[SPECIFICATION]

API Reference

REST API for programmatic diagram management. All endpoints require authentication via session cookie or API key.

00

AUTHENTICATION

All API requests require authentication. Include your session cookie (automatic in browser) or pass an API key via the Authorization header.

Authorization: Bearer <your-api-key>

# Rate limits
# Free:  100 requests/minute
# Pro:   500 requests/minute
# Team: 1000 requests/minute
01

ENDPOINTS

GET/api/diagram

List all diagrams for the authenticated user

RESPONSE: { diagrams: DiagramListItem[] }
POST/api/diagram

Create a new diagram

BODY: { title, diagramType, projectId }RESPONSE: { diagram: Diagram }
GET/api/diagram/:id

Get a specific diagram with full DSL source

RESPONSE: { _id, title, diagramType, dslSource, ... }
PATCH/api/diagram/:id

Update diagram title, DSL source, or metadata

BODY: { title?, dslSource?, diagramType? }RESPONSE: { diagram: Diagram }
DELETE/api/diagram/:id

Delete a diagram permanently

RESPONSE: { success: true }
POST/api/ai/generate

Generate DSL from a natural language prompt

BODY: { prompt, diagramType }RESPONSE: { dsl: string, description: string }
POST/api/ai/edit

AI-edit an existing diagram with an instruction

BODY: { instruction, diagramType, currentDsl }RESPONSE: { dsl: string, description: string }
POST/api/ai/image

Convert an uploaded image to DSL

BODY: FormData { image: File, diagramType: string }RESPONSE: { dsl: string }
GET/api/templates

List available templates with optional filters

RESPONSE: { templates: Template[] }
POST/api/templates/:id/use

Create a new diagram from a template

RESPONSE: { diagram: Diagram }
POST/api/diagram/:id/share

Create a share link for a diagram

BODY: { access: "view"|"comment"|"edit", allowEmbed? }RESPONSE: { link: ShareLink }
GET/api/diagram/:id/versions

Get version history for a diagram

RESPONSE: { versions: Version[], total: number }