The Archway REST API is namespaced under /api/v1. All endpoints accept and return JSON unless otherwise noted. Base URL: https://archdiagram.dev.
Every /api/v1 endpoint accepts either a session cookie (browser usage) or a Bearer API key. API keys are created from Dashboard → API Keys and are prefixed with ak_. The full key value is shown only once at creation time; only a salted hash is stored server-side.
curl https://archdiagram.dev/api/v1/diagrams \ -H "Authorization: Bearer ak_..." \ -H "Content-Type: application/json"
API keys carry one or more permission scopes: read, write, and generate. Mutating endpoints require write; AI-backed endpoints additionally require generate. A request with a missing scope returns 403.
Rate limits are per-user, per-minute, and apply to the union of session and API-key traffic. AI-backed endpoints (any call that accepts a prompt) consume against a separate ai bucket as well as the shared api bucket. When a limit trips, the response is 429 with X-RateLimit-Remaining: 0 and X-RateLimit-Reset (milliseconds).
The v1 surface today covers list, read, create, update, AI regeneration, and export. There is no v1 DELETE endpoint — deletions are currently performed through the dashboard UI or via the legacy /api/diagram routes used by the web app itself.
/api/v1/diagramsSCOPE: READList diagrams owned by the authenticated user, paginated and sorted by most recently updated.
Query parameters:
pageINTEGER11-indexed page number.limitINTEGER20Page size, max 100.typeSTRING—Filter by diagramType (cloud-arch, sequence, erd, data-flow, c4, flowchart, network).{
"diagrams": [
{
"id": "65f1...",
"title": "Checkout flow",
"diagramType": "cloud-arch",
"sourceType": "text",
"tags": [],
"visibility": "private",
"createdAt": "2026-04-01T...",
"updatedAt": "2026-04-12T..."
}
],
"pagination": { "page": 1, "limit": 20, "total": 47, "totalPages": 3 }
}/api/v1/diagramsSCOPE: WRITE (AND GENERATE, IF A PROMPT IS SUPPLIED)Create a new diagram. Either pass dslSource for a deterministic create, or pass prompt to have the AI generate the DSL.
titleSTRING—Required. Display title.diagramTypeSTRINGcloud-archOne of the seven diagram types.dslSourceSTRING""Raw DSL source. Used directly if provided.promptSTRING—If set, calls the AI generator. Counts against AI credits.preferredProviderSTRING—Optional AI provider hint passed to the generator.projectIdSTRING—Project to attach to. Falls back to the user's first project if omitted.{
"id": "65f1...",
"title": "Checkout flow",
"diagramType": "cloud-arch",
"dslSource": "diagram \"Checkout flow\" { ... }",
"createdAt": "2026-04-14T..."
}400title missing or no project exists for the user403API key lacks write or generate scope429AI credit limit reached, or rate limit exceeded/api/v1/diagrams/[id]SCOPE: READFetch a single diagram, including the full DSL source and metadata.
{
"id": "65f1...",
"title": "Checkout flow",
"diagramType": "cloud-arch",
"dslSource": "diagram \"...\" { ... }",
"metadata": {
"nodeCount": 14,
"sourceType": "text",
"lastAiModel": "claude-sonnet-4-5",
"tags": []
},
"sharing": { "visibility": "private", "allowEmbed": false },
"isFavorite": false,
"createdAt": "...",
"updatedAt": "..."
}404No diagram with that id owned by the caller/api/v1/diagrams/[id]SCOPE: WRITEUpdate a diagram. Only title, dslSource, and diagramType are accepted; other fields in the body are ignored.
titleSTRING—Optional new title.dslSourceSTRING—Optional replacement DSL.diagramTypeSTRING—Optional diagram-type change.{
"id": "65f1...",
"title": "Checkout flow v2",
"diagramType": "cloud-arch",
"dslSource": "diagram \"...\" { ... }",
"updatedAt": "..."
}400No allowed fields were provided403API key lacks write scope404Diagram not found/api/v1/diagrams/[id]/generateSCOPE: GENERATERegenerate the DSL of an existing diagram from a natural-language prompt. Replaces dslSource on success.
promptSTRING—Required. Description of what the diagram should look like.diagramTypeSTRING(diagram's current type)Optional override.preferredProviderSTRING—Optional AI provider hint.{
"id": "65f1...",
"dsl": "diagram \"...\" { ... }",
"diagramType": "cloud-arch",
"description": "Short summary of the generated diagram",
"model": "claude-sonnet-4-5",
"retries": 0
}400prompt missing403API key lacks generate scope404Diagram not found429Rate limit or AI credit cap reached503AI service is not configured on the server/api/v1/diagrams/[id]/exportSCOPE: READExport the diagram source. Today this returns the raw Archway DSL for text formats; mermaid/plantuml/d2 transpilation is not yet implemented and returns the same DSL with the matching file extension.
Query parameters:
formatSTRINGdslOne of: dsl, json, mermaid, plantuml, d2.For format=json, the response is the full diagram document (id, title, diagramType, dslSource, metadata, timestamps). For all other formats, the response is a text/plain body containing the DSL source with a Content-Disposition: attachment header. Two extra response headers are set: X-Diagram-Type and X-Export-Format.
400Unsupported format value404Diagram not foundThe endpoints under /api/keys are not part of v1 and are session-only (cookie auth). They power the dashboard UI: GET /api/keys lists the user's keys (without secrets), POST /api/keys issues a new key (returning the raw value exactly once, capped at 10 active keys per user), and DELETE /api/keys/[id] revokes a key by flipping isActive to false. Both creation and revocation emit security audit events.
All error responses share the same envelope. Status codes follow standard HTTP semantics.
{
"error": "Diagram not found"
}Validation failures may include an additional details field with field-level information.