mindmapio

Drive Mindmap.io maps via the node API

This skill teaches you to drive Mindmap.io maps by calling its HTTP node API directly. It is the alternative to the mindmapio-mcp server: same primitives, no MCP client required, just authenticated HTTP calls.

The API is the authoritative contract — match the shapes in the examples exactly. A map's data is a tree of nodes, the same shape every read returns, with camelCase fields like nodeType and parentId. The single-node write endpoints take their own snake_case fields like node_type.

Setup

Every call sends a personal access token as a bearer header. Generate the token once in Mindmap.io: settings → API access. It acts as its user; regenerating it immediately revokes the old one.

export MINDMAP_API_TOKEN="<your personal access token>"
export MINDMAP_API_BASE_URL="https://mindmap.io"   # optional, this is the default

Never print, echo, or commit the token. Send it on every request:

Authorization: Bearer $MINDMAP_API_TOKEN

A reusable curl alias for the examples below:

mm() { curl -sS -H "Authorization: Bearer $MINDMAP_API_TOKEN" \
  -H "Content-Type: application/json" "$MINDMAP_API_BASE_URL$@"; }

Primitives

IDs are unprefixed everywhere. You mint node ids client-side, so you can reference a node id you chose before it is persisted.

Node content is sent as messages: a UIMessage array (Vercel AI SDK shape). Each message is {role, parts} and each part is {type: "text", text}. A node's body — a prompt, a data node, a note's source turn — is a single user message with one or more text parts.

Read

List maps — GET /api/mindmaps → array of {id, title, kind, created_at, updated_at}, newest first.

mm /api/mindmaps

Read a full map — GET /api/mindmaps/{id} → {id, title, kind, user_id, data} where data is {rootId, selectedId, nodes} and nodes maps id → node.

mm /api/mindmaps/MAP_ID

Read one node — GET /api/mindmaps/{mapId}/nodes/{nodeId} → a SubtreeNode {node, children} with children: []. The node's own children array still lists child ids for navigation.