Skip to content

API Reference

Smoothdev provides REST and GraphQL APIs for programmatic access to documentation generation.

Overview

The Smoothdev API enables programmatic generation of commit messages, PR summaries, release notes, and repository documentation. The API uses GraphQL for generation operations and REST for key management.

When to Use It

  • Integrate documentation generation into custom tooling
  • Build automation workflows outside of the CLI or GitHub Actions
  • Access generation capabilities from non-supported platforms

How It Works

  1. Authenticate using an API key or JWT token
  2. Send a GraphQL mutation to start a generation workflow
  3. Poll the workflow status until completion
  4. Retrieve the generated artifact

Configuration

Base URLs

Service URL
REST API https://rest.production.smoothdev.io
GraphQL https://ai.production.smoothdev.io/graphql
Auth0 https://auth.production.smoothdev.io

Authentication

All API requests require authentication using one of these methods:

API Key (Recommended for CI/CD)

curl -X POST https://ai.production.smoothdev.io/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "..."}'

JWT Token (Interactive)

curl -X POST https://ai.production.smoothdev.io/graphql \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "..."}'

Output Behavior

Generation Mutations

All generation mutations return an executionId and status:

mutation GenerateCommit($input: CommitGenerationInput!) {
  generateCommit(input: $input) {
    executionId
    status
  }
}

Workflow Status Values

  • PENDING - Workflow queued
  • RUNNING - Workflow in progress
  • SUCCEEDED - Workflow completed successfully
  • FAILED - Workflow failed

Error Response Format

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or expired token"
  }
}
Code HTTP Status Description
AUTHENTICATION_ERROR 401 Invalid or missing authentication
AUTHORIZATION_ERROR 403 Insufficient permissions
RATE_LIMIT_EXCEEDED 429 Too many requests
VALIDATION_ERROR 400 Invalid request parameters
INTERNAL_ERROR 500 Server error

Security and Data Handling

Smoothdev encrypts customer data in transit and at rest using tenant-scoped encryption keys. Source data is processed only for the requested operation and is not retained long term. Generated artifacts are returned to the user. Operational metrics and validation logs are retained to improve system reliability and quality.

Limitations

  • Rate limiting: 100 requests per minute per API key
  • Maximum request payload: 1MB
  • Maximum diff size: 100KB for commit generation
  • GraphQL query depth limit: 10 levels
  • Concurrent requests per tenant: 10
  • API keys are scoped to the creating user's tenant

Troubleshooting

Error Cause Resolution
AUTHENTICATION_ERROR Invalid or expired token Refresh JWT or verify API key
RATE_LIMIT_EXCEEDED Too many requests Wait and retry with exponential backoff
VALIDATION_ERROR Missing required fields Check input schema requirements
Timeout polling status Large generation request Increase poll timeout; check workflow logs

GraphQL Mutations

Generate Commit Message

mutation GenerateCommit($input: CommitGenerationInput!) {
  generateCommit(input: $input) {
    executionId
    status
  }
}

Variables:

{
  "input": {
    "repository": "owner/repo",
    "diff": "...",
    "baseRef": "main",
    "headRef": "feature/my-feature"
  }
}

Generate PR Summary

mutation GeneratePRSummary($input: PRGenerationInput!) {
  generatePRSummary(input: $input) {
    executionId
    status
  }
}

Generate Release Notes

mutation GenerateReleaseNotes($input: ReleaseGenerationInput!) {
  generateReleaseNotes(input: $input) {
    executionId
    status
  }
}

Generate Repository Documentation

mutation GenerateRepoDocs($input: RepoDocsGenerationInput!) {
  generateRepoDocs(input: $input) {
    executionId
    status
  }
}

Modes: LITE (quick overview) or FULL (comprehensive)

Check Workflow Status

query GetWorkflowExecution($id: ID!) {
  getWorkflowExecution(executionId: $id) {
    executionId
    status
    currentStep
  }
}

Get Workflow Result

query GetWorkflowResult($id: ID!) {
  getWorkflowExecutionResult(executionId: $id)
}

REST Endpoints

API Key Management

List API Keys

GET https://rest.production.smoothdev.io/keys
Authorization: Bearer <jwt_token>

Create API Key

POST https://rest.production.smoothdev.io/keys
Authorization: Bearer <jwt_token>
Content-Type: application/json

{"name": "My CI/CD Key"}

Delete API Key

DELETE https://rest.production.smoothdev.io/keys/{key_id}
Authorization: Bearer <jwt_token>

Rotate API Key

POST https://rest.production.smoothdev.io/keys/{key_id}/rotate
Authorization: Bearer <jwt_token>

Code Examples

Python

import requests

API_KEY = "your_api_key"
GRAPHQL_URL = "https://ai.production.smoothdev.io/graphql"

def generate_commit(repository: str, diff: str) -> dict:
    query = """
    mutation GenerateCommit($input: CommitGenerationInput!) {
      generateCommit(input: $input) {
        executionId
        status
      }
    }
    """
    response = requests.post(
        GRAPHQL_URL,
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        json={"query": query, "variables": {"input": {"repository": repository, "diff": diff}}}
    )
    return response.json()

cURL

curl -X POST https://ai.production.smoothdev.io/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation GenerateCommit($input: CommitGenerationInput!) { generateCommit(input: $input) { executionId status } }", "variables": {"input": {"repository": "owner/repo", "diff": "..."}}}'

See Also