A tab's elements change through changesets, but a document holds more than elements: the images it shows, its pages and its articles. Each has its own endpoints, shown here with curl. The examples assume your API token is in $TOKEN and a document id in $DOC; paths are relative to https://www.livedocuments.app/api, and /api/openapi.json has every field.
Every write here reaches anyone with the document open straight away, credited to you.
Images
Upload the raw bytes of a PNG, JPEG, WebP or GIF, up to 10 MB, with its pixel size in two headers:
curl -X POST https://www.livedocuments.app/api/images \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: image/png" \
-H "X-Image-Width: 1200" -H "X-Image-Height: 800" \
-H "X-Image-Original-Name: architecture.png" \
--data-binary @architecture.png
{
"image": {
"id": "9f2c…",
"contentType": "image/png",
"byteSize": 48211,
"width": 1200,
"height": 800,
"originalName": "architecture.png",
"createdAt": 1760180000000
},
"deduped": false
}
Uploading the same bytes again answers the image you already have, with "deduped": true. Then put it on a tab with a changeset that adds a whole image element:
curl -X POST https://www.livedocuments.app/api/documents/$DOC/tabs/$TAB/changesets \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "operations": [ { "op": "add", "element": { "type": "image", "imageId": "'"$IMAGE"'", "x": 0, "y": 0, "width": 600, "height": 400, "naturalWidth": 1200, "naturalHeight": 800, "alt": "Architecture overview" } } ] }'
GET /images lists your uploads, GET /images/usage maps each to the documents that use it, GET /images/{id} downloads one, and DELETE /images/{id} removes it from your gallery. Refusals are 415 unsupported_type, 413 file_too_large, and 403 gallery_full once your gallery holds 500 images or 1 GB, counted across every liveworkspace app.
Pages and Articles
POST /documents/$DOC/tabs/$TAB/pages changes a tab's Pages pages, up to 50 changes as one edit, or writes an article from Markdown. A locked tab is refused.
# Add two slides and rename the first page
curl -X POST https://www.livedocuments.app/api/documents/$DOC/tabs/$TAB/pages \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "pages": [
{ "op": "add", "kind": "slide", "name": "Roadmap" },
{ "op": "add", "kind": "slide", "background": { "gradient": ["#1e3a8a", "#7c3aed"] } },
{ "op": "set", "page": 1, "name": "Cover" }
] }'
# Write an article: the editor flows it onto pages
curl -X POST https://www.livedocuments.app/api/documents/$DOC/tabs/$TAB/pages \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "article": { "markdown": "# Release notes\n\nWhat changed this month.", "size": "a4" } }'
A page change is one of:
add: akindofinfographic,slideorflashcard, with an optionalsize,orientation,name,background,layoutandat(its place in the row). Article pages are not added this way: write an article instead.set: a page'sname,size,orientation,backgroundorlocked.layout,move(toa place),duplicateordelete. Deleting or duplicating an article's page acts on the whole article.apply_background_to_all: every other page of the same kind takes this page's background; locked pages keep their own.
A page is named by its id, its place in the row (from 1) or its name. A background takes one of color, gradient (two hex colours, with an optional angle) or paper: true, and may add a pattern.
An article write takes markdown, mode replace (the default) or append, and article (its id or title) to name an existing one, or new: true to start another. A new article also takes size and orientation, and any write can set the article's look (clean, classic, report, notebook or bold), accent (a hex colour) and pageNumbers. On a tab of flashcards, the write fills a card.
The answer lists every page with its rectangle on the canvas, which is where a changeset puts elements to land them on that page, and every article with its word count and an estimate of how many pages it fills. A refused request answers 400 naming the change it stopped at. An agent's article write that would change a paragraph someone is typing in is refused with 409 paragraphs_held, naming who holds it, so nothing they are writing is overwritten; try again once they pause (the CLI's article set --wait-held <seconds> does this for you).
A Tab as a Picture
curl https://www.livedocuments.app/api/documents/$DOC/tabs/$TAB/render.svg \
-H "Authorization: Bearer $TOKEN" -o overview.svg
The tab drawn by the same renderer the CLI's tab render and pull --svg use, as image/svg+xml, with images inlined when the host stores them. It is never cached, so it always shows the tab now. For an image to embed somewhere public, use a live image instead.
Copy a Document
curl -X POST https://www.livedocuments.app/api/documents/$DOC/copy \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "name": "Service map (2027 draft)" }'
Makes a copy in your own files and answers 201 with the new document. Leave out name for <name> (copy). Anything you can read can be copied; share links are not copied with it.
Was this article helpful?
Still need help?
Try Troubleshooting, or tell us what you were trying to do.