HTTP API reference

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/v1 returns an index of the endpoints, and /openapi.json describes them in OpenAPI 3.1.

Endpoints

Who can read: the project's owner, the emails it added, and, for a project in an org with sharing on, everyone in the 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	Deletes the project and every diagram in it	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? }	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?, project? } (project moves it to another project you own; same link)	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		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 read the project but only its owner can change it, or you've hit an account 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 own up to 5 projects of 100 diagrams each. Pro ($5/month) raises that to 100 projects of 1000 diagrams. See pricing.
• 20 active API keys per account.
• Project slugs are unique across the site: lowercase letters, digits, and dashes.