/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
| op | Fields | What it does |
|---|---|---|
add | parent, text, note?, after?, ref?, children? | Adds a node, with an optional subtree, under parent. Without after it goes last. |
update | node, text?, note?, collapsed? | Changes a node’s text or note, or collapses it. A note of null removes it. |
move | node, parent, after?, side? | Moves a node and its subtree. after: null makes it the first child. |
delete | node | Removes a node and its whole subtree. The root can’t be deleted. |
rename | title | Renames 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.
{
"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.
- Call
get_mindmapand noteversion. - Call
edit_mindmapwithexpectedVersionset to it. - On
VERSION_CONFLICT,data.currentVersionholds the new version. Callget_mindmapagain, 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.