Diagram
← Developer reference

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/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, 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.