Working with Diagrams

These examples use curl against the hosted service. Each request carries your API token; the examples assume you have put it in a shell variable:

export TOKEN=lvd_your_token_here

Paths are relative to https://livediagram.app/api. For the exact request and response shapes of every field, see the OpenAPI reference at /api/openapi.json.

List your diagrams

A diagram list returns metadata only, not the tab contents:

curl https://livediagram.app/api/diagrams \
  -H "Authorization: Bearer $TOKEN"

{
  "diagrams": [{ "id": "abc123", "name": "Service map", "folderId": null, "shareable": false }]
}

Read a diagram and a tab

Fetching one diagram returns its metadata and a list of tab summaries, but still not the elements on each tab:

curl https://livediagram.app/api/diagrams/abc123 \
  -H "Authorization: Bearer $TOKEN"

To get the actual contents of a tab, request it by id. This keeps listing a big diagram cheap:

curl https://livediagram.app/api/diagrams/abc123/tabs/tab-1 \
  -H "Authorization: Bearer $TOKEN"

{
  "tab": {
    "id": "tab-1",
    "name": "Overview",
    "elements": [
      /* ... */
    ]
  }
}

Create a diagram

POST /diagrams creates a diagram. You supply the id (any unique string), a name, and optionally the tabs to seed it with. Nodes are shape elements with a position and size; this creates one tab with two boxes:

curl -X POST https://livediagram.app/api/diagrams \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "svc-map",
    "name": "Service map",
    "tabs": [
      {
        "id": "tab-1",
        "name": "Overview",
        "elements": [
          { "id": "n1", "type": "shape", "shape": "square", "x": 0, "y": 0, "width": 160, "height": 80, "label": "Web" },
          { "id": "n2", "type": "shape", "shape": "square", "x": 0, "y": 160, "width": 160, "height": 80, "label": "API" }
        ]
      }
    ]
  }'

Arrows, text, images, and the rest of the element types follow the same pattern with their own fields. The OpenAPI document's Tab and Element schemas describe every one.

Update a tab

To change what is on a tab, send the whole tab with PUT. It replaces that tab's contents, so include every element you want to keep:

curl -X PUT https://livediagram.app/api/diagrams/svc-map/tabs/tab-1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": "tab-1", "name": "Overview", "elements": [ /* the full set */ ] }'

Organise into folders

Create a folder, then move a diagram into it:

curl -X POST https://livediagram.app/api/folders \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "id": "infra", "name": "Infrastructure" }'

curl -X PUT https://livediagram.app/api/diagrams/svc-map/folder \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "folderId": "infra" }'

Share a diagram

Create a share link with a role of view or edit:

curl -X POST https://livediagram.app/api/diagrams/svc-map/share \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "role": "view" }'

The response includes the share code to build a link from. See Sharing and Embeds for what the different roles allow.