Edit Operations Reference

What a Changeset Changes

A tab holds a few elements, and they are what fill it: a Board tab holds a plan-board, a Sheet tab a plan-sheet, and a Dashboard tab one plan-view per metric, chart or note. A changeset changes those elements, such as a board's settings or which widgets a dashboard shows.

The things inside them have endpoints of their own, which are usually what you want:

• Cards live in the plan's item store, not on a tab. Add, change and move them with the item endpoints.
• Sheet cells are changed with sheet writes.
• A form's questions are changed with the form endpoints, or the CLI's form change and the MCP server's change_form.
• Comments have their own endpoints. Edit operations never change them.

The same vocabulary reaches a tab three ways:

• The API: POST /projects/{id}/tabs/{tabId}/changesets with "operations" as a string (the line form) or an array of objects (the JSON form).
• The CLI: liveplanner edit "Sprint 14" --tab Flow -f ops.txt sends a file (or stdin, with -f -) as one changeset, and liveplanner element set or liveplanner element rm sends one operation. liveplanner guide edit explains the line form.
• The MCP server: update_project in ops mode turns its add, update and remove into add, set and rm, or takes edits, edit operations as text.

Two Forms

The line form is one operation a line, which is what an agent writes most easily. Values with spaces are quoted (label="Sprint board"), a value starting with [ or { is read as JSON, and blank lines and lines starting with # are skipped:

# Swap the calendar for a workload chart, and drop the stale-cards metric
test 0a78 planView={"view":"calendar"}
set 0a78 planView={"view":"workload"}
rm 82d4

The JSON form is one object an operation, which is what a script produces. Any line of the text form that starts with { is read as JSON, so the two mix:

[
  { "op": "test", "target": "0a78", "fields": { "planView": { "view": "calendar" } } },
  { "op": "set", "target": "0a78", "fields": { "planView": { "view": "workload" } } },
  { "op": "rm", "target": "82d4" }
]

One parser turns the line form into the JSON form, so both are checked the same way. A changeset holds at most 500 operations, and a line at most 16,384 characters.

Element Kinds

A tab holds only these elements, each { "type": "shape", "shape": <kind>, "x", "y", "width", "height" } with an optional label and locked. An add or a replace with any other element is refused with invalid_value, naming the kinds there are:

A chart's chartSource is { "sheetId", "range": { "r1", "c1", "r2", "c2" } }: the sheet and the row and column ids of its first and last cells. GET /api/schema/<kind> (or liveplanner schema <kind>) prints a kind's fields, a closed field with its values:

{
  "op": "add",
  "element": {
    "type": "shape",
    "shape": "plan-view",
    "x": 0,
    "y": 840,
    "width": 500,
    "height": 360,
    "planView": { "view": "gantt" }
  }
}

test is how you make sure you change what you read: put one before a set and the changeset is refused, with nothing applied, if someone changed that element since. Sending the revision you read as base (below) does the same for every element at once.

Replace a Whole Tab

To rebuild a tab rather than change it, send "replace" instead of "operations", with exactly one of:

A replace may also carry a name for the tab. Nothing is laid out for you, so a replace carrying layout is refused. A replace on a tab id the plan does not have yet creates that tab, which is how a new tab is added in one write:

curl -X POST https://liveplanner.app/api/projects/$DOC/tabs/$(uuidgen)/changesets \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "replace": {
      "name": "Overview",
      "dashboard": {
        "tabs": [{ "tabId": "'"$BOARD_TAB"'", "of": "board" }],
        "metrics": ["count", "progress"],
        "charts": [{ "view": "workload" }]
      }
    }
  }'

The OpenAPI reference at /api/openapi.json lists the metric kinds and chart views a dashboard takes.

Base Revisions

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. Add "strict": true to refuse it if anything on the tab changed at all (412 stale_tab).

An element somebody has selected in the editor is left alone too: the changeset is refused with 409 elements_held, naming who holds it. The CLI's --wait-held <seconds> retries until they let go.