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=lwt_your_token_here
In livediagram
Paths are relative to https://www.livediagram.app/api. For the exact request and response shapes of every field, see the OpenAPI reference at /api/openapi.json.
Old paths. These routes were called /api/diagrams… until canvases got their name. Scripts that still call the old paths keep working until 30 April 2027 , with a Deprecation header on every answer; move them to /api/documents… before then.
List your filesIn livehuddle
A space list returns the spaces in your personal library (spaces in a team library are not included), as metadata only, not the tab contents:
curl https://www.livehuddle.app/api/documents \
-H "Authorization: Bearer $TOKEN"
In livediagram
A canvas list returns the canvases in your personal library, as metadata only, not the tab contents. Add team=all to include every team you have joined, q= to search names, and limit= for one page of that many, newest first:
curl https://www.livediagram.app/api/documents \
-H "Authorization: Bearer $TOKEN"
In livedocuments
A document list returns the documents in your personal library, as metadata only, not the tab contents. Add ?team=all to include every team you have joined, q= to search by name and limit= for one page of results, or archived=1 to list your Archived documents instead:
curl https://www.livedocuments.app/api/documents \
-H "Authorization: Bearer $TOKEN"
{
"documents": [{ "id": "abc123", "name": "Service map", "folderId": null, "shareable": false }]
}
Read a file and a tabFetching one file returns its metadata and a list of tab summaries , but still not the elements on each tab:
To get the actual contents of a tab, request it by id. This keeps listing a big file cheap:
{
"tab": {
"id": "tab-1",
"name": "Overview",
"rev": 7,
"elements": [/* ... */]
}
}
Read a tab as textIn livediagram
The element JSON carries every coordinate and colour. When you want what a tab means , which is usually what a script or an AI model needs, ask for a view instead. The outline gives one line per element, nested by frame, with its arrows on the same line:
In livedocuments
The element JSON carries every coordinate and colour. When you want what a tab means , which is usually what a script or an AI model needs, ask for a view instead. The outline gives one line per element, nested by stack, with its arrows on the same line:
In livehuddle
The element JSON carries every coordinate and colour. When you want what a tab means , which is usually what a script or an AI model needs, ask for a view instead. The outline gives one line per element, in reading order:
In livediagram and livedocuments
tab tab-1 "Overview" · 3 elements: 2 boxes, 1 arrow · rev 7
square n1 "Web" → n2
square n2 "API"
Each element is named by a short ref : its id when that is short and readable, otherwise the first few characters of it. Anywhere the API takes an element, a ref, any unique start of the id or the full id all work. The first line ends with the tab's revision.
Other views answer other questions:
In livediagram
view=graph lists what connects to what.
view=layout gives positions and sizes; add coarse=1 for rows instead.
view=comments shows the open comment threads in full; add all=1 for resolved ones too.
view=show&ref=n1 prints one element with every field and its arrows both ways.
view=find&q=api lists the elements whose text contains api.
In livedocuments
view=graph lists what connects to what.
view=layout gives positions and sizes; add coarse=1 for rows instead.
view=comments shows the open comment threads in full; add all=1 for resolved ones too.
view=show&ref=n1 prints one element with every field and its arrows both ways.
view=find&q=api lists the elements whose text contains api.
view=pages lists the tab's pages and articles.
In livehuddle
view=layout gives positions and sizes; add coarse=1 for rows instead.
view=comments shows the open comment threads in full; add all=1 for resolved ones too.
view=show&ref=n1 prints one element with every field.
view=find&q=api lists the elements whose text contains api.
In livediagram
view=lint checks how the tab is drawn: boxes that overlap, arrows that cross or run behind boxes, labels too long for their box. One summary line, then one finding a line, each ending with a fix you can send as a changeset:
In livedocuments
view=lint checks how the tab is drawn: boxes that overlap, arrows that cross or run behind boxes, labels too long for their box, and text that overflows its box or prints over other text. One summary line, then one finding a line, each ending with a fix you can send as a changeset:
In livediagram and livedocuments
5 crossings · 2 behind · 0 overlaps · 1317×1196 → 3 warnings, 6 info
W arrow-behind-box orders→bus passes behind pay fix: set orders->bus line=angled
Every changeset's last line carries the same verdict, such as lint clean or lint 1 warning, beside the new revision and the revert command. A changeset that changes nothing answers nothing changed.
In livediagram and livedocuments
Add budget=2000 to fit any view except lint to about 2,000 tokens. The view then leaves out detail in a fixed order, and its last line says what it left out and how to see it. Add json=1 for the same view as JSON. To see every tab of a file at a glance, ask the file itself: GET /documents/abc123?view=overview.
In livehuddle
Add budget=2000 to fit any view to about 2,000 tokens. The view then leaves out detail in a fixed order, and its last line says what it left out and how to see it. Add json=1 for the same view as JSON. To see every tab of a space at a glance, ask the space itself: GET /documents/abc123?view=overview.
Create a fileIn livediagram and livedocuments
POST /documents creates a file. You supply the id, 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. Ids are shared across all of every app, not just your account, so use a fresh UUID for the file, each tab and each folder; an id someone else already holds is refused or swapped for a new one:
In livehuddle
POST /documents creates a space. You supply the id, a name, and optionally the tabs to seed it with. Each element has a position and size; this creates one tab with two sticky notes. Ids are shared across all of livehuddle, not just your account, so use a fresh UUID for the space, each tab and each folder; an id someone else already holds is refused or swapped for a new one:
In livediagram
DOC=$(uuidgen) TAB=$(uuidgen) FOLDER=$(uuidgen)
curl -X POST https://www.livediagram.app/api/documents \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "'"$DOC"'",
"name": "Service map",
"tabs": [
{
"id": "'"$TAB"'",
"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" }
]
}
]
}'
In livedocuments
DOC=$(uuidgen) TAB=$(uuidgen) FOLDER=$(uuidgen)
curl -X POST https://www.livedocuments.app/api/documents \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "'"$DOC"'",
"name": "Service map",
"tabs": [
{
"id": "'"$TAB"'",
"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" }
]
}
]
}'
In livehuddle
DOC=$(uuidgen) TAB=$(uuidgen) FOLDER=$(uuidgen)
curl -X POST https://www.livehuddle.app/api/documents \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "'"$DOC"'",
"name": "Team sync",
"tabs": [
{
"id": "'"$TAB"'",
"name": "Overview",
"elements": [
{ "id": "n1", "type": "sticky", "x": 0, "y": 0, "width": 200, "height": 200, "label": "Agenda" },
{ "id": "n2", "type": "sticky", "x": 240, "y": 0, "width": 200, "height": 200, "label": "Actions" }
]
}
]
}'
In livediagram and livedocuments
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 tabScripts and agents change a tab with a changeset : a short list of edit operations, applied together or not at all. Anyone with the file open sees the change arrive straight away, it is credited to you, and it can be undone as one unit for 30 days. Changes people make in the editor at the same time are kept.
In livediagram
curl -X POST https://www.livediagram.app/api/documents/$DOC/tabs/$TAB/changesets \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"summary": "rename the API box, add a database",
"operations": [
{ "op": "set", "target": "n2", "fields": { "label": "Orders API" } },
{ "op": "add", "element": { "id": "n3", "type": "shape", "shape": "cylinder", "x": 0, "y": 320, "width": 160, "height": 80, "label": "Orders DB" } },
{ "op": "rm", "target": "n1" }
]
}'
In livedocuments
curl -X POST https://www.livedocuments.app/api/documents/$DOC/tabs/$TAB/changesets \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"summary": "rename the API box, add a database",
"operations": [
{ "op": "set", "target": "n2", "fields": { "label": "Orders API" } },
{ "op": "add", "element": { "id": "n3", "type": "shape", "shape": "cylinder", "x": 0, "y": 320, "width": 160, "height": 80, "label": "Orders DB" } },
{ "op": "rm", "target": "n1" }
]
}'
In livehuddle
curl -X POST https://www.livehuddle.app/api/documents/$DOC/tabs/$TAB/changesets \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"summary": "rename the actions note, add a decisions note",
"operations": [
{ "op": "set", "target": "n2", "fields": { "label": "Next Steps" } },
{ "op": "add", "element": { "id": "n3", "type": "sticky", "x": 480, "y": 0, "width": 200, "height": 200, "label": "Decisions" } },
{ "op": "rm", "target": "n1" }
]
}'
In livediagram and livedocuments
set changes only the fields you name, add takes a whole element, and rm removes an element (here the Web box) along with any arrow pinned to it. The answer lists what changed, the changeset's id and the tab's new revision. Add ?dryRun=1 to see the answer without changing anything.
In livehuddle
set changes only the fields you name, add takes a whole element, and rm removes an element (here the Agenda note). The answer lists what changed, the changeset's id and the tab's new revision. Add ?dryRun=1 to see the answer without changing anything.
The same operations read well as text, one a line, which is easier for a script or an agent to write. Send them as a string:
In livediagram
Elements are named by the refs a text view prints, or picked by what they are: "Orders API" by label, type:sticky, in:f2 for what a frame holds, n3->n4 for an arrow. Edit Operations Reference lists every operation, selector, placement and flag. Besides add, set and rm there are move, connect, rewire, insert (a step between two connected ones, making room for it), wrap and unwrap (frames and lanes), order, layout, and test, which refuses the changeset unless an element still holds the values you read. New boxes are sized for their label and placed beside what you name, and the answer has one line per element changed:
In livedocuments
Elements are named by the refs a text view prints, or picked by what they are: "Orders API" by label, type:sticky, in:s2 for what a stack holds, n3->n4 for an arrow. Edit Operations Reference lists every operation, selector, placement and flag. Besides add, set and rm there are move, connect, rewire, insert (a step between two connected ones, making room for it), unwrap (stacks), order, layout, and test, which refuses the changeset unless an element still holds the values you read. New boxes are sized for their label and placed beside what you name, and the answer has one line per element changed:
In livehuddle
Elements are named by the refs a text view prints, or picked by what they are: "Next Steps" by label or type:sticky. Edit Operations Reference lists every operation, selector, placement and flag. Besides add, set and rm there are move, order, layout (tidy rows), and test, which refuses the changeset unless an element still holds the values you read. New boxes are sized for their label and placed beside what you name, and the answer has one line per element changed:
~ n2 label "Actions"→"Next Steps"
+ risks sticky "Risks" @240,240 200×200
In livediagram and livedocuments
~ n2 label "API"→"Orders API"
+ db cylinder "Orders DB" @14,270 113×140
+ arrow n2→db
In livediagram
To rebuild a whole tab, send "replace" instead of "operations", with elements (or a graph, mermaid text or a template). A replace on a tab id the canvas doesn't have yet creates that tab.
In livedocuments and livehuddle
To rebuild a whole tab, send "replace" instead of "operations", with elements (or a template). A replace on a tab id the file doesn't have yet creates that tab.
Every tab read returns the tab's rev. Send it back as "base": { "rev": 7 } and the changeset is
refused with 409 changeset_conflict if an element it touches changed since you read it, so
nothing you didn't see gets overwritten. An element somebody has selected in the editor is left
alone too: the changeset is refused with 409 elements_held, naming who holds it.
To rename a tab, PUT its name: PUT /documents/$DOC/tabs/$TAB/name with { "name": "Overview" }. The whole-tab PUT the editor saves with is not open to tokens; it answers 405 use_changesets.
GET /documents/$DOC/changesets lists the recent changesets, and POST /documents/$DOC/changesets/<id>/revert undoes one, leaving any element somebody changed since.
Organise into foldersCreate a folder (add "parentId" to make it inside another, or "teamId" for a team's), then create a file straight into it by naming its id as folderId. Renaming and moving folders, and moving a file you already have, happens in the Explorer.
In livediagram
curl -X POST https://www.livediagram.app/api/folders \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "id": "'"$FOLDER"'", "name": "Infrastructure" }'
curl -X POST https://www.livediagram.app/api/documents \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "id": "'"$(uuidgen)"'", "name": "Network", "folderId": "'"$FOLDER"'" }'
In livedocuments
curl -X POST https://www.livedocuments.app/api/folders \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "id": "'"$FOLDER"'", "name": "Infrastructure" }'
curl -X POST https://www.livedocuments.app/api/documents \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "id": "'"$(uuidgen)"'", "name": "Runbook", "folderId": "'"$FOLDER"'" }'
In livehuddle
curl -X POST https://www.livehuddle.app/api/folders \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "id": "'"$FOLDER"'", "name": "Infrastructure" }'
curl -X POST https://www.livehuddle.app/api/documents \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "id": "'"$(uuidgen)"'", "name": "Network", "folderId": "'"$FOLDER"'" }'
GET /api/folders lists your folders with their ids.
Delete and restoreDELETE /documents/$DOC moves the file to the Trash , where it waits for 30 days, and answers 204. While it is there, reading or changing it answers 410 document_trashed. Add ?permanent=true to delete it for good straight away.
In livediagram and livehuddle
DELETE /trash/$DOC deletes one trashed file for good, and DELETE /trash empties your personal Trash (?team=<id> empties a team's). A read-only token can list the Trash but not restore or purge.
In livediagram
To put a canvas you own away instead, POST /documents/$DOC/archive moves it to your Archived: out of every list, with its share links ended. POST /documents/$DOC/unarchive brings it back, to the top of My Work, or into the folder or team you name with { "folderId": "…" } or { "teamId": "…" }. GET /documents?archived=1 lists what is archived.
Share a fileIn livedocuments
Create a share link with a role of view, participate or edit. Add "tabId" to share one tab, and "expiry" (never, the default, week, month or sixMonths) to make the link lapse:
The response includes the share code to build a link from. See Sharing and Embeds for what the different roles allow.
In livehuddle
Send the role explicitly, spelled exactly. A body with no role mints a participate link,
which is the app's own default, and so does a role the API does not recognise: it is dropped as if
you had sent none, not rejected. view is recognised but not offered here, so asking for it is
refused with a 400. Check the role in the answer.
When a call fails, the status code and a small { "error": "..." } body tell you why. See
Errors and Rate Limits .