/docs/editing

One call. Every change.

edit_mindmap applies a list of operations to one map atomically: either every operation succeeds, or none do and the map is unchanged.

Operations

opFieldsWhat it does
addparent, text, note?, after?, ref?, children?Adds a node, with an optional subtree, under parent. Without after it goes last.
updatenode, text?, note?, collapsed?Changes a node’s text or note, or collapses it. A note of null removes it.
movenode, parent, after?, side?Moves a node and its subtree. after: null makes it the first child.
deletenodeRemoves a node and its whole subtree. The root can’t be deleted.
renametitleRenames the map.

Temporary refs

Give a new node a ref like $risks, then use that ref as a parent later in the same call. The result maps each ref to its new node id in refs. Write receipts summarize counts without exposing existing labels or notes; read-authorized clients can retrieve detailed descriptions from get_mindmap_activity.

edit_mindmap
{
  "id": "map_k2x9p4q7",
  "expectedVersion": 3,
  "operations": [
    {
      "op": "add",
      "ref": "$risks",
      "parent": "n_root01",
      "text": "Risks"
    },
    {
      "op": "add",
      "parent": "$risks",
      "text": "Budget"
    },
    {
      "op": "add",
      "parent": "$risks",
      "text": "Hiring"
    }
  ]
}

Versions and conflicts

Every map has a version that goes up by one with each change, whoever makes it. Pass the version you read as expectedVersion, so your edit never overwrites a change you haven’t seen.

  1. Call get_mindmap and note version.
  2. Call edit_mindmap with expectedVersion set to it.
  3. On VERSION_CONFLICT, data.currentVersion holds the new version. Call get_mindmap again, rebuild your operations against the new tree and retry.

To retry a create or edit safely after a network error, send the same idempotencyKey and input with it. Keys are kept for 24 hours and replay the original receipt and applied version, even if the map has since changed. Read the current tree separately with get_mindmap.

Deleting a map

delete_mindmap removes a whole map permanently. Ask the person first, then pass the map’s exact title as confirmTitle.