Mind Maps
Create, read, and edit mind maps through a structured node-tree API.
Mind Maps
When to use
Use these endpoints when an integration needs a complete mind map as a nested node tree. They avoid exposing the internal page and block layout used to store a mind map.
A mind map has a page-level identity, so it can also appear in page lists and search results with page_type: "mind_map". Use the mind-map endpoints below when you need its nodes or presentation settings.
Endpoints
| Method | Path | Purpose | Scope |
|---|---|---|---|
POST |
/v2/mind-maps |
Create a mind map and its initial node tree. | pages.write |
GET |
/v2/mind-maps/:mind_map_id |
Return the normalized tree and settings. | pages.read |
PATCH |
/v2/mind-maps/:mind_map_id |
Change the title/settings or edit nodes. | pages.write |
All three endpoints require Bearer token authentication. mind_map_id must be the UUID of either a page mind map or an inline mind map.
Create a mind map
POST /v2/mind-maps accepts an optional Idempotency-Key header. Reuse the same key only when retrying the same request body.
{
"parent": {
"page_id": "55555555-5555-4555-8555-555555555555"
},
"title": [
{
"type": "text",
"text": { "content": "Product roadmap", "link": null },
"plain_text": "Product roadmap",
"href": null
}
],
"settings": {
"layout": "both",
"line_style": "curved",
"sibling_node_alignment": true,
"branch_color": "gray"
},
"nodes": [
{
"rich_text": [
{
"type": "text",
"text": { "content": "Engineering", "link": null },
"plain_text": "Engineering",
"href": null
}
],
"branch_color": "blue",
"children": []
}
]
}
| Field | Required | Description |
|---|---|---|
parent.page_id |
No | Parent page UUID. Omit parent to create at the authenticated workspace root. |
title |
Yes | Mind-map title as a rich-text array. |
settings |
No | Initial presentation settings. |
nodes |
No | Initial root nodes, each with nested children. |
The endpoint accepts at most 100 root nodes, 100 children per node, 1,000 nodes in the complete tree, and 20 levels of nesting.
Get a mind map
GET /v2/mind-maps/:mind_map_id returns the complete normalized tree:
{
"object": "mind_map",
"id": "44444444-4444-4444-8444-444444444444",
"parent": { "type": "workspace", "workspace": true },
"title": [],
"settings": {
"layout": "both",
"line_style": "curved",
"sibling_node_alignment": true,
"branch_color": "gray",
"text_color": "default",
"background_color": "default"
},
"nodes": [
{
"id": "88888888-8888-4888-8888-888888888888",
"parent_node_id": null,
"rich_text": [],
"branch_color": "blue",
"text_color": "default",
"background_color": "default",
"has_children": false,
"children": []
}
],
"total_nodes": 1,
"created_time": "2026-04-09T08:00:00.000Z",
"last_edited_time": "2026-04-09T09:30:00.000Z",
"url": "https://buildin.ai/44444444-4444-4444-8444-444444444444"
}
Node IDs are stable and are the identifiers used by edit operations. Root nodes have parent_node_id: null.
Edit a mind map
PATCH /v2/mind-maps/:mind_map_id can update the title or settings and apply up to 100 ordered node operations in one request.
{
"settings": {
"line_style": "normal"
},
"operations": [
{
"op": "update_node",
"node_id": "88888888-8888-4888-8888-888888888888",
"rich_text": [],
"text_color": "blue"
},
{
"op": "add_node",
"parent_node_id": "88888888-8888-4888-8888-888888888888",
"node": {
"rich_text": [],
"branch_color": "purple"
}
}
]
}
| Operation | Required fields | Behavior |
|---|---|---|
add_node |
op, node |
Add a node at the root or below parent_node_id. |
update_node |
op, node_id, and at least one changed field |
Update node text or colors. |
move_node |
op, node_id |
Move a node to the root or below parent_node_id. |
archive_node |
op, node_id |
Soft-delete a node. |
For add_node and move_node, omit parent_node_id or send null to target the root. Set before_node_id to insert before an active direct child of the target parent; otherwise the node is appended. Moves that would create a cycle are rejected.
The response is the complete updated mind_map object. If the tree changes concurrently while an edit is being prepared, the endpoint returns 409 conflict rather than applying changes to a stale tree.
Settings and colors
| Field | Allowed values |
|---|---|
layout |
right, left, both, down |
line_style |
normal, curved |
sibling_node_alignment |
Boolean |
branch_color |
default, gray, brown, orange, pink, yellow, green, blue, purple, red |
text_color |
A supported V2 text color. |
background_color |
A supported V2 background color. |
branch_color: "default" clears the branch-specific color. See Object Models for rich text and Block Types for mind-map block creation.
Errors and limits
400 validation_error: invalid UUID, malformed node tree, unsupported setting, empty edit, too many operations, or a move that would create a cycle.403 forbidden: missing scope or no access to the target mind map.404 not_found: the mind map or a referenced node does not exist.409 conflict: the tree is structurally invalid or changed during edit preparation.429 rate_limited: the credential exceeded its request limit.