FlowchartAI developer documentation · v1

Generate a diagram. Keep it editable.

Use the REST API from your application or connect an MCP client. Both use the same saved diagrams, account allowance and developer budgets.

1. Create a scoped API key

Sign in to the developer dashboard. Create a key with diagrams:generate and diagrams:write; add read, export, task and account permissions for the complete workflow. Copy the key once and store it as a server environment variable. Send Authorization: Bearer … or X-API-Key. Keys cannot log in to the website.

2. Generate and save

Set FLOWCHART_API_KEY in your shell, then run this request with cURL and jq. Choose a unique idempotency key for each new operation and keep it unchanged for retries. The successful response includes the saved file, a content version and a link to its website editor.

curl --max-time 300 https://flowchartai.org/api/v1/generations \
  -H "Authorization: Bearer $FLOWCHART_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: onboarding-flow-001' \
  -d '{"prompt":"Map signup, email verification and activation, including an expired-link retry.","max_credits":100}' \
  > task.json

jq '{id,state,charged_credits,diagram}' task.json

3. Edit, reopen and export

To edit an existing diagram, send its ID and latest expected_version. The version covers changes made in the website, too. A stale version returns 409 version_conflict. read the file again and review it before retrying with a new operation key. Successful edits are saved automatically.

ID=$(jq -r '.diagram_id' task.json)
VERSION=$(jq -r '.diagram.version' task.json)

jq -n --arg id "$ID" --arg version "$VERSION" \
  '{diagram_id:$id,expected_version:$version,
    prompt:"Add a welcome email after activation.",max_credits:100}' \
  > edit.json

curl --max-time 300 https://flowchartai.org/api/v1/generations \
  -H "Authorization: Bearer $FLOWCHART_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: onboarding-edit-001' \
  --data-binary @edit.json > edited-task.json

curl "https://flowchartai.org/api/v1/diagrams/$ID/export?format=drawio" \
  -H "Authorization: Bearer $FLOWCHART_API_KEY" \
  -o onboarding.drawio

Open diagram.open_url to continue editing on the website. API exports return editable draw.io XML or the original JSON. The website editor also renders SVG and PNG. Read, manual save and export do not incur AI charges.

Task states and uncertain responses

Generation executes synchronously for up to 240 seconds. A request may take several model steps. Its receipt is persisted before execution. States are running → prepared → succeeded, or failed. A concurrent duplicate returns the current receipt and starts no second model call. List /tasks, read /tasks/ID, or repeat the exact request and key after a timeout. Reading a prepared receipt can finish delivery without regenerating. An interrupted running task becomes failed after six minutes when read. Start a new operation only after checking the terminal receipt.

Usage, limits and charges

AI operations share your existing Credits or eligible legacy subscription allowance. Every generation requires max_credits, between 1 and 2,000. The server may reserve less using the full prompt, image and native-document context. A cap below this estimate returns 409 with required_credits before generation; review the amount before increasing your cap. The receipt retains budget_credits and reports the active reservation and actual charge. Full-task usage includes every model call. Settlement never exceeds the accepted reservation. Failed delivery and platform corrections do not create an extra user charge.

The account and credential each have daily credit and AI-request budgets, resetting at 00:00 UTC. Active reservations count toward the credit budget. The account is limited to 120 authenticated requests per minute across all credentials. A key defaults to 60 requests per minute; its owner can choose up to 120. API, MCP and website AI tasks share the wallet's single active-task rule. A rate or budget limit returns 429; wait for its reset instead of cycling keys. See the current allowance on Pricing.

Connect an MCP client

Remote endpoint: https://flowchartai.org/api/mcp. Transport: Streamable HTTP. Add this URL to a client supporting remote MCP and OAuth. It opens FlowchartAI sign-in and a permission screen; review the app name, return destination and permissions before allowing it. Revoke connections from the developer dashboard.

For clients supporting custom request headers, use an API key. Configuration syntax varies by client; this is a common JSON shape. Keep the key in the client's secret store when available.

{
  "mcpServers": {
    "flowchartai": {
      "url": "https://flowchartai.org/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_FLOWCHARTAI_KEY" }
    }
  }
}

Discovery: /.well-known/oauth-protected-resource/api/mcp and /.well-known/oauth-authorization-server. The server supports dynamic public-client registration, authorization-code PKCE S256, exact registered redirects and resource https://flowchartai.org/api/mcp. Access tokens last 10 minutes. Request offline_access for a rotating refresh token lasting up to 30 days. Refresh reuse revokes the connection. Dashboard revocation blocks both token types immediately. OAuth tokens are accepted only by MCP.

Tools: get_capabilities, get_account, create_flowchart, edit_flowchart, list_flowcharts, get_flowchart, save_flowchart, list_flowchart_versions, export_flowchart, get_task, list_tasks. Ask the assistant to read the latest file before editing, set a credit maximum and keep the operation key stable after an uncertain response.

REST endpoint reference

Paths are relative to /api/v1. Lists return 20 records and an optional next_cursor. Every write requires Idempotency-Key. A manual save body is {"title":"…","document":{…},"expected_version":"…"}. Omit the version for a new file. Follow OpenAPI's NativeDocument schema. Native XML is limited to 2 MB and 2,000 objects. Images are one base64 PNG, JPEG or WebP of at most 2 MB; arbitrary image URLs are not fetched. Legacy files remain readable and exportable as JSON; native AI editing requires draw.io format.

Errors and recovery

Errors use {"error":{"code":"…","message":"…"}}. 401: invalid, expired or revoked credential. 403: missing permission or unavailable account. 402: insufficient Credits. 409: busy task, changed file or conflicting idempotency key. 413: oversized input. 422: unsupported format or no usable diagram. 429: rate or daily budget limit. 502/503: upstream or database unavailable. Never put prompts, API keys or tokens in URLs or client logs.

Rotating a key immediately revokes its old secret. Reconnecting OAuth creates a new grant and cannot reactivate revoked tokens. Task IDs, response states and content hashes let you reconcile results independently of a network response.