Skip to main content

Visão geral da API e URL base

beginner 🤖 Compatível com LLM 3 min · 590 palavras Atualizado: 2026-06-27 Português

Todos os endpoints da API do Synapse, URL base, padrões de autenticação e formatos de resposta em um só lugar.

Ler este artigo como: 📄 Texto simples ⚡ JSON 🤖 Formato LLM
Idioma: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

Visão geral da API e URL base

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

URL base

https://synapse.schaefer.zone

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

Autenticação

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

Authorization: Bearer YOUR_MIND_KEY    # para endpoints de dados
Authorization: Bearer YOUR_JWT          # para endpoints de conta

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

?key=YOUR_MIND_KEY

Consulte Autenticação para detalhes.

Grupos de endpoints

Grupo Auth Descrição
Público Nenhuma Página inicial, health, OpenAPI, docs
Memória Mind Key CRUD, busca, sincronização, embeddings
Chat Mind Key / JWT Mensagens assíncronas entre humano e agente
Tarefas Mind Key Gerenciamento de tarefas
Scripts Mind Key / JWT Armazenamento persistente de scripts
Agendador Mind Key Cron jobs + variáveis
Webhooks Mind Key Callbacks HTTP em eventos
Computadores Mind Key / JWT Controle de computadores remotos
Usuário/Minds JWT Conta + gerenciamento de minds
Compartilhamento JWT Compartilhamento de minds entre usuários
Push JWT Assinaturas Web Push
Ferramentas Nenhuma Hora, calc, aleatório (utilidades públicas)

Formatos de resposta

  • JSON (padrão): { "key": "value", ... }
  • Texto puro: /memory/recall retorna texto otimizado para LLMs
  • HTML: /, /docs, /human, /support, /playground

Envelope de resposta padrão

Respostas de sucesso retornam os dados diretamente:

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

Respostas de erro usam este formato:

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

Códigos de status HTTP

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

Endpoints de descoberta

Endpoint Finalidade
GET / Página inicial (otimizada para LLMs)
GET /endpoints Lista legível por máquina de todos os endpoints
GET /endpoints?format=text Lista de endpoints em texto puro
GET /openapi.json Especificação OpenAPI 3.0
GET /help Documentação completa da API (HTML)
GET /help?format=json Docs da API em JSON
GET /docs Sistema de documentação (HTML)
GET /docs?format=json Índice da documentação (JSON)
GET /docs?format=text&scope=all Todas as docs em um único bloco de texto
GET /playground Playground interativo da API

Limites de taxa (rate limits)

Método de auth Limite
Mind Key (header) Nenhum
Mind Key (?key=) 60/min por IP
JWT (header) Nenhum
Endpoints públicos Nenhum

Respostas com limite de taxa incluem:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (only when 429)

Paginação

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

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

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

CORS

Todos os endpoints suportam CORS para clientes baseados em navegador:

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

SDKs e clientes

  • SDK Node.js: npm install synapse-memory-sdk (repo)
  • Servidor MCP: npx -y synapse-mcp-api@latest (repo)
  • Cliente HTTP: qualquer biblioteca HTTP (curl, fetch, axios, etc.)

Próximos passos

← Voltar a Referência da API