Working with Plans

List your plans

A plan list returns the plans in your personal library (plans in a team library are not included), as metadata only, not the tab contents:

curl https://liveplanner.app/api/projects \
  -H "Authorization: Bearer $TOKEN"

{
  "projects": [{ "id": "4cd7082b-…", "name": "Sprint 14", "folderId": null, "shareable": false }]
}

Read a tab as text

The element JSON carries every setting. 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:

curl "https://liveplanner.app/api/projects/$DOC/tabs/$TAB?view=outline" \
  -H "Authorization: Bearer $TOKEN"

tab 8bf8 "Board" · 1 element: 1 box · kind=board · rev 1
plan-board 0933 columns=Backlog|To Do|In Progress|Review|Done

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:

• view=show&ref=0933 prints one element with every stored field.
• view=comments shows the open comment threads in full; add all=1 for resolved ones too.
• view=find&q=roadmap lists the elements whose text contains roadmap.

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.

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 plan 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. This one changes the Kanban template's Flow dashboard (its tab id in $FLOW), using the refs its outline printed:

curl -X POST https://liveplanner.app/api/projects/$DOC/tabs/$FLOW/changesets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "swap the calendar for a workload chart",
    "base": { "rev": 1 },
    "operations": [
      { "op": "test", "target": "0a78", "fields": { "planView": { "view": "calendar" } } },
      { "op": "set", "target": "0a78", "fields": { "planView": { "view": "workload" } } },
      { "op": "rm", "target": "82d4" }
    ]
  }'

test refuses the changeset unless the element still holds what you read, set changes only the fields you name, and rm removes an element (here a dashboard metric). 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:

~ 0a78  planView (changed)
- 82d4  plan-view
rev 1→2 · cs_tbrfqcvm1w · revert: liveplanner changeset revert 4cd7082b-… cs_tbrfqcvm1w

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:

curl -X POST https://liveplanner.app/api/projects/$DOC/tabs/$FLOW/changesets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "operations": "set 0a78 planView={\"view\":\"workload\"}\nrm 82d4" }'

Edit Operations Reference lists every operation and selector, and how to rebuild a whole tab.

To rebuild a whole tab, send "replace" instead of "operations", with a template, a dashboard, a new Form tab's form, or elements. A replace on a tab id the plan doesn't have yet creates that tab.

To rename a tab, PUT its name: PUT /projects/$DOC/tabs/$TAB/name with { "name": "Board" }. The whole-tab PUT the editor saves with is not open to tokens; it answers 405 use_changesets.

GET /projects/$DOC/changesets lists the recent changesets, and POST /projects/$DOC/changesets/<id>/revert undoes one, leaving any element somebody changed since.

Cards, Sheet cells and forms have endpoints of their own: see Plan Items, Sheets and More.

Delete and restore

DELETE /projects/$DOC moves the plan to the Trash, where it waits for 30 days, and answers 204. While it is there, reading or changing it answers 410 project_trashed. Add ?permanent=true to delete it for good straight away.

curl -X DELETE https://liveplanner.app/api/projects/$DOC \
  -H "Authorization: Bearer $TOKEN"

# What you can restore: your own Trash and every team's you belong to
curl https://liveplanner.app/api/trash \
  -H "Authorization: Bearer $TOKEN"

curl -X POST https://liveplanner.app/api/trash/$DOC/restore \
  -H "Authorization: Bearer $TOKEN"

DELETE /trash/$DOC deletes one trashed plan 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.