API Reference

All diagram conversion features are available as a REST API. The API accepts and returns JSON. The base URL for production is https://diagram2code.com/api.

Authentication

Anonymous requests (no API key) are allowed for all endpoints up to the rate limit and monthly quota.

Rate Limits & Quotas

The API is rate-limited to 10 requests per minute and 100 calls per month per IP address.

Rate limit status is returned in response headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-Quota-Used: 32
X-Quota-Limit: 100

Error Envelope

All non-2xx responses return a JSON error envelope:

{
  "error": {
    "code": "INPUT_ERROR",
    "message": "missing required field: diagram",
    "details": { "phase": "parsing" }
  }
}

GET /v1/health

Health check endpoint. Returns 200 when the server is up.

GET /api/v1/health

{ "status": "ok" }

POST /v1/convert/sql

Convert a diagram to SQL DDL for a specific database.

Request body

{
  "diagramType": "mermaid",
  "database":    "postgres",
  "diagram":     "erDiagram\n    USER { int id PK }\n"
}

Success response 200

{
  "sql": "CREATE TABLE \"user\" (\n    \"id\" SERIAL PRIMARY KEY\n);\n",
  "metadata": {
    "dialect":       "postgres",
    "tableCount":    1,
    "schemaVersion": "v1"
  }
}

POST /v1/convert/orm

Convert a diagram to ORM model code.

Request body

{
  "diagramType": "mermaid",
  "framework":   "gorm",
  "diagram":     "erDiagram\n    USER { int id PK }\n"
}

Success response 200

{
  "code": "package models\n\ntype User struct { … }\n",
  "metadata": {
    "framework":   "gorm",
    "language":    "go",
    "tableCount":  1
  }
}

POST /v1/diff

Compare two diagram versions and return a structured list of schema changes.

Request body

{
  "oldDiagramType": "mermaid",
  "oldDiagram":     "erDiagram\n    USER { int id PK }\n",
  "newDiagramType": "mermaid",
  "newDiagram":     "erDiagram\n    USER { int id PK\n    string email }\n"
}

Success response 200

{
  "changes": [
    {
      "op":          "ADD_COLUMN",
      "table":       "USER",
      "column":      "email",
      "destructive": false,
      "description": "Add column email to table USER"
    }
  ],
  "summary": {
    "total":            1,
    "additions":        1,
    "deletions":        0,
    "modifications":    0,
    "destructiveCount": 0
  }
}

Rate Limiting Responses

When you exceed the per-minute rate limit, the API returns 429 with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "too many requests - try again in 42s"
  }
}