API REST

Começar

1. Crie um token em Conta → Tokens de acesso. "Ver mapas" só lê; "Ver e editar" também grava. O valor mm_… aparece uma vez só.
2. Mande o token no cabeçalho Authorization: Bearer mm_… em toda chamada. Sem cookie: o token sozinho basta.
3. Teste com GET /api/me, que devolve o e-mail da conta.

export NUMAPS_TOKEN=mm_…
curl https://numaps.nuture.so/api/me -H "Authorization: Bearer $NUMAPS_TOKEN"

Valem as suas permissões: mapa compartilhado com você para ver só é lido. Revogue o token na conta se ele vazar. A especificação completa, para gerar cliente ou importar no Postman, está em /openapi.json (OpenAPI 3.1).

O documento

Um mapa é um contêiner invisível (id: -1, v: 2) cujos filhos são os nós centrais. Cada nó tem um id numérico único, o texto em t (uma linha por item) e os filhos em k. O título do mapa é o texto do 1º nó central.

{
  "id": -1,
  "v": 2,
  "t": [
    "Viagem"
  ],
  "k": [
    {
      "id": 0,
      "t": [
        "Viagem"
      ],
      "x": 0,
      "y": 0,
      "k": [
        {
          "id": 1,
          "t": [
            "Roteiro"
          ],
          "side": "R"
        },
        {
          "id": 2,
          "t": [
            "Orçamento"
          ],
          "side": "L",
          "note": "Até R$ 5 mil"
        }
      ]
    }
  ]
}

Limites: 10.000 nós, 200 níveis, 1,8 MB por mapa. Campo desconhecido é recusado com invalid_map. Para mudar um mapa: leia com GET, altere o documento e grave com PUT mandando a versão lida.

Endpoints

GET /api/me · Quem sou eu

O e-mail da conta dona do token. Bom para testar o token.

curl https://numaps.nuture.so/api/me \
  -H "Authorization: Bearer $NUMAPS_TOKEN"

Resposta 200: A conta. Erros: 401, 429.

GET /api/maps · Listar mapas

Seus mapas e os compartilhados com você, do editado por último ao mais antigo (até 100 de cada). Os que você arquivou na Home ficam de fora; com archived=1, vêm só eles.

Parâmetros: archived (1: só os mapas que você arquivou (o arquivamento é feito na Home)).

curl https://numaps.nuture.so/api/maps \
  -H "Authorization: Bearer $NUMAPS_TOKEN"

Resposta 200: As duas listas. Erros: 401, 429.

POST /api/maps · Criar mapa edita

Sem root, cria um mapa em branco com o estilo e o layout padrão da conta. Com root, grava o documento dado (o título vem do 1º nó central).

curl -X POST https://numaps.nuture.so/api/maps \
  -H "Authorization: Bearer $NUMAPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"root":{"id":-1,"v":2,"t":["Viagem"],"k":[{"id":0,"t":["Viagem"],"x":0,"y":0,"k":[{"id":1,"t":["Roteiro"],"side":"R"},{"id":2,"t":["Orçamento"],"side":"L","note":"Até R$ 5 mil"}]}]}}'

Resposta 201: Criado. Erros: 400, 401, 403, 413, 429.

GET /api/maps/{id} · Abrir mapa

O documento inteiro e a versão atual.

curl https://numaps.nuture.so/api/maps/MAPA_ID \
  -H "Authorization: Bearer $NUMAPS_TOKEN"

Resposta 200: O mapa. Erros: 401, 404, 429.

PUT /api/maps/{id} · Gravar mapa edita

Substitui o documento. Mande em baseVersion a versão que você leu: se outra pessoa gravou no meio, a resposta é 409 com a versão atual em error.current, para você juntar as mudanças e tentar de novo. Gravações seguidas do mesmo token em até 10 minutos viram uma revisão só no histórico.

curl -X PUT https://numaps.nuture.so/api/maps/MAPA_ID \
  -H "Authorization: Bearer $NUMAPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"baseVersion":1,"root":{"id":-1,"v":2,"t":["Viagem"],"k":[{"id":0,"t":["Viagem"],"x":0,"y":0,"k":[{"id":1,"t":["Roteiro"],"side":"R"},{"id":2,"t":["Orçamento"],"side":"L","note":"Até R$ 5 mil"}]}]}}'

Resposta 200: Gravado. Erros: 400, 401, 403, 404, 409, 413, 429.

POST /api/maps/{id}/duplicate · Duplicar mapa edita

Cria uma cópia sua ("Cópia de …"), sem compartilhamentos nem histórico. Com version, copia aquela versão do histórico. Vale também para mapas que você só pode ver.

curl -X POST https://numaps.nuture.so/api/maps/MAPA_ID/duplicate \
  -H "Authorization: Bearer $NUMAPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta 201: Copiado. Erros: 400, 401, 403, 404, 413, 429.

GET /api/maps/{id}/revisions · Histórico

Versões do mapa, da mais nova para a mais antiga, em páginas. Para a próxima página, mande before = nextBefore.

Parâmetros: limit, before (Só versões menores que esta).

curl https://numaps.nuture.so/api/maps/MAPA_ID/revisions \
  -H "Authorization: Bearer $NUMAPS_TOKEN"

Resposta 200: Uma página do histórico. Erros: 400, 401, 404, 429.

GET /api/maps/{id}/revisions/{version} · Abrir uma versão

O documento como estava naquela versão.

curl https://numaps.nuture.so/api/maps/MAPA_ID/revisions/1 \
  -H "Authorization: Bearer $NUMAPS_TOKEN"

Resposta 200: A versão. Erros: 400, 401, 404, 429.

POST /api/maps/{id}/restore · Restaurar uma versão edita

Grava o documento de version como versão nova (nada é apagado do histórico). baseVersion funciona como no PUT.

curl -X POST https://numaps.nuture.so/api/maps/MAPA_ID/restore \
  -H "Authorization: Bearer $NUMAPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version":1,"baseVersion":1}'

Resposta 200: Restaurado. Erros: 400, 401, 403, 404, 409, 413, 429.

GET /api/account/prefs · Preferências

O padrão de mapa novo e o tema dos estilos.

curl https://numaps.nuture.so/api/account/prefs \
  -H "Authorization: Bearer $NUMAPS_TOKEN"

Resposta 200: As preferências. Erros: 401, 429.

PATCH /api/account/prefs · Mudar preferências edita

Muda só os campos mandados; null volta ao padrão. Não mexe em nenhum mapa existente.

curl -X PATCH https://numaps.nuture.so/api/account/prefs \
  -H "Authorization: Bearer $NUMAPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"newMap":{"st":"vivas","ly":"horizontal"}}'

Resposta 200: As preferências depois da mudança. Erros: 400, 401, 403, 429.

PUT /api/account/prefs · Trocar preferências edita

Substitui as preferências inteiras.

curl -X PUT https://numaps.nuture.so/api/account/prefs \
  -H "Authorization: Bearer $NUMAPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prefs":{"styleTheme":"light"}}'

Resposta 200: As preferências gravadas. Erros: 400, 401, 403, 429.

Erros e limites

Todo erro vem como { "error": { "code": "…", "message": "…" } }. Decida pelo code; a message é texto para gente e pode mudar.

• Leituras: até 120 por minuto por conta, somando os tokens. Gravações: até 120 por minuto e 5.000 por dia por conta, somando tokens, apps e o editor. Acima disso, 429 com Retry-After; o teto do dia volta à 0h UTC.
• Corpo de até 2 MB. Até 1.000 mapas e 5 MB por conta, somando mapas e histórico; quando falta espaço, o histórico mais antigo cede primeiro.
• Gravações por token aparecem no histórico como "via token <nome>".
• Apagar mapas, compartilhar e gerenciar a conta ficam só no site.