# Referência da API Torêva

Recursos públicos de API e descoberta expostos por `toreva.com.br`. O guia
completo, com início rápido e exemplos, está em
<https://toreva.com.br/developers>.

Tudo aqui é público, somente leitura e não exige autenticação nem cadastro.

## Versão

A versão fica no caminho: `/api/v1/...`. Versão corrente: **v1**.

`/api/...` sem versão é apelido da versão estável corrente e pode mudar de
destino. **Integre contra `/api/v1/`.** Toda resposta traz `API-Version` com a
versão que respondeu. A política de depreciação, com os cabeçalhos `Deprecation`
e `Sunset`, está em <https://toreva.com.br/docs/versioning.md>.

## API pública

- `GET /api/v1`
  - Content type: `application/json`
  - Índice da versão: endpoints, política de versão, limite de taxa, onboarding
    e catálogo de erros. É o primeiro pedido que um cliente novo deve fazer.
- `GET /api/v1/status`
  - Content type: `application/json`
  - Estado dos serviços públicos, componente a componente.
- `GET /api` e `GET /api/status`
  - Content type: `application/json`
  - Apelidos sem versão dos dois acima.

Qualquer caminho sob `/api/` que não exista responde **404 com corpo JSON** —
nunca HTML.

## Limite de taxa

**120 requisições por minuto por cliente**, com rajada de 60 liberada de
imediato. Toda resposta sob `/api/` traz:

```
API-Version: v1
RateLimit: limit=120, remaining=117, reset=43
RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 43
RateLimit-Policy: "public-api";q=120;w=60
```

`RateLimit-Remaining` é o saldo real daquele cliente; `RateLimit-Reset` é a
contagem regressiva até o próximo slot vagar. A janela é deslizante de 60
segundos, então o saldo se recompõe aos poucos.

Ao estourar, a resposta é `429` com `error.code` igual a `rate_limited` e um
`Retry-After` calculado — os segundos exatos até haver saldo.

A contagem é por cliente e por instância do serviço. Um anteparo separado, bem
acima desse teto, protege contra enxurrada e também responde `429`.

## MCP

- `POST /.well-known/mcp`
  - Content type: `application/json`
  - Servidor MCP público, transporte Streamable HTTP, JSON-RPC 2.0, sem
    autenticação. Aceita `initialize`, `ping`, `tools/list`, `tools/call`,
    `resources/list` e `resources/read`. `GET` responde `405`: não há stream SSE.
  - Cartão: `GET /.well-known/mcp/server-card.json`
  - Apelido: `POST /mcp`

## Descoberta

- `GET /.well-known/openapi.json` (e `GET /openapi.json`)
  - Content type: `application/json`
  - Descrição OpenAPI 3.1, com schema de erro tipado em todas as operações.
- `GET /.well-known/api-catalog`
  - Content type: `application/linkset+json`
  - Linkset de descoberta (RFC 9727).
- `GET /.well-known/status.json`
  - Content type: `application/json`
  - Cartão estático de status.
- `GET /.well-known/agent-skills/index.json`
  - Content type: `application/json`
  - Habilidades declaradas para agentes, com hash por arquivo.
- `GET /agent-instructions.md`
  - Content type: `text/markdown`
  - Quando usar a Torêva, quando não usar e como chamar cada superfície.
- `GET /llms.txt`
  - Content type: `text/plain`
  - Mapa do domínio para modelos de linguagem.

## Páginas

- `GET /consulta-cnpj/`
  - Content type: `text/html`
  - Consulta pública de CNPJ. Fichas em `/consulta-cnpj/{14 dígitos}`, que
    redireciona para a URL canônica com slug.
- `GET /developers`
  - Content type: `text/html` ou `text/markdown`
  - Portal do desenvolvedor. Responde markdown quando o `Accept` pede; a
    resposta traz `Vary: Accept`.
- `GET /sobre` (também em `/about`) e `GET /contato` (também em `/contact`)
  - Content type: `text/html`
  - Páginas institucionais com razão social, CNPJ, endereço e canais.

## Formato de erro

Todas as respostas de erro sob `/api/` seguem o mesmo objeto:

```json
{
  "error": {
    "code": "not_found",
    "status": 404,
    "message": "Endpoint não encontrado.",
    "hint": "Consulte https://toreva.com.br/api/v1 para a lista de endpoints públicos.",
    "documentation": "https://toreva.com.br/developers"
  }
}
```

| `code` | status | Quando acontece |
| --- | --- | --- |
| `not_found` | 404 | O caminho sob `/api/` não existe. |
| `method_not_allowed` | 405 | A API pública é somente leitura: use GET, HEAD ou OPTIONS. |
| `rate_limited` | 429 | Limite de taxa excedido. Respeite `Retry-After`. |
| `upstream_unavailable` | 503 | Origem indisponível. Falhas de gateway 502/503/504 são normalizadas aqui. |
| `endpoint_sunset` | 410 | O endpoint foi desligado após o prazo do `Sunset`. |

`error.code` é contrato; `error.message` é texto para humanos e pode ser
reescrito. Ramifique pelo código.

Fora de `/api/`, um caminho inexistente responde **HTTP 404 real** — HTML por
padrão e markdown para quem enviar `Accept: text/markdown`.

## Negociação de conteúdo

`/` e `/developers` têm duas representações na mesma URL:

```
curl -H "Accept: text/markdown" https://toreva.com.br/
curl -H "Accept: text/markdown" https://toreva.com.br/developers
```

As respostas negociadas enviam `Vary: Accept, Accept-Encoding`.

## Autenticação

Os endpoints públicos de descoberta não exigem autenticação. As APIs de conta
são protegidas e ficam na aplicação em `https://app.toreva.com.br`.

Veja `https://toreva.com.br/auth.md` para as regras de registro e de atuação de
agentes.