Working with Files

Copy-pasteable examples for the calls you will reach for most.

Applies To

livediagram, livedocuments and livehuddle

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

List your files

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

Read a file and a tab

Fetching 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 text

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:

Create a file

Update a tab

Scripts 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.

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:

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 folders

Create 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.

GET /api/folders lists your folders with their ids.

Delete and restore

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

Share a file

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

When a call fails, the status code and a small { "error": "..." } body tell you why. See Errors and Rate Limits.

Was this article helpful?

Still need help?

Try Troubleshooting, or tell us what you were trying to do.

Contact us