Mindmap

Mindmap para desenvolvedores e agentes de IA

O Mindmap expõe duas interfaces programáticas sobre os mesmos mapas que você vê na interface web: uma API REST em /api/v1 e um servidor MCP (Model Context Protocol) em /api/mcp. As duas usam a mesma chave de API pessoal e respeitam as mesmas permissões da sua conta.

O acesso programático faz parte dos planos Pro e Teams. Em contas do plano grátis as chaves existem mas respondem 402.

Autenticação

Crie uma chave em Configurações, na seção Chaves de API. A chave tem o formato mm_ seguido de 43 caracteres e aparece uma única vez. Escolha o escopo na criação: somente leitura (read) ou leitura e escrita (read e write).

Envie a chave no header Authorization em toda requisição, REST ou MCP:

Authorization: Bearer mm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Servidor MCP

O endpoint MCP é https://www.mindmap.app.br/api/mcp/mcp, no transporte Streamable HTTP (SSE está desativado). Configure-o em qualquer cliente MCP, como o Claude Desktop, o Claude Code ou o seu próprio agente:

{
  "mcpServers": {
    "mindmap": {
      "type": "http",
      "url": "https://www.mindmap.app.br/api/mcp/mcp",
      "headers": { "Authorization": "Bearer mm_sua_chave" }
    }
  }
}

Ferramentas MCP

  • list_maps: lista os mapas visíveis para o usuário (próprios e compartilhados), com id, título, papel e datas.
  • get_map: lê um mapa. format=markdown devolve texto legível, format=tree devolve a árvore JSON com os ids dos nós.
  • create_map: cria um mapa a partir de markdown (lista aninhada, raiz em H1) ou de uma árvore JSON. Exige escopo write.
  • replace_map: substitui todo o conteúdo de um mapa. Exige escopo write.
  • apply_node_ops: aplica um lote atômico de operações em nós. Exige escopo write.
  • delete_map: exclui um mapa, apenas para o dono. Exige escopo write.

API REST

A base é https://www.mindmap.app.br/api/v1. Corpo e resposta em JSON.

  • GET /api/v1/maps: lista os mapas visíveis. Resposta { maps: [...] }.
  • POST /api/v1/maps: cria um mapa. Corpo { title?, markdown? | tree? }. Resposta 201 com { id, title, url }.
  • GET /api/v1/maps/{id}?format=markdown|tree|both: lê um mapa. O padrão é markdown.
  • PUT /api/v1/maps/{id}: substitui o conteúdo. Corpo { markdown? | tree? }. Exige escopo write.
  • DELETE /api/v1/maps/{id}: exclui o mapa, apenas para o dono. Resposta 204. Exige escopo write.
  • POST /api/v1/maps/{id}/ops: aplica operações em nós. Corpo { ops: [...] }. Exige escopo write.

Exemplo: criar um mapa a partir de markdown

curl -X POST https://www.mindmap.app.br/api/v1/maps \
  -H "Authorization: Bearer mm_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lançamento",
    "markdown": "# Lançamento\n- Pesquisa\n  - Entrevistas\n- Produto\n- Go to market"
  }'

Operações em nós

POST /api/v1/maps/{id}/ops aplica de 1 a 100 operações em um único lote atômico: ou todas passam, ou nenhuma. Os ids de nó vêm de GET /api/v1/maps/{id}?format=tree.

Um add_node pode declarar um ref no formato $nome, que operações seguintes do mesmo lote usam no lugar de um id ainda inexistente. A resposta mapeia cada ref para o id criado.

  • add_node: { op, parentId, text, index?, note?, link?, color?, ref? }
  • update_node: { op, nodeId, text?, note?, link?, color?, collapsed? }. Enviar null em note, link ou color limpa o campo.
  • move_node: { op, nodeId, newParentId?, index? }. Sem newParentId, reordena dentro do pai atual.
  • delete_node: { op, nodeId }
{
  "ops": [
    { "op": "add_node", "parentId": "root", "text": "Riscos", "ref": "$riscos" },
    { "op": "add_node", "parentId": "$riscos", "text": "Prazo" },
    { "op": "update_node", "nodeId": "$riscos", "color": "#0F766E" }
  ]
}

Limites

  • 600 leituras por hora e 120 escritas por hora, por chave, em janela móvel.
  • Corpo da requisição de até 1 MB.
  • Até 2000 nós por mapa e até 200 filhos por nó.
  • Texto do nó até 500 caracteres, nota até 10.000, link até 2048.
  • Markdown de entrada até 500.000 caracteres.
  • Até 100 operações por lote em /ops.

Erros

Toda falha devolve JSON no formato { error: { code, message, details? } }.

  • invalid_key (401): chave ausente, inválida ou revogada.
  • plan_limit (402): a conta está no plano grátis, que não inclui acesso programático.
  • forbidden (403): a chave é somente leitura, ou falta permissão no mapa.
  • not_found (404): mapa inexistente ou fora do seu alcance.
  • validation_error (400): corpo ou parâmetro inválido, com details do Zod.
  • conflict (409): o mapa mudou durante a escrita. Releia e tente de novo.
  • payload_too_large (413): corpo acima de 1 MB.
  • op_failed (422): uma operação do lote não pôde ser aplicada.
  • rate_limited (429): limite por hora atingido.
  • internal (500): erro inesperado do servidor.

Formatos legíveis por máquina

  • llms.txt: índice do site para agentes, com quando usar o Mindmap.
  • openapi.json: especificação OpenAPI 3.1 da API REST.
  • sitemap.xml: páginas públicas indexáveis.
  • Negociação de conteúdo: /, /about, /contact, /docs, /privacy e /terms respondem em text/markdown quando a requisição envia Accept: text/markdown, com Vary: Accept. Um Accept que não aceite nenhum dos dois formatos recebe 406, e URLs inexistentes recebem 404 com corpo em markdown.

Suporte

Dúvidas e relatos de bug na API: contato@mindmap.app.br. Inclua o endpoint, o corpo enviado e o código de erro devolvido.