HTTP API
API reference
Check, render, and describe diagrams written in a small line-oriented language (flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, swimlane). Built for AI agents: every error carries a line, column, and fix hint, and the language reference is served as data. The same operations are available as MCP tools.
TL;DR
| Question | Answer |
|---|---|
| What format? | JSON in, JSON out. Every body is described by a schema, and each endpoint page links the ones it uses. |
| Where is the live spec? | GET /openapi.json returns OpenAPI 3.1; GET /docs serves an interactive page. |
| What does an error look like? | One envelope for every failure; see "Error envelope". A diagram with mistakes is a normal result from the validate route and a 422 from the render and outline routes. |
| Where does it run? | The hosted API is at https://api.plotwork.dev, and every path below is relative to that address. Calling the drawing and checking routes needs an API key and the Pro plan. |
| Which endpoints draw diagrams? | The ones under /v1: each serves a tool of the tool reference, and its page names the tool. |
Endpoints
130 endpoints, each with a page of its own. They are grouped by what they do.
Diagrams
| Method | Path | What it does |
|---|---|---|
| POST | /v1/diagrams/draw | Check, describe, and draw a diagram. |
| POST | /v1/diagrams/edit | Change diagram source with small typed operations. |
| POST | /v1/diagrams/convert-mermaid | Convert one Mermaid diagram. |
| POST | /v1/diagrams/validate | Check diagram source. |
| POST | /v1/diagrams/render | Render diagram source to SVG. |
| POST | /v1/diagrams/outline | Describe diagram source as text. |
| POST | /v1/diagrams/read | Read the source back out of a Plotwork SVG. |
| POST | /v1/diagrams/compare | Say what changed between two versions of a diagram. |
| POST | /v1/diagrams/suggest | Choose the kind of diagram for a request. |
| POST | /v1/import | Turn a file of another format into a diagram. |
Icons
| Method | Path | What it does |
|---|---|---|
| POST | /v1/icons/map | Choose icons for many names at once. |
| GET | /v1/icons | Find bundled icon names. |
Markdown
| Method | Path | What it does |
|---|---|---|
| POST | /v1/markdown/sync | Turn a document's diagram fences into pictures. |
| POST | /v1/markdown/plan | Find the sections of a document a picture would help. |
Patterns
| Method | Path | What it does |
|---|---|---|
| POST | /v1/patterns/find | Find a ready-made architecture diagram. |
| POST | /v1/patterns/get | Read a pattern filled for a flavour. |
| POST | /v1/patterns/draw | Fill a pattern and draw it. |
Vocabulary
| Method | Path | What it does |
|---|---|---|
| GET | /v1/vocabulary | Get the diagram language reference. |
Auth
| Method | Path | What it does |
|---|---|---|
| POST | /auth/code | Email a sign-in code. |
| POST | /auth/verify | Sign in with a code. |
| POST | /auth/logout | Sign out. |
| POST | /auth/sso/discover | Ask whether an address signs in with single sign-on. |
| POST | /auth/sso/start | Start signing in through an organisation's identity provider. |
| GET | /auth/sso/callback | Finish signing in through an identity provider. |
| GET | /auth/sso/saml/{org}/metadata | Read an organisation's SAML service provider metadata. |
| POST | /auth/sso/saml/{org}/acs | Finish signing in through a SAML identity provider. |
Keys
| Method | Path | What it does |
|---|---|---|
| GET | /user/me | Read the signed-in account. |
| GET | /user/api-keys | List your API keys. |
| POST | /user/api-keys | Create an API key. |
| POST | /user/api-keys/{id}/reveal | Reveal an API key. |
| DELETE | /user/api-keys/{id} | Revoke an API key. |
| GET | /user/usage | Read the account's usage. |
Connections
| Method | Path | What it does |
|---|---|---|
| POST | /user/mcp/approve | Approve a request to connect an agent. |
| GET | /user/mcp/connections | List the agents you have connected. |
| DELETE | /user/mcp/connections/{keyId} | Disconnect an agent. |
Hosting
| Method | Path | What it does |
|---|---|---|
| POST | /v1/diagrams/publish | Publish a diagram and get a link. |
| GET | /user/diagrams | List your hosted diagrams. |
| PATCH | /user/diagrams/{id} | File a hosted diagram in a folder. |
| DELETE | /user/diagrams/{id} | Delete a hosted diagram. |
| PUT | /user/diagrams/{id}/lock | Lock a hosted diagram. |
| DELETE | /user/diagrams/{id}/lock | Unlock a hosted diagram. |
| PUT | /user/diagrams/{id}/source | Save edited source over a hosted diagram. |
| GET | /user/diagrams/{id}/versions | List a hosted diagram's previous versions. |
| POST | /user/diagrams/{id}/versions/{versionId}/restore | Restore a previous version of a hosted diagram. |
| POST | /user/stable-links | Point a stable link at one of your diagrams. |
| DELETE | /user/stable-links/{id} | Delete a stable link. |
| GET | /oembed | Describe a diagram link for an embedder (oEmbed). |
Organisations
| Method | Path | What it does |
|---|---|---|
| GET | /orgs | List your organisations. |
| POST | /orgs | Create an organisation. |
| GET | /orgs/{org} | Read an organisation. |
| PATCH | /orgs/{org} | Rename an organisation. |
| DELETE | /orgs/{org} | Delete an organisation. |
| GET | /orgs/{org}/members | List an organisation's members. |
| PATCH | /orgs/{org}/members/{userId} | Change a member's role. |
| DELETE | /orgs/{org}/members/{userId} | Remove a member, or leave. |
| GET | /orgs/{org}/invites | List an organisation's pending invitations. |
| POST | /orgs/{org}/invites | Invite an address to an organisation. |
| DELETE | /orgs/{org}/invites/{id} | Revoke an invitation. |
| POST | /orgs/invites/accept | Accept an invitation. |
| GET | /orgs/{org}/diagrams | List an organisation's diagrams. |
| POST | /orgs/{org}/diagrams | Publish a diagram to an organisation. |
| GET | /orgs/{org}/diagrams/{id}/svg | Download an organisation diagram's SVG. |
| PATCH | /orgs/{org}/diagrams/{id} | File or rename an organisation diagram. |
| DELETE | /orgs/{org}/diagrams/{id} | Delete an organisation diagram. |
| PUT | /orgs/{org}/diagrams/{id}/lock | Lock an organisation diagram. |
| DELETE | /orgs/{org}/diagrams/{id}/lock | Unlock an organisation diagram. |
| PUT | /orgs/{org}/diagrams/{id}/source | Save edited source over an organisation diagram. |
| GET | /orgs/{org}/diagrams/{id}/versions | List an organisation diagram's previous versions. |
| POST | /orgs/{org}/diagrams/{id}/versions/{versionId}/restore | Restore a previous version of an organisation diagram. |
| PUT | /orgs/{org}/editable | Keep an organisation's diagrams editable. |
| PUT | /orgs/{org}/publishing | Choose where an organisation's members publish. |
| GET | /orgs/{org}/publishing/public-diagrams | List members' public diagrams for review. |
| POST | /orgs/{org}/publishing/public-diagrams/{id}/move | Move a member's public diagram into the library. |
| DELETE | /orgs/{org}/publishing/public-diagrams/{id} | Unpublish a member's public diagram. |
| GET | /user/publishing | Read where your publishes go. |
| PUT | /user/publishing | Choose your default organisation for publishing. |
| GET | /orgs/{org}/folder-rules | List an organisation's folder rules. |
| PUT | /orgs/{org}/folder-rules | Restrict a folder. |
| DELETE | /orgs/{org}/folder-rules | Remove a folder's rule. |
| GET | /orgs/{org}/keys | List an organisation's API keys. |
| POST | /orgs/{org}/keys | Create an organisation API key. |
| POST | /orgs/{org}/keys/{id}/reveal | Reveal an organisation API key. |
| DELETE | /orgs/{org}/keys/{id} | Revoke an organisation API key. |
| GET | /orgs/{org}/brand | Read an organisation's brand theme. |
| PUT | /orgs/{org}/brand | Save an organisation's brand theme. |
| DELETE | /orgs/{org}/brand | Remove an organisation's brand theme. |
| POST | /orgs/{org}/brand/preview | Preview brand colors. |
| GET | /user/brand | Read the brand of your own calls. |
| PUT | /user/brand | Choose the brand of your own calls. |
| GET | /orgs/{org}/style-rules | Read an organisation's style rules. |
| PUT | /orgs/{org}/style-rules | Save an organisation's style rules. |
| DELETE | /orgs/{org}/style-rules | Remove an organisation's style rules. |
| GET | /orgs/{org}/icons | List an organisation's custom icons. |
| PUT | /orgs/{org}/icons/{name} | Upload or replace a custom icon. |
| DELETE | /orgs/{org}/icons/{name} | Delete a custom icon. |
| GET | /orgs/{org}/icons/{name}/preview | Preview a custom icon in a diagram. |
| GET | /orgs/{org}/avatar | Read an organisation's avatar. |
| PUT | /orgs/{org}/avatar | Upload or replace an organisation's avatar. |
| DELETE | /orgs/{org}/avatar | Remove an organisation's avatar. |
| POST | /orgs/{org}/drift/runs | Report a drift run from CI. |
| GET | /orgs/{org}/drift | Read an organisation's drift dashboard. |
| GET | /orgs/{org}/audit | Read an organisation's audit log. |
| GET | /orgs/{org}/audit/export | Export an organisation's audit log. |
| GET | /orgs/{org}/sso | Read an organisation's single sign-on settings. |
| PUT | /orgs/{org}/sso/connection | Set up an OpenID Connect identity provider. |
| PATCH | /orgs/{org}/sso/connection | Turn single sign-on on or off, and set Require SSO and who joins on first sign-in. |
| DELETE | /orgs/{org}/sso/connection | Remove the identity provider. |
| PUT | /orgs/{org}/sso/saml | Set up a SAML identity provider. |
| POST | /orgs/{org}/sso/domains | Add an email domain. |
| POST | /orgs/{org}/sso/domains/{domain}/verify | Check a domain's DNS record. |
| DELETE | /orgs/{org}/sso/domains/{domain} | Remove an email domain. |
| GET | /orgs/{org}/scim | Read an organisation's SCIM settings. |
| POST | /orgs/{org}/scim/token | Make or rotate the SCIM token. |
| DELETE | /orgs/{org}/scim/token | Revoke the SCIM token. |
| PATCH | /orgs/{org}/scim/groups/{group} | Choose the role a SCIM group gives. |
| GET | /orgs/{org}/support | Read what priority support is for an organisation. |
| POST | /orgs/{org}/support/requests | Ask the organisation's named contact for help. |
Billing
| Method | Path | What it does |
|---|---|---|
| GET | /user/billing | Read the account's plan. |
| POST | /user/billing/checkout | Start a checkout for a paid plan. |
| POST | /user/billing/verify-checkout | Read a finished checkout back. |
| POST | /user/billing/cancel | Cancel the plan at the end of the period. |
| POST | /user/billing/resume | Take back a cancellation. |
| POST | /user/billing/portal | Open the Stripe billing portal. |
| GET | /user/billing/documents | List your invoices and receipts. |
| GET | /user/billing/documents/{id} | Read one invoice or receipt. |
| GET | /user/billing/documents/{id}/pdf | Download an invoice or receipt as a PDF. |
| POST | /billing/webhook | Receive a Stripe event. Called by Stripe, not by clients. |
Enterprise
| Method | Path | What it does |
|---|---|---|
| POST | /enterprise/enquiries | Send an Enterprise enquiry. |
Telemetry
| Method | Path | What it does |
|---|---|---|
| POST | /telemetry/usage | Receive the opt-in daily totals of the local npm package. |
Health
| Method | Path | What it does |
|---|---|---|
| GET | /health | Check the service is up. |
Error envelope
Every failure uses the same shape, so a client needs one error handler.
| Field | Type | Required | Description |
|---|---|---|---|
error | true | yes | Always true, so clients can branch without reading the status. |
errorCode | string | yes | Stable snake_case key such as validation.failed or diagram.invalid. |
message | string | yes | Safe, human-readable summary. |
details | any | no | Validation issues or diagnostics, JSON-safe. |
requestId | string | no | Trace id for correlating with logs. |
See also
| Doc | Why |
|---|---|
| Schemas | Every request and response type |
| Tool reference | The same operations as callable tools |
| Language reference | What the diagram source may contain |
| Writing diagrams | The language by example |