# 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](/docs/getting-started/authentication) 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:

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

Respostas de erro usam este formato:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

> [!NOTE]
> 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](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **Servidor MCP**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))
- **Cliente HTTP**: qualquer biblioteca HTTP (curl, fetch, axios, etc.)

## Próximos passos

- [API de Memória](/docs/api/memory) — os endpoints mais importantes
- [API de Chat](/docs/api/chat) — comunicação assíncrona humano-agente
- [Erros e tratamento de erros](/docs/api/errors)