{ "openapi": "3.1.0", "info": { "title": "Numaps API", "version": "1.0.0", "description": "API REST dos mapas do Numaps. Autenticação por token pessoal (Conta → Tokens de acesso). Mudanças incompatíveis só com aviso e versão nova da API." }, "servers": [ { "url": "https://numaps.nuture.so" } ], "security": [ { "token": [] } ], "paths": { "/api/me": { "get": { "operationId": "getMe", "summary": "Quem sou eu", "description": "O e-mail da conta dona do token. Bom para testar o token.", "responses": { "200": { "description": "A conta", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "E-mail da conta" } }, "required": [ "email" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/maps": { "get": { "operationId": "listMaps", "summary": "Listar mapas", "description": "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.", "parameters": [ { "name": "archived", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "description": "1: só os mapas que você arquivou (o arquivamento é feito na Home)" } ], "responses": { "200": { "description": "As duas listas", "content": { "application/json": { "schema": { "type": "object", "properties": { "maps": { "type": "array", "items": { "$ref": "#/components/schemas/MapListItem" } }, "sharedMaps": { "type": "array", "items": { "$ref": "#/components/schemas/SharedMapListItem" } } }, "required": [ "maps", "sharedMaps" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } }, "post": { "operationId": "createMap", "summary": "Criar mapa", "description": "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). Exige token com escopo \"Ver e editar\".", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "root": { "$ref": "#/components/schemas/MapDoc" } }, "required": [] }, "example": { "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" } ] } ] } } } } }, "responses": { "201": { "description": "Criado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id do mapa novo" }, "version": { "type": "integer", "description": "Sempre 1" } }, "required": [ "id", "version" ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "413": { "$ref": "#/components/responses/E413" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/maps/{id}": { "get": { "operationId": "getMap", "summary": "Abrir mapa", "description": "O documento inteiro e a versão atual.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Id do mapa (de GET /api/maps)" } ], "responses": { "200": { "description": "O mapa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Map" } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "put": { "operationId": "saveMap", "summary": "Gravar mapa", "description": "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. Exige token com escopo \"Ver e editar\".", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Id do mapa (de GET /api/maps)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "baseVersion": { "type": "integer", "description": "Versão lida (GET)" }, "root": { "$ref": "#/components/schemas/MapDoc" } }, "required": [ "baseVersion", "root" ] }, "example": { "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" } ] } ] } } } } }, "responses": { "200": { "description": "Gravado", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Versão nova" } }, "required": [ "version" ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "413": { "$ref": "#/components/responses/E413" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/maps/{id}/duplicate": { "post": { "operationId": "duplicateMap", "summary": "Duplicar mapa", "description": "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. Exige token com escopo \"Ver e editar\".", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Id do mapa (de GET /api/maps)" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Versão do histórico (opcional)" } }, "required": [] }, "example": {} } } }, "responses": { "201": { "description": "Copiado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da cópia" }, "version": { "type": "integer", "description": "Sempre 1" }, "title": { "type": "string", "description": "Título da cópia" } }, "required": [ "id", "version", "title" ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "413": { "$ref": "#/components/responses/E413" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/maps/{id}/revisions": { "get": { "operationId": "listRevisions", "summary": "Histórico", "description": "Versões do mapa, da mais nova para a mais antiga, em páginas. Para a próxima página, mande `before` = `nextBefore`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Id do mapa (de GET /api/maps)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "before", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Só versões menores que esta" } ], "responses": { "200": { "description": "Uma página do histórico", "content": { "application/json": { "schema": { "type": "object", "properties": { "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } }, "nextBefore": { "type": [ "integer", "null" ] } }, "required": [ "revisions", "nextBefore" ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/maps/{id}/revisions/{version}": { "get": { "operationId": "getRevision", "summary": "Abrir uma versão", "description": "O documento como estava naquela versão.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Id do mapa (de GET /api/maps)" }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A versão", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Revision" }, { "type": "object", "properties": { "root": { "$ref": "#/components/schemas/MapDoc" } }, "required": [ "root" ] } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/maps/{id}/restore": { "post": { "operationId": "restoreRevision", "summary": "Restaurar uma versão", "description": "Grava o documento de `version` como versão nova (nada é apagado do histórico). `baseVersion` funciona como no PUT. Exige token com escopo \"Ver e editar\".", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Id do mapa (de GET /api/maps)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Versão a restaurar" }, "baseVersion": { "type": "integer", "description": "Versão atual lida" } }, "required": [ "version", "baseVersion" ] }, "example": { "version": 1, "baseVersion": 1 } } } }, "responses": { "200": { "description": "Restaurado", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Versão nova" } }, "required": [ "version" ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "413": { "$ref": "#/components/responses/E413" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/account/prefs": { "get": { "operationId": "getPrefs", "summary": "Preferências", "description": "O padrão de mapa novo e o tema dos estilos.", "responses": { "200": { "description": "As preferências", "content": { "application/json": { "schema": { "type": "object", "properties": { "prefs": { "$ref": "#/components/schemas/Prefs" } }, "required": [ "prefs" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } }, "patch": { "operationId": "patchPrefs", "summary": "Mudar preferências", "description": "Muda só os campos mandados; `null` volta ao padrão. Não mexe em nenhum mapa existente. Exige token com escopo \"Ver e editar\".", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "newMap": { "type": [ "object", "null" ] }, "styleTheme": { "type": [ "string", "null" ], "enum": [ "light", null ] } }, "required": [] }, "example": { "newMap": { "st": "vivas", "ly": "horizontal" } } } } }, "responses": { "200": { "description": "As preferências depois da mudança", "content": { "application/json": { "schema": { "type": "object", "properties": { "prefs": { "$ref": "#/components/schemas/Prefs" } }, "required": [ "prefs" ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } }, "put": { "operationId": "putPrefs", "summary": "Trocar preferências", "description": "Substitui as preferências inteiras. Exige token com escopo \"Ver e editar\".", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prefs": { "$ref": "#/components/schemas/Prefs" } }, "required": [ "prefs" ] }, "example": { "prefs": { "styleTheme": "light" } } } } }, "responses": { "200": { "description": "As preferências gravadas", "content": { "application/json": { "schema": { "type": "object", "properties": { "prefs": { "$ref": "#/components/schemas/Prefs" } }, "required": [ "prefs" ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } } }, "components": { "securitySchemes": { "token": { "type": "http", "scheme": "bearer", "description": "Token pessoal `mm_…`. Escopo \"Ver mapas\" só lê; \"Ver e editar\" também grava." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Código estável, para o programa decidir", "enum": [ "unauthenticated", "forbidden", "bad_origin", "not_found", "bad_request", "invalid_map", "version_conflict", "payload_too_large", "unsupported_media_type", "quota_exceeded", "rate_limited" ] }, "message": { "type": "string", "description": "Texto em português, para gente" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Node": { "type": "object", "properties": { "id": { "type": "integer", "description": "Id do nó, único no documento (≥ 0)" }, "t": { "type": "array", "items": { "type": "string" }, "description": "Texto do nó, uma linha por item (até 20 linhas de 500 caracteres)" }, "k": { "type": "array", "items": { "$ref": "#/components/schemas/Node" }, "description": "Filhos, em ordem" }, "note": { "type": "string", "description": "Nota (até 100.000 caracteres)" }, "side": { "type": "string", "description": "Lado do ramo no 1º nível", "enum": [ "L", "R" ] }, "p": { "type": "integer", "description": "Cor do ramo no 1º nível (índice da paleta do estilo)" }, "c": { "type": "integer", "description": "1 = recolhido", "enum": [ 1 ] }, "x": { "type": "integer", "description": "Só nos nós centrais: posição horizontal do centro" }, "y": { "type": "integer", "description": "Só nos nós centrais: posição vertical do centro" }, "ck": { "type": "integer", "description": "Caixa de seleção: 1 marcada, 0 desmarcada", "enum": [ 0, 1 ] }, "g": { "type": "integer", "description": "1 = borda de ramo", "enum": [ 1 ] }, "ly": { "type": "string", "description": "Layout próprio do ramo", "enum": [ "free", "horizontal", "vertical", "topdown", "linear", "radial", "matrix", "list" ] } }, "required": [ "id", "t" ] }, "MapDoc": { "type": "object", "properties": { "id": { "type": "integer", "description": "Sempre -1 (contêiner invisível)", "enum": [ -1 ] }, "v": { "type": "integer", "description": "Versão do formato: sempre 2", "enum": [ 2 ] }, "t": { "type": "array", "items": { "type": "string" }, "description": "Título do mapa = texto do 1º nó central" }, "k": { "type": "array", "items": { "$ref": "#/components/schemas/Node" }, "minItems": 1, "description": "Nós centrais (cada um com x e y)" }, "n": { "type": "integer", "description": "Próximo id livre (opcional; o servidor recalcula)" }, "r": { "type": "array", "description": "Ligações entre nós: { id, a: origem, b: destino, l?: rótulo }", "items": { "type": "object" } }, "gr": { "type": "array", "description": "Bordas de grupo: { id, m: ids dos membros }", "items": { "type": "object" } }, "st": { "type": "string", "description": "Estilo do mapa (ex.: \"nuture\", \"vivas\")" }, "ly": { "type": "string", "description": "Layout do mapa" } }, "required": [ "id", "v", "t", "k" ], "description": "Documento do mapa. Até 10.000 nós, 200 níveis e 1,8 MB. Campos desconhecidos são recusados (invalid_map)." }, "MapListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Id do mapa" }, "title": { "type": "string", "description": "Título" }, "version": { "type": "integer", "description": "Versão atual" }, "updated_at": { "type": "integer", "description": "Última gravação (ms desde 1970)" }, "shared": { "type": "boolean", "description": "Só nos seus: há alguém convidado" }, "origin": { "type": [ "string", "null" ], "enum": [ "modelo", "mapa", null ], "description": "De onde veio a cópia: \"modelo\" ou \"mapa\" da galeria; null = não veio da galeria (ou o item saiu dela)" } }, "required": [ "id", "title", "version", "updated_at" ] }, "SharedMapListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Id do mapa" }, "title": { "type": "string", "description": "Título" }, "version": { "type": "integer", "description": "Versão atual" }, "updated_at": { "type": "integer", "description": "Última gravação (ms desde 1970)" }, "role": { "type": "string", "description": "Seu papel", "enum": [ "editor", "viewer" ] }, "owner_email": { "type": "string", "description": "E-mail de quem compartilhou" }, "origin": { "type": [ "string", "null" ], "enum": [ "modelo", "mapa", null ], "description": "De onde veio a cópia (do dono): \"modelo\" ou \"mapa\" da galeria; null = não veio da galeria" } }, "required": [ "id", "title", "version", "updated_at", "role", "owner_email", "origin" ] }, "Map": { "type": "object", "properties": { "id": { "type": "string", "description": "Id do mapa" }, "title": { "type": "string", "description": "Título" }, "version": { "type": "integer", "description": "Versão atual (use como baseVersion ao gravar)" }, "access": { "type": "string", "description": "Seu acesso", "enum": [ "owner", "editor", "viewer" ] }, "root": { "$ref": "#/components/schemas/MapDoc" } }, "required": [ "id", "title", "version", "access", "root" ] }, "Summary": { "type": "object", "properties": { "added": { "type": "integer", "description": "Nós added" }, "removed": { "type": "integer", "description": "Nós removed" }, "renamed": { "type": "integer", "description": "Nós renamed" }, "moved": { "type": "integer", "description": "Nós moved" }, "recolored": { "type": "integer", "description": "Nós recolored" }, "noted": { "type": "integer", "description": "Nós noted" }, "linked": { "type": "integer", "description": "Nós linked" }, "grouped": { "type": "integer", "description": "Nós grouped" }, "checked": { "type": "integer", "description": "Nós checked" }, "restyled": { "type": "integer", "description": "Nós restyled" } }, "required": [ "added", "removed", "renamed", "moved", "recolored", "noted" ] }, "Revision": { "type": "object", "properties": { "version": { "type": "integer", "description": "Versão" }, "authorLabel": { "type": "string", "description": "Quem gravou (e-mail só para o dono do mapa)" }, "via": { "type": "string", "description": "Origem", "enum": [ "web", "token", "restore", "import" ] }, "summary": { "$ref": "#/components/schemas/Summary" }, "startedAt": { "type": "integer", "description": "Início da sessão de edição (ms)" }, "updatedAt": { "type": "integer", "description": "Última gravação da revisão (ms)" } }, "required": [ "version", "authorLabel", "via", "summary", "startedAt", "updatedAt" ] }, "Prefs": { "type": "object", "properties": { "newMap": { "type": "object", "properties": { "st": { "type": "string", "description": "Estilo" }, "ly": { "type": "string", "description": "Layout" }, "ld": { "type": "string", "description": "Direção do layout" } }, "required": [], "description": "Padrão de mapa novo em branco" }, "styleTheme": { "type": "string", "description": "\"light\" = estilos não acompanham o tema escuro", "enum": [ "light" ] } }, "required": [] } }, "responses": { "E400": { "description": "Pedido inválido (bad_request, invalid_map)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "Sem token, ou token inválido, vencido ou revogado (unauthenticated)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "Token só de leitura numa escrita, ou sem permissão no mapa (forbidden); escrita sem o cabeçalho Authorization (bad_origin)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "Mapa ou versão não existe para você (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "Outra versão foi gravada no meio (version_conflict); error.current traz a versão e o documento atuais", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E413": { "description": "Corpo acima de 2 MB (payload_too_large) ou sem espaço na conta (quota_exceeded)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "Muitas leituras ou gravações; espere os segundos de Retry-After (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }