REST API Reference

Last updated: March 2026

The Diagram2Code REST API lets you convert Mermaid ER and PlantUML entity diagrams to SQL DDL or ORM model code directly over HTTP — no browser required. It is designed for use in CI/CD pipelines, editor plugins, code-generation scripts, and any workflow where you want to automate schema generation from diagram source files.

All requests and responses use JSON. The API is versioned under /v1/. Breaking changes will be introduced in a new version prefix rather than modifying existing endpoints.

Base URL

https://diagram2code.com/api

All endpoint paths below are relative to this base. Use HTTPS exclusively — plain HTTP requests are not supported.

POST /v1/convert/sql

Converts a Mermaid or PlantUML ER diagram to SQL DDL for a specific database dialect. The generated DDL includes CREATE TABLE statements, primary keys, foreign key constraints, unique constraints, indexes, and any directives embedded in the source diagram.

Request

Response — 200 OK

{
  "diagramType": "mermaid",
  "database": "postgres",
  "diagram": "erDiagram\n  USER {\n    int id PK\n    string email UK\n    string name\n  }\n  POST {\n    int id PK\n    int user_id FK\n    string title\n  }\n  USER ||--o{ POST : writes"
}

{
  "sql": "CREATE TABLE \"user\" (\n  \"id\" SERIAL PRIMARY KEY,\n  \"email\" TEXT UNIQUE NOT NULL,\n  \"name\" TEXT NOT NULL\n);\n\nCREATE TABLE \"post\" (\n  \"id\" SERIAL PRIMARY KEY,\n  \"user_id\" INTEGER NOT NULL REFERENCES \"user\"(\"id\"),\n  \"title\" TEXT NOT NULL\n);",
  "metadata": {
    "dialect": "postgres",
    "tableCount": 2,
    "schemaVersion": "1"
  },
  "warnings": []
}

POST /v1/convert/orm

Converts a Mermaid or PlantUML ER diagram to ORM model code in the target language and framework. The free tier supports GORM (Go) without an API key. All other frameworks — SQLAlchemy, TypeORM, Prisma, JPA, Django ORM, Sequelize, and Entity Framework Core — require a Developer or higher tier key.

Request

Response — 200 OK

GET /v1/health

Returns a simple liveness signal. Useful for monitoring integrations and load-balancer health checks. This endpoint is always unauthenticated and not subject to rate limits.

GET https://diagram2code.com/api/v1/health

A healthy response is 200 OK with body {"status":"ok"}. Any non-200 response indicates a service disruption.

Rate Limits & Quotas

Every request is subject to two independent limits: a per-minute rate limit (burst protection) and a monthly conversion quota (overall usage cap). Both limits are tracked per API key, or per IP address for anonymous requests.

When the rate limit is exceeded the API returns 429 Too Many Requests with error code RATE_LIMITED. When the monthly quota is exhausted it returns 429 with error code QUOTA_EXCEEDED. In both cases the response body follows the standard error envelope below.

The GET /v1/health endpoint is exempt from rate limiting. The conversion quota resets on the first calendar day of each month (UTC).

Error Reference

All error responses share the same JSON envelope regardless of HTTP status code:

{
  "error": {
    "code": "PARSE_ERROR",
    "message": "line 3:5: unexpected token 'USERS'",
    "details": {
      "phase": "parsing",
      "line": 3,
      "column": 5
    }
  }
}

The code field is machine-readable and stable across API versions. The message field is a human-readable description intended for debugging. The details object is optional and varies by error type.

Curl Examples

1. Mermaid diagram → PostgreSQL DDL

curl -X POST https://diagram2code.com/v1/convert/sql \
  -H "Content-Type: application/json" \
  -d '{
    "diagramType": "mermaid",
    "database": "postgres",
    "diagram": "erDiagram\n  CUSTOMER {\n    int id PK\n    string email UK\n    string name\n  }\n  ORDER {\n    int id PK\n    int customer_id FK\n    decimal total\n    timestamp created_at\n  }\n  CUSTOMER ||--o{ ORDER : places"
  }'

2. PlantUML diagram → MySQL DDL

curl -X POST https://diagram2code.com/v1/convert/sql \
  -H "Content-Type: application/json" \
  -d '{
    "diagramType": "plantuml",
    "database": "mysql",
    "diagram": "@startuml\nentity Product {\n  * id : int <<PK>>\n  name : string\n  price : decimal\n  sku : string <<UNIQUE>>\n}\n@enduml"
  }'

3. Mermaid diagram → GORM model (free tier)

curl -X POST https://diagram2code.com/v1/convert/orm \
  -H "Content-Type: application/json" \
  -d '{
    "diagramType": "mermaid",
    "framework": "gorm",
    "diagram": "erDiagram\n  USER {\n    int id PK\n    string username UK\n    string email UK\n    timestamp created_at\n  }\n  PROFILE {\n    int id PK\n    int user_id FK\n    string bio\n  }\n  USER ||--|| PROFILE : has"
  }'

4. Mermaid diagram → SQLAlchemy model (Developer+ tier)

curl -X POST https://diagram2code.com/v1/convert/orm \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_api_key_here" \
  -d '{
    "diagramType": "mermaid",
    "framework": "sqlalchemy",
    "diagram": "erDiagram\n  ARTICLE {\n    int id PK\n    string title\n    text body\n    int author_id FK\n  }"
  }'

5. Health check

curl https://diagram2code.com/v1/health

Troubleshooting

PARSE_ERROR — "expected erDiagram keyword"

Every Mermaid diagram must begin with the literal keyword erDiagram (exact casing, on its own line or followed by whitespace). If your diagram text starts with anything else — a comment, a blank line, or a different Mermaid diagram type — the parser will reject it. Strip any leading whitespace or %% comment lines before sending the diagram.

PARSE_ERROR with line/column details

When the error response includes details.line and details.column, navigate to that position in the source diagram. Common causes: a column name containing a space (not supported — use snake_case), a missing closing brace } at the end of an entity block, or an unquoted string used as a comment.

VALIDATION_ERROR — "foreign key references unknown table"

A column marked FK in Mermaid (or <<FK>> in PlantUML) must have a corresponding relationship line that names the target table. For example, if ORDER has a column customer_id FK, the diagram must include a line such as CUSTOMER ||--o{ ORDER : places so the generator can resolve the foreign key target. Add the missing relationship and resubmit.

FORBIDDEN — "framework X requires a Developer or higher plan"

GORM is the only ORM framework available on the free (anonymous) tier. SQLAlchemy, TypeORM, Prisma, JPA, Django ORM, Sequelize, and Entity Framework Core all require a Developer API key supplied via the X-Api-Key header. To use the GORM-free tier, set "framework": "gorm" or omit the header and use an anonymous request.

429 — rate limit vs quota exceeded

Both rate-limit and quota errors return HTTP 429, but they have different code values in the response body. RATE_LIMITED means you sent too many requests within the current minute — wait 60 seconds and retry. QUOTA_EXCEEDED means you have used all conversions allocated for the current calendar month — the quota resets at midnight on the first day of the next month (UTC).