{"title":"Visão geral da API e URL base","slug":"overview","category":"api","summary":"Todos os endpoints da API do Synapse, URL base, padrões de autenticação e formatos de resposta em um só lugar.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":590,"read_minutes":3,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# Visão geral da API e URL base\n\nA API do Synapse é uma API HTTP RESTful. Todos os endpoints retornam JSON (exceto\nquando indicado de outra forma). Esta página cobre o essencial que você precisa\nantes de explorar endpoints específicos.\n\n## URL base\n\n```\nhttps://synapse.schaefer.zone\n```\n\nTodos os caminhos nesta documentação são relativos a esta URL base. Para\ninstâncias auto-hospedadas, substitua pela sua própria URL.\n\n## Autenticação\n\nDois métodos, ambos enviados via cabeçalho `Authorization`:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # para endpoints de dados\nAuthorization: Bearer YOUR_JWT # para endpoints de conta\n```\n\nOu via parâmetro de consulta (limitado a 60/min):\n\n```\n?key=YOUR_MIND_KEY\n```\n\nConsulte [Autenticação](/docs/getting-started/authentication) para detalhes.\n\n## Grupos de endpoints\n\n| Grupo | Auth | Descrição |\n|-------|------|-----------|\n| Público | Nenhuma | Página inicial, health, OpenAPI, docs |\n| Memória | Mind Key | CRUD, busca, sincronização, embeddings |\n| Chat | Mind Key / JWT | Mensagens assíncronas entre humano e agente |\n| Tarefas | Mind Key | Gerenciamento de tarefas |\n| Scripts | Mind Key / JWT | Armazenamento persistente de scripts |\n| Agendador | Mind Key | Cron jobs + variáveis |\n| Webhooks | Mind Key | Callbacks HTTP em eventos |\n| Computadores | Mind Key / JWT | Controle de computadores remotos |\n| Usuário/Minds | JWT | Conta + gerenciamento de minds |\n| Compartilhamento | JWT | Compartilhamento de minds entre usuários |\n| Push | JWT | Assinaturas Web Push |\n| Ferramentas | Nenhuma | Hora, calc, aleatório (utilidades públicas) |\n\n## Formatos de resposta\n\n- **JSON** (padrão): `{ \"key\": \"value\", ... }`\n- **Texto puro**: `/memory/recall` retorna texto otimizado para LLMs\n- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`\n\n## Envelope de resposta padrão\n\nRespostas de sucesso retornam os dados diretamente:\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nRespostas de erro usam este formato:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n> [!NOTE]\n> O campo `docs` aponta para a documentação relevante dos erros comuns.\n\n## Códigos de status HTTP\n\n| Código | Significado |\n|--------|-------------|\n| 200 | Sucesso (GET, PUT) |\n| 201 | Criado (POST) |\n| 204 | Sem conteúdo (DELETE) |\n| 400 | Requisição inválida (erro de validação) |\n| 401 | Não autorizado (token ausente/inválido) |\n| 403 | Proibido (tipo de token incorreto) |\n| 404 | Não encontrado (caminho não existe) |\n| 409 | Conflito (duplicado) |\n| 429 | Muitas requisições (rate limit) |\n| 500 | Erro de servidor |\n\n## Endpoints de descoberta\n\n| Endpoint | Finalidade |\n|----------|------------|\n| `GET /` | Página inicial (otimizada para LLMs) |\n| `GET /endpoints` | Lista legível por máquina de todos os endpoints |\n| `GET /endpoints?format=text` | Lista de endpoints em texto puro |\n| `GET /openapi.json` | Especificação OpenAPI 3.0 |\n| `GET /help` | Documentação completa da API (HTML) |\n| `GET /help?format=json` | Docs da API em JSON |\n| `GET /docs` | Sistema de documentação (HTML) |\n| `GET /docs?format=json` | Índice da documentação (JSON) |\n| `GET /docs?format=text&scope=all` | Todas as docs em um único bloco de texto |\n| `GET /playground` | Playground interativo da API |\n\n## Limites de taxa (rate limits)\n\n| Método de auth | Limite |\n|----------------|--------|\n| Mind Key (header) | Nenhum |\n| Mind Key (?key=) | 60/min por IP |\n| JWT (header) | Nenhum |\n| Endpoints públicos | Nenhum |\n\nRespostas com limite de taxa incluem:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (only when 429)\n```\n\n## Paginação\n\nEndpoints de listagem suportam `?limit=` e `?offset=`:\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nLimite padrão: 100. Limite máximo: 500.\n\n## CORS\n\nTodos os endpoints suportam CORS para clientes baseados em navegador:\n\n```\nAccess-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## SDKs e clientes\n\n- **SDK Node.js**: `npm install synapse-memory-sdk` ([repo](https://gitlab.com/schaefer-services/synapse-sdk-js))\n- **Servidor MCP**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))\n- **Cliente HTTP**: qualquer biblioteca HTTP (curl, fetch, axios, etc.)\n\n## Próximos passos\n\n- [API de Memória](/docs/api/memory) — os endpoints mais importantes\n- [API de Chat](/docs/api/chat) — comunicação assíncrona humano-agente\n- [Erros e tratamento de erros](/docs/api/errors)\n","content_html":"

Visão geral da API e URL base

\n

A API do Synapse é uma API HTTP RESTful. Todos os endpoints retornam JSON (exceto\nquando indicado de outra forma). Esta página cobre o essencial que você precisa\nantes de explorar endpoints específicos.

\n

URL base

\n
https://synapse.schaefer.zone

Todos os caminhos nesta documentação são relativos a esta URL base. Para\ninstâncias auto-hospedadas, substitua pela sua própria URL.

\n

Autenticação

\n

Dois métodos, ambos enviados via cabeçalho Authorization:

\n
Authorization: Bearer YOUR_MIND_KEY    # para endpoints de dados\nAuthorization: Bearer YOUR_JWT          # para endpoints de conta

Ou via parâmetro de consulta (limitado a 60/min):

\n
?key=YOUR_MIND_KEY

Consulte Autenticação para detalhes.

\n

Grupos de endpoints

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
GrupoAuthDescrição
PúblicoNenhumaPágina inicial, health, OpenAPI, docs
MemóriaMind KeyCRUD, busca, sincronização, embeddings
ChatMind Key / JWTMensagens assíncronas entre humano e agente
TarefasMind KeyGerenciamento de tarefas
ScriptsMind Key / JWTArmazenamento persistente de scripts
AgendadorMind KeyCron jobs + variáveis
WebhooksMind KeyCallbacks HTTP em eventos
ComputadoresMind Key / JWTControle de computadores remotos
Usuário/MindsJWTConta + gerenciamento de minds
CompartilhamentoJWTCompartilhamento de minds entre usuários
PushJWTAssinaturas Web Push
FerramentasNenhumaHora, calc, aleatório (utilidades públicas)
\n

Formatos de resposta

\n\n

Envelope de resposta padrão

\n

Respostas de sucesso retornam os dados diretamente:

\n
{ "id": "mem_001", "status": "stored" }

Respostas de erro usam este formato:

\n
{\n  "statusCode": 401,\n  "error": "Unauthorized",\n  "message": "Mind Key fehlt oder ungültig.",\n  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}
O campo `docs` aponta para a documentação relevante dos erros comuns.

Códigos de status HTTP

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CódigoSignificado
200Sucesso (GET, PUT)
201Criado (POST)
204Sem conteúdo (DELETE)
400Requisição inválida (erro de validação)
401Não autorizado (token ausente/inválido)
403Proibido (tipo de token incorreto)
404Não encontrado (caminho não existe)
409Conflito (duplicado)
429Muitas requisições (rate limit)
500Erro de servidor
\n

Endpoints de descoberta

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointFinalidade
GET /Página inicial (otimizada para LLMs)
GET /endpointsLista legível por máquina de todos os endpoints
GET /endpoints?format=textLista de endpoints em texto puro
GET /openapi.jsonEspecificação OpenAPI 3.0
GET /helpDocumentação completa da API (HTML)
GET /help?format=jsonDocs da API em JSON
GET /docsSistema de documentação (HTML)
GET /docs?format=jsonÍndice da documentação (JSON)
GET /docs?format=text&scope=allTodas as docs em um único bloco de texto
GET /playgroundPlayground interativo da API
\n

Limites de taxa (rate limits)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Método de authLimite
Mind Key (header)Nenhum
Mind Key (?key=)60/min por IP
JWT (header)Nenhum
Endpoints públicosNenhum
\n

Respostas com limite de taxa incluem:

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (only when 429)

Paginação

\n

Endpoints de listagem suportam ?limit= e ?offset=:

\n
GET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending

Limite padrão: 100. Limite máximo: 500.

\n

CORS

\n

Todos os endpoints suportam CORS para clientes baseados em navegador:

\n
Access-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT, Mcp-Session-Id, Mcp-Tool-Profile

SDKs e clientes

\n\n

Próximos passos

\n\n","urls":{"html":"/docs/api/overview","text":"/docs/api/overview?format=text","json":"/docs/api/overview?format=json","llm":"/docs/api/overview?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}