HTTP API reference
REST endpoints for creating projects, pushing diagram HTML, versions, visibility, and members, with curl examples and an OpenAPI description.
Every change on Diagram goes through this API or the MCP server, with the same keys and access checks. Use it from CI or scripts.
- Base URL:
https://diagram.la/api/v1 - Auth:
Authorization: Bearer dgm_...with a key from the API keys page. - Bodies and responses are JSON.
GET /api/v1returns an index of the endpoints, and/openapi.jsondescribes them in OpenAPI 3.1.
Endpoints
Who can read: the project's owner, the emails it added, and, for a project in an org, everyone in that org. Orgs themselves are created and managed on the site.
| Method | Path | Body | Who |
|---|---|---|---|
| GET | /projects |
Projects you own or were added to | |
| GET | /orgs |
Orgs you belong to | |
| POST | /projects |
{ slug, name?, org? } |
Anyone with a key |
| GET | /projects/:slug |
Owner, members | |
| PATCH | /projects/:slug |
{ name?, org? }. A new name moves the slug too (the old one keeps working and redirects); org is an org slug, or null for personal |
Owner |
| DELETE | /projects/:slug |
Moves the project and its diagrams to your archive (/archive), where you restore them or delete them for good |
Owner |
| POST | /projects/:slug/members |
{ email } |
Owner |
| DELETE | /projects/:slug/members |
{ email } |
Owner |
| GET | /projects/:slug/diagrams |
Owner, members | |
| POST | /projects/:slug/diagrams |
{ title, html, visibility?, kind?, draft? } (kind says what kind of diagram it is, from a fixed list such as flowchart, gantt or exploded_view; see /openapi.json. draft: true starts it as a draft only you can see; the API publishes straight away by default, since CI has no one to ask) |
Owner |
| GET | /diagrams/:id |
?html=1 also returns the HTML |
Owner, members |
| GET | /<id>/screenshot (site, not /api) |
The current version as a JPEG, for whoever can open the diagram | Same as the diagram |
| PUT / PATCH | /diagrams/:id |
{ html?, title?, visibility?, kind?, project?, publish? } (project moves it to another project you own; same link. publish: true publishes a draft) |
Anyone who can see the project; visibility and project: owner |
| GET | /diagrams/:id/versions |
Owner, members | |
| POST | /diagrams/:id/restore |
{ version } publishes that version again as the newest |
Anyone who can see the project |
| DELETE | /diagrams/:id |
Moves it to your archive | Owner |
Examples
Create a project and a diagram:
curl -X POST https://diagram.la/api/v1/projects \
-H "Authorization: Bearer $DIAGRAM_API_KEY" -H 'content-type: application/json' \
-d '{"slug":"my-app","name":"My App"}'
jq -Rs '{title:"Architecture", html:., visibility:"private"}' docs/architecture.html |
curl -X POST https://diagram.la/api/v1/projects/my-app/diagrams \
-H "Authorization: Bearer $DIAGRAM_API_KEY" -H 'content-type: application/json' -d @-
The response includes the permanent link:
{ "diagram": { "id": "Hk3pQ8zLw2Rt", "project": "my-app", "title": "Architecture",
"visibility": "private", "version": 1, "url": "https://diagram.la/Hk3pQ8zLw2Rt", ... } }
Push a new version to the same link:
jq -Rs '{html:.}' docs/architecture.html |
curl -X PUT https://diagram.la/api/v1/diagrams/Hk3pQ8zLw2Rt \
-H "Authorization: Bearer $DIAGRAM_API_KEY" -H 'content-type: application/json' -d @-
The response is { diagram, changed }. Identical HTML returns changed: false and doesn't add a version.
Make it public:
curl -X PATCH https://diagram.la/api/v1/diagrams/Hk3pQ8zLw2Rt \
-H "Authorization: Bearer $DIAGRAM_API_KEY" -H 'content-type: application/json' \
-d '{"visibility":"public"}'
Errors
Errors are { "error": "message" } with a status code:
| Status | Meaning |
|---|---|
| 400 | The body failed validation. issues lists what's wrong. |
| 401 | Missing, invalid, or revoked key. |
| 403 | You can see the project but only its owner can do that (change visibility, move, delete), or the owner's account has hit a limit. |
| 404 | The project or diagram doesn't exist, or you can't see it. |
| 409 | The project slug is taken. |
Limits
- 900KB of HTML per version. Every version is kept.
- Free accounts can have 5 diagrams across all their projects (archived diagrams, versions, and diagrams in projects shared with them don't count). Past that, creating a diagram returns 403 with an upgrade link. Paid plans, with unlimited diagrams, open soon. Projects are unlimited on both. See pricing.
- 20 active API keys per account.
- Project slugs are unique across the site: lowercase letters, digits, and dashes.