# Rota Nacional — referência completa da API

> Gerada do catálogo em https://staging.rota-nacional.ia.br · build `dev`
> 67 endpoints · 6 estruturas
> Índice curto: https://staging.rota-nacional.ia.br/llms.txt · Spec: https://staging.rota-nacional.ia.br/openapi.json · MCP: https://staging.rota-nacional.ia.br/mcp

> Referência completa. O catálogo é público; o resto pede a chave de API da conta.

## Como ler

- Cada endpoint traz caminho, auth, parâmetros, corpo, estrutura da resposta, erros e uma chamada que roda.
- `Pagina<Canal>` é referência: os campos estão em **Estruturas**, no fim, uma vez só.
- `(opcional)` num campo quer dizer que ele pode não vir; `(pode ser null)` quer dizer que vem com valor nulo.
- Fatie o que precisa: `https://staging.rota-nacional.ia.br/llms-full.txt?prefix=/api/` devolve só aquele ramo.

## Autenticação

- `none` — Público.
- `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.
- `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.
- `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou header `X-Credito`). Não é conta: é portador de saldo.

## Endpoints

## Conta

### `GET /api/auth/bootstrap`

Prepara o navegador para entrar na conta global.

Define cookie HttpOnly restrito ao host. CSRF vinculado à sessão atual. Sem CORS.

- **URL:** `https://staging.rota-nacional.ia.br/api/auth/bootstrap`
- **Auth:** `none` — Público.

**Resposta `200`**

- `csrf` (string) — X-CSRF-Token
- `context` (string) — Opaque view context, also in X-MM-Context; not a credential / contexto opaco da vista, não é credencial.

**Erros**

- `400` — invalid_request
- `403` — invalid_origin / invalid_csrf
- `503` — auth_unavailable: a sessão anterior é preservada / the previous session is preserved

### `GET /api/account/profile`

Consulta seu perfil global.

Lê preferências atuais da conta. Altere-as na página da conta; produtos não mantêm perfil autoritativo separado.

- **URL:** `https://staging.rota-nacional.ia.br/api/account/profile`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

{profile:{name,locale,timeZone,theme,revision}}

**Erros**

- `401` — invalid_session
- `503` — auth_unavailable

**Exemplo**

```js
await fetch("https://staging.rota-nacional.ia.br/api/account/profile", {credentials: "same-origin"}).then(r => r.json());
```

### `GET /api/account/avatar`

Consulta sua foto de perfil global.

WebP privado de até 64 KiB, sem cache. Altere-o na conta. Não aceita ID de usuário ou URL de objeto.

- **URL:** `https://staging.rota-nacional.ia.br/api/account/avatar`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

image/webp; Cache-Control: no-store

**Erros**

- `401` — invalid_session
- `404` — not_found: no photo / sem foto
- `503` — auth_unavailable

**Exemplo**

```js
await fetch("https://staging.rota-nacional.ia.br/api/account/avatar", {credentials: "same-origin"}).then(r => {if (!r.ok) throw new Error("HTTP " + r.status); return r.blob();});
```

### `GET /api/me`

Lê a conta global atual neste produto.

- **URL:** `https://staging.rota-nacional.ia.br/api/me`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

{user:{identityId,sessionId,productId,audience,authTime,methods,mfaState}}

**Erros**

- `401` — invalid_session
- `503` — auth_unavailable

**Exemplo**

```js
await fetch("https://staging.rota-nacional.ia.br/api/me", {credentials: "same-origin"}).then(r => r.json());
```

### `POST /api/auth/logout`

Revoga esta sessão do produto.

Exige bootstrap/CSRF deste navegador e sessão. As sessões de outros produtos permanecem ativas.

- **URL:** `https://staging.rota-nacional.ia.br/api/auth/logout`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

- `ok` (bool) — true

**Erros**

- `400` — invalid_request
- `403` — invalid_origin / invalid_csrf
- `503` — auth_unavailable: a sessão anterior é preservada / the previous session is preserved

**Exemplo**

```js
// Execute no console da página do produto / Run in the product page console.
(async () => {
  const origin = "https://staging.rota-nacional.ia.br";
  const {csrf} = await fetch(origin + "/api/auth/bootstrap").then(r => r.json());
  const r = await fetch(origin + "/api/auth/logout", {
    method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({})
  });
  if (!r.ok) throw new Error("Auth HTTP " + r.status);
  return r.json();
})();
```

### `GET /api/account/keys`

Lista suas chaves de API neste produto.

Nunca devolve a chave: nome, 4 últimos caracteres, organização, criação, último uso (por hora) e se ainda vale.

- **URL:** `https://staging.rota-nacional.ia.br/api/account/keys`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

- `keys` (object[]) — `id`, `name`, `organizationId`, `last4`, `createdAt`, `lastUsedAt`, `revokedAt`, `active` (false quando revogada ou parada por troca de senha / encerrar todos os acessos).

**Erros**

- `401` — invalid_session
- `503` — auth_unavailable

**Exemplo**

```js
await fetch("https://staging.rota-nacional.ia.br/api/account/keys", {credentials: "same-origin"}).then(r => r.json());
```

### `POST /api/account/keys/create`

Cria uma chave de API para agentes e scripts.

Exige entrada nos últimos 5 minutos; a de organização também exige segundo fator na sessão e o papel de dona/administradora com o produto ligado. No máximo 10 chaves vivas por conta e produto. A chave (`secret`) volta UMA vez.

- **URL:** `https://staging.rota-nacional.ia.br/api/account/keys/create`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Corpo** (`application/json`)

- `name` (string, obrigatório) — Até 60 caracteres.
- `organizationId` (string, obrigatório) — `null` para chave da conta.

**Exemplo de corpo**

```json
{
  "name": "agent",
  "organizationId": null
}
```

**Resposta `200`**

- `key` (object) — `id`, `name`, `organizationId`, `last4`, `createdAt`.
- `secret` (string) — `mmk_…`, mostrada uma vez.

**Erros**

- `400` — invalid_key_name / invalid_organization
- `401` — invalid_session / reauth_required
- `403` — invalid_origin / invalid_csrf / organization_forbidden / organization_mfa_required
- `409` — key_limit_reached
- `503` — auth_unavailable

**Exemplo**

```js
(async () => {
  const {csrf} = await fetch("https://staging.rota-nacional.ia.br/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://staging.rota-nacional.ia.br/api/account/keys/create", {method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({name: "agent", organizationId: null})});
  return r.json();
})();
```

### `POST /api/account/keys/revoke`

Revoga uma das suas chaves de API.

Para a chave na hora. Repetir não faz mal.

- **URL:** `https://staging.rota-nacional.ia.br/api/account/keys/revoke`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Corpo** (`application/json`)

- `id` (string, obrigatório) — O `id` da chave.

**Exemplo de corpo**

```json
{
  "id": "…"
}
```

**Resposta `200`**

- `ok` (bool) — true

**Erros**

- `400` — invalid_key_id
- `401` — invalid_session
- `403` — invalid_origin / invalid_csrf
- `404` — key_not_found
- `503` — auth_unavailable

**Exemplo**

```js
(async () => {
  const {csrf} = await fetch("https://staging.rota-nacional.ia.br/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://staging.rota-nacional.ia.br/api/account/keys/revoke", {method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({id: "…"})});
  return r.json();
})();
```

## Descoberta

### `GET /api/`

Índice auto-descrito: cada rota, o que cobra e como plugar o MCP.

- **URL:** `https://staging.rota-nacional.ia.br/api/`
- **Auth:** `none` — Público.

**Resposta `200`**

- `name` (string) — Nome do produto.
- `description` (string) — O que o produto faz.
- `build` (string) — Commit publicado.
- `base_url` (string) — Origem em que esta API está servindo.
- `docs` (object) — Links para llms.txt, OpenAPI, MCP e a UI.
- `endpoints` (object[]) — Catálogo de endpoints.
- `mcp_tools` (string[]) — Tools do MCP.

### `GET /api/health`

Se o serviço responde, e o build no ar.

- **URL:** `https://staging.rota-nacional.ia.br/api/health`
- **Auth:** `none` — Público.

**Resposta `200`**

- `ok` (bool) — Sempre `true` quando o processo responde.
- `service` (string) — O serviço: `rota-nacional`.
- `build` (string) — O commit no ar.
- `request_id` (string) — O id deste pedido, para o suporte.

### `POST /mcp`

MCP Streamable HTTP — as tools deste catálogo, despachadas neste mesmo Worker.

- **URL:** `https://staging.rota-nacional.ia.br/mcp`
- **Auth:** `none` — Público.

**Resposta `200`**

JSON-RPC 2.0 (`initialize`, `tools/list`, `tools/call`).

**Exemplo**

```sh
curl -s -XPOST https://staging.rota-nacional.ia.br/mcp -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

### `GET /api/pricing`

Preços vigentes e franquias gratuitas.

- **URL:** `https://staging.rota-nacional.ia.br/api/pricing`
- **Auth:** `none` — Público.

**Resposta `200`**

- `product` (string) — Product name.
- `quota` (PaymentQuota) — Public allowances and current list prices; not personal usage. → ver `PaymentQuota` em **Estruturas**.
- `pricing` (string) — Absolute URL of the current price list.
- `billing` (string) — Absolute URL of payment discovery or the existing billing summary.
- `api_index` (string) — Absolute URL of the API catalog.

**Erros**

- `405` — Use GET ou HEAD.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/pricing
```

### `GET /api/billing`

Descoberta pública de pagamento e crédito pré-pago.

- **URL:** `https://staging.rota-nacional.ia.br/api/billing`
- **Auth:** `none` — Público.

**Resposta `200`**

- `product` (string) — Product name.
- `quota` (PaymentQuota) — Public allowances and current list prices; not personal usage. → ver `PaymentQuota` em **Estruturas**.
- `pricing` (string) — Absolute URL of the current price list.
- `billing` (string) — Absolute URL of payment discovery or the existing billing summary.
- `api_index` (string) — Absolute URL of the API catalog.
- `payment` (PaymentX402) — Public x402 configuration; pay_to=null means not configured. → ver `PaymentX402` em **Estruturas**.
- `credit` (PaymentCredit) — Prepaid credit entry point. Never contains a balance or token. → ver `PaymentCredit` em **Estruturas**.

**Erros**

- `405` — Use GET ou HEAD.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/billing
```

## Operação

### `POST /api/erro-cliente`

Relato de erro do navegador, enviado pela própria interface. Agente não precisa chamar.

A interface relata sozinha erro de JS, promessa rejeitada, script/CSS que não carregou e bloqueio de CSP — uma vez por sessão — e o app relata falha tratada por `window.mmErro.relata`. O servidor valida o envelope, redige credencial, e-mail e telefone, junta repetições da mesma falha por minuto e registra um evento operacional; nada é gravado em banco. Não guarda IP, cookie, query nem o User-Agent inteiro. Responde 204 sempre, inclusive para relato inválido.

- **URL:** `https://staging.rota-nacional.ia.br/api/erro-cliente`
- **Auth:** `none` — Público.

**Corpo** (`application/json`)

- `code` (string, obrigatório) — Código da falha, `UI-` + letras/dígitos (`UI-JS-001` erro global, `UI-PROMESSA-001`, `UI-RECURSO-001`, `UI-CSP-001`, `UI-APP-001` relato do app).
- `phase` (string, obrigatório) — Fase em que quebrou, minúsculas: `global`, `promessa`, `script`, `carregar_lista`…
- `path` (string) — Caminho da página aberta, sem query; número, hash e token no caminho são guardados como `:id`.
- `message` (string) — Mensagem do erro, até 2000 caracteres.
- `stack` (string) — Stack trace, até 12000 caracteres.
- `source` (string) — Script de origem; só o caminho é guardado.
- `line` (int) — Linha no script de origem.
- `column` (int) — Coluna no script de origem.
- `visivel` (bool) — Se a aba estava visível quando quebrou.
- `build` (string) — Build da página que relatou (a `<meta name="build">`), até 64 letras, dígitos, `.`, `_` ou `-`; é ele que data a falha.

**Exemplo de corpo**

```json
{
  "code": "UI-APP-001",
  "phase": "carregar_lista",
  "path": "/",
  "message": "lista 500"
}
```

**Resposta `200`**

204 sem corpo, sempre — relato inválido, repetido ou acima do teto também recebe 204.

**Exemplo**

```sh
curl -s -XPOST https://staging.rota-nacional.ia.br/api/erro-cliente -H 'content-type: application/json' -d '{"code":"UI-APP-001","phase":"carregar_lista","path":"/","message":"lista 500"}'
```

### `POST /api/pagamento/aberto`

A interface relata que exibiu uma cobrança. Agentes não devem chamar.

Relato sem corpo, da mesma origem, enviado automaticamente quando uma cobrança fica visível. Não inicia pagamento, não concede acesso e não recebe identidade ou credencial. Não grava banco por relato. Conta eventos, não pessoas únicas. O painel privado do operador separa pedidos de pagamento da API e aberturas da interface por dia UTC; os dois números podem se sobrepor.

- **URL:** `https://staging.rota-nacional.ia.br/api/pagamento/aberto`
- **Auth:** `none` — Público.

**Headers**

- `Origin` (string, obrigatório) — A origem da página, idêntica à desta rota.
- `Sec-Fetch-Site` (string, obrigatório) — `same-origin`, definido pelo navegador.
- `X-MM-Payment-View` (string, obrigatório) — `1`, definido pelo componente comum.

**Resposta `202`**

202 sem corpo se aceito; 204 se ignorado. Sempre no-store.

### `POST /api/funil`

A interface relata os passos da visita (funil de conversão). Agentes não devem chamar.

Lote da mesma origem, enviado pela própria página: páginas vistas, engajamento, oferta à vista, clique em comprar, janela de pagamento, pagamento enviado ou aceito. Guarda o id aleatório do navegador, o caminho sem query, o host de quem mandou a pessoa e as utm; nunca IP, e-mail ou conta. Não grava banco: uma linha por lote no diário do dia, com teto. Robô declarado e smoke ficam de fora.

- **URL:** `https://staging.rota-nacional.ia.br/api/funil`
- **Auth:** `none` — Público.

**Headers**

- `Origin` (string) — A origem da página, idêntica à desta rota.
- `Content-Type` (string, obrigatório) — `application/json` ou `text/plain`.

**Corpo** (`application/json`)

- `v` (number, obrigatório) — Versão do lote: `1`.
- `vid` (string, obrigatório) — Id aleatório deste navegador (UUID v4).
- `sid` (string, obrigatório) — Id da sessão (30 min sem atividade encerram).
- `sn` (number, obrigatório) — Número da sessão deste navegador.
- `pv` (string, obrigatório) — Id da página vista.
- `e` (object[], obrigatório) — Até 40 eventos `{ t, n, p? }` do vocabulário do funil.

**Resposta `202`**

202 sem corpo se guardado; 204 se ignorado. Sempre no-store.

**Exemplo**

```sh
curl -s -XPOST https://staging.rota-nacional.ia.br/api/funil -H 'content-type: text/plain' -H 'x-mm-smoke: 1' -d '{"v":1,"vid":"0f8b9c1e-2a3b-4c5d-8e6f-7a8b9c0d1e2f","sid":"s1abcdefgh","sn":1,"pv":"p1abcdefgh","e":[{"t":0,"n":"pagina"}]}'
```

### `GET /api/funil/arquivos`

Operador: os dias do diário do funil guardados neste app, com o tamanho de cada um.

- **URL:** `https://staging.rota-nacional.ia.br/api/funil/arquivos`
- **Auth:** `none` — Público.

**Headers**

- `Authorization` (string, obrigatório) — `Bearer <METRICS_TOKEN>`.

**Resposta `200`**

- `v` (number) — Versão do lote guardado.
- `produto` (string) — O produto.
- `teto` (object) — `bytesDia` e `dias` guardados.
- `dias` (object[]) — `{ dia, bytes }`, do mais velho ao de hoje.

**Erros**

- `401` — Unauthorized
- `503` — Not configured

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/funil/arquivos -H "Authorization: Bearer $METRICS_TOKEN"
```

### `GET /api/funil/arquivo`

Operador: um pedaço de um dia do diário do funil, em NDJSON, a partir de um byte.

Até 4 MiB por resposta, cortados na última linha inteira. `X-MM-Funil-Proximo` diz de onde pedir o resto; `X-MM-Funil-Tamanho`, o tamanho do dia agora.

- **URL:** `https://staging.rota-nacional.ia.br/api/funil/arquivo`
- **Auth:** `none` — Público.

**Query**

- `dia` (string, obrigatório) — O dia, `AAAA-MM-DD` (UTC).
- `desde` (number) — O byte de onde ler; `0` no começo.

**Headers**

- `Authorization` (string, obrigatório) — `Bearer <METRICS_TOKEN>`.

**Resposta `200`**

Linhas JSON, uma por lote guardado.

**Erros**

- `400` — Invalid parameters
- `401` — Unauthorized
- `503` — Not configured

**Exemplo**

```sh
curl -s "https://staging.rota-nacional.ia.br/api/funil/arquivo?dia=2026-09-27&desde=0" -H "Authorization: Bearer $METRICS_TOKEN"
```

### `GET /api/metrics`

Métricas dos últimos 7 dias para o painel do operador; com o token, inclui o financeiro.

Sem credencial devolve o uso: os pedidos da API por dia (`usage.requests`) e o total de projetos (`accounts.tenants`). Com `METRICS_TOKEN` em Bearer acrescenta o financeiro do razão da casa.

- **URL:** `https://staging.rota-nacional.ia.br/api/metrics`
- **Auth:** `none` — Público.

**Headers**

- `Authorization` (string) — `Bearer <METRICS_TOKEN>` para incluir o financeiro; token errado é 401.

**Resposta `200`**

- `app` (string) — O nome do produto.
- `today` (string) — O dia de hoje em UTC (AAAA-MM-DD).
- `days` (object[]) — Os 7 dias, com as visitas de cada um.
- `usage` (object) — `requests`: os pedidos de hoje (`today`) e de cada dia (`days`).
- `accounts` (object) — `tenants`: os projetos com conta no RN.

**Erros**

- `401` — Token de operador errado.
- `503` — App sem METRICS_TOKEN configurado.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/metrics
```

### `POST /api/public/analytics`

A medida de visita das páginas, sem terceiros: a `page_view` conta como a visita da casa; o resto é aceito sem registro.

- **URL:** `https://staging.rota-nacional.ia.br/api/public/analytics`
- **Auth:** `none` — Público.

**Corpo** (`application/json`)

- `event_type` (string, obrigatório) — `page_view` conta a visita.
- `path` (string) — A página visitada.

**Resposta `200`**

Sem estrutura declarada.

**Exemplo**

```sh
curl -s -XPOST https://staging.rota-nacional.ia.br/api/public/analytics -H 'content-type: application/json' -d '{"event_type":"page_view","path":"/pt/"}'
```

## Números públicos

### `GET /api/vitrine`

Os números públicos do produto: tráfego, agentes, uso e confiabilidade, sem dinheiro.

Projeção publicada de hora em hora pelo coletor da casa, arredondada a dois dígitos significativos; `null` é medição ausente, nunca zero. Cache de 15 minutos com ETag (`If-None-Match` → 304). Não há como enviar números por esta rota: a publicação é do coletor, com token próprio.

- **URL:** `https://staging.rota-nacional.ia.br/api/vitrine`
- **Auth:** `none` — Público.

**Resposta `200`**

- `v` (int) — Versão do contrato (1).
- `produto` (string) — Id do produto.
- `publicado` (bool) — `false` antes da primeira publicação do coletor; aí só estas cinco chaves vêm.
- `atualizado_em` (string, pode ser null) — Quando o coletor publicou (ISO 8601).
- `stale` (bool) — `true` quando a projeção tem mais de 26 h.
- `nome` (string, opcional) — Nome do produto.
- `desde` (string, opcional, pode ser null) — Dia a partir do qual a série vale.
- `fuso` (string, opcional) — Fuso dos dias (`UTC`).
- `hoje` (object, opcional) — O dia de hoje: páginas por classe (pessoa, IA, bot), chamadas de API por classe, leituras das superfícies de máquina e uso do produto.
- `dias` (object[], opcional) — Até 31 dias, o mais antigo primeiro: `dia`, `paginas`, `api`, `api_ia`, `maquina`, `visitantes`, `uso`.
- `janelas` (object, opcional) — Somas de 7 e 30 dias (`d7`, `d30`).
- `visitantes` (object, opcional) — Visitantes únicos na borda em 7 dias.
- `pessoas` (object, opcional, pode ser null) — GA4 quando há: usuários, sessões, países, aparelhos e quem chegou de IA.
- `agentes` (object, opcional) — Os agentes de IA e os bots que mais leem, 7 dias.
- `superficies` (object, opcional) — Leituras de OKF, llms, well-known, OpenAPI e MCP em 7 dias.
- `mcp` (object, opcional) — Chamadas MCP em 7 dias.
- `uso` (object, opcional) — Uso real do produto por recurso: rótulo, hoje, 7 e 30 dias.
- `contas` (object, opcional, pode ser null) — Usuários e convidados.
- `confiabilidade` (object, opcional) — Percentual de pedidos sem 5xx em 7 dias e o build no ar.
- `catalogo` (object, opcional, pode ser null) — Tamanho do acervo, quando o produto tem um.
- `apoio` (object, opcional) — Impressões e cliques por patrocinador, quando houver.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/vitrine
```

### `GET /api/vitrine/operador`

O documento completo do produto no painel do operador — só com o token do operador.

- **URL:** `https://staging.rota-nacional.ia.br/api/vitrine/operador`
- **Auth:** `none` — Público.

**Headers**

- `Authorization` (string, obrigatório) — `Bearer <METRICS_TOKEN>` — a classe operador.

**Resposta `200`**

- `produto` (string) — Id do produto.
- `atualizado_em` (string, pode ser null) — Quando o coletor publicou.
- `operador` (object, pode ser null) — O documento completo do coletor, com o que a projeção pública não carrega.

**Erros**

- `401` — Sem token, token errado ou token de outra classe.
- `503` — Worker sem `METRICS_TOKEN` ou sem o control plane.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/vitrine/operador -H "Authorization: Bearer $METRICS_TOKEN"
```

### `GET /api/vitrine/painel`

O painel da casa inteira, na forma que o gm lê — só com o token do operador.

- **URL:** `https://staging.rota-nacional.ia.br/api/vitrine/painel`
- **Auth:** `none` — Público.

**Headers**

- `Authorization` (string, obrigatório) — `Bearer <METRICS_TOKEN>` — a classe operador.

**Resposta `200`**

- `apps` (object[]) — Um documento do operador por produto, em ordem de id.
- `updated` (string, opcional) — Quando o coletor fechou a rodada.
- `totals` (object, opcional) — Os totais da casa.

**Erros**

- `401` — Sem token, token errado ou token de outra classe.
- `503` — Worker sem `METRICS_TOKEN` ou sem o control plane.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/vitrine/painel -H "Authorization: Bearer $METRICS_TOKEN"
```

### `GET /api/vitrine/cursores`

O cursor de erro resolvido por produto (`borda`, `cli`) — só com o token do operador.

- **URL:** `https://staging.rota-nacional.ia.br/api/vitrine/cursores`
- **Auth:** `none` — Público.

**Headers**

- `Authorization` (string, obrigatório) — `Bearer <METRICS_TOKEN>` — a classe operador.

**Resposta `200`**

JSON: `{ [produto]: { borda?: ISO, cli?: ISO } }`; vazio é `{}`.

**Erros**

- `401` — Sem token, token errado ou token de outra classe.
- `503` — Worker sem `METRICS_TOKEN` ou sem o control plane.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/vitrine/cursores -H "Authorization: Bearer $METRICS_TOKEN"
```

## Contato

### `POST /api/contact`

Fale com quem faz o produto — de graça, para pessoa e agente.

Uma rota para dúvida e para proposta de patrocínio, parceria ou anúncio (`tipo`, com os espaços de `GET /api/partners`). Sem captcha, sem conta, sem pagamento. Uma mensagem a cada 10 segundos por rede: a que chega antes espera a vez e sai — sem erro. A mensagem chega à equipe por e-mail, com o `email` como endereço de resposta.

- **URL:** `https://staging.rota-nacional.ia.br/api/contact`
- **Auth:** `none` — Público.

**Corpo** (`application/json`)

- `name` (string, obrigatório) — Como chamar quem escreve (alias `nome`).
- `email` (string, obrigatório) — Para onde responder.
- `message` (string, obrigatório) — O que você quer dizer (alias `mensagem`).
- `tipo` (string) — Proposta: `patrocinio`, `parceria` ou `anuncio`. Liga os campos abaixo.
- `empresa` (string) — Quem propõe, quando é empresa.
- `site` (string) — Site de quem propõe.
- `orcamento` (string) — `ate_100`, `100_500`, `500_2000`, `2000_mais` ou `a_combinar`.
- `espaco` (string[]) — Ids de placement de `GET /api/partners`, até 6.
- `duracao` (string) — Dias de exposição: `30`, `90` ou `365`.
- `pagamento` (string) — `usdc`, `deposito` ou `a_combinar`.

**Exemplo de corpo**

```json
{
  "name": "Agente",
  "email": "agent@example.com",
  "message": "olá, sou um agente"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true` quando a mensagem foi aceita.

**Erros**

- `400` — Validação: o `code` diz o campo.
- `503` — O contato não está configurado neste servidor.

**Exemplo**

```sh
curl -s -XPOST https://staging.rota-nacional.ia.br/api/contact -H 'content-type: application/json' -d '{"name":"Agente","email":"agent@example.com","message":"olá, sou um agente"}'
```

### `POST /api/public/contact`

O formulário de contato do site: a mensagem chega à equipe pelo contato da casa.

- **URL:** `https://staging.rota-nacional.ia.br/api/public/contact`
- **Auth:** `none` — Público.

**Corpo** (`application/json`)

- `name` (string, obrigatório) — Como chamar quem escreve.
- `email` (string, obrigatório) — Para onde responder.
- `message` (string, obrigatório) — O que você quer dizer: o piloto, a dúvida ou a proposta.
- `organization` (string) — A organização de quem escreve.
- `role_title` (string) — O cargo de quem escreve, para a equipe saber com quem fala.
- `phone` (string) — Um telefone, se preferir.
- `intent` (string) — O objetivo: `piloto`, `contratacao`, `duvida` ou `parceria`.
- `source_path` (string) — A página de onde a mensagem saiu.

**Resposta `200`**

- `ok` (bool) — `true` quando a mensagem foi aceita.

**Erros**

- `400` — Validação: nome, e-mail ou mensagem.
- `503` — O contato não está configurado neste servidor.

**Exemplo**

```sh
curl -s -XPOST https://staging.rota-nacional.ia.br/api/public/contact -H 'content-type: application/json' -d '{"name":"Ana","email":"ana@example.com","message":"Quero um piloto."}'
```

## Parceria

### `GET /api/partners`

Parceria, patrocínio e anúncio: os espaços do produto com preço sugerido, os números públicos ao lado e como propor.

Informação sob consulta, sem ativação: espaços do catálogo da casa com preço em USD por 30 dias (90 e 365 dias com desconto), patrocinadores em vigor, recorte de `/api/vitrine`, carteira da casa (USDC na Base) e o caminho de contato — depósito, PIX ou fatura são combinados na resposta. Cache de 1 hora.

- **URL:** `https://staging.rota-nacional.ia.br/api/partners`
- **Auth:** `none` — Público.

**Resposta `200`**

- `status` (string) — `sob_consulta`: informação e proposta, sem ativação nem cobrança.
- `produto` (string) — Nome do produto.
- `idioma` (string) — Idioma dos textos (o do produto).
- `titulo` (string) — Título da oferta.
- `descricao` (string) — Uma frase sobre a oferta.
- `publico` (string) — Quem usa o produto — o público que o patrocinador alcança.
- `modalidades` (object[]) — `{ id, nome }`: patrocinio, parceria, anuncio.
- `placements` (object[]) — Os espaços do produto: `id`, `nome`, `onde`, `formato`, `exclusivo`, `medicao`, `price_usd_30d` (sugestão; `null` é sob consulta), `exposure[{ dias, price_usd }]` para 30, 90 e 365 dias, `disponivel`.
- `house_bundle` (object) — O pacote da casa: rodapé e menção para agentes nos dez produtos, com desconto.
- `parcerias` (string[]) — Ideias de parceria que o produto aceita discutir.
- `current_sponsors` (object[]) — Patrocinadores em vigor: `id`, `nome`, `url`, `frase`, `espacos`, `ate`.
- `stats` (object) — Recorte dos números públicos (`hoje`, `janelas`, `agentes`, `confiabilidade`) e o `link` para `/api/vitrine`; `publicado: false` antes da primeira publicação.
- `payment` (object) — Como pagar: `rede`, `chain_id`, `ativo`, `pay_to`, `eip681` (a carteira da casa, quando declarada), `alternativas` e a `nota` — depósito, PIX ou fatura pela resposta.
- `contact` (object) — `email`, `form_url`, `api_url` (`POST /api/contact`, livre: uma mensagem a cada 10 s por rede), `campos` (os obrigatórios), `campos_proposta` (os opcionais da proposta, com os valores aceitos de cada um), `message_template`, `instructions`.
- `politica` (object) — Rótulo do espaço, setores recusados, pagamento adiantado, prazos.
- `_links` (object) — `self`, `stats`, `page` (`null` até a página existir), `contact`, `casa` (o mesmo caminho nos dez produtos).

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/partners
```

## Crédito

### `POST /api/credito`

Recarrega crédito pré-pago: paga uma vez com x402 e recebe o token que desconta em qualquer API da casa.

- **URL:** `https://staging.rota-nacional.ia.br/api/credito`
- **Auth:** `none` — Público.

**Query**

- `usd` (int, obrigatório) — Pacote: 1, 5, 10 ou 25 dólares.

**Resposta `200`**

- `token` (string) — Token portador do saldo (`cred_…`). Mostrado UMA vez — não há como recuperá-lo.
- `saldo_usd` (string) — Saldo creditado.
- `guarde` (string) — Aviso de que o token é o portador do crédito.
- `usar` (string) — Como apresentar o token nas rotas pagas.
- `saldo_em` (string) — Onde consultar saldo e extrato.

**Erros**

- `400` — Pacote fora da lista (1, 5, 10 ou 25).
- `402` — Sem pagamento — o corpo traz `accepts[]` do x402.

**Exemplo**

```sh
curl -s -XPOST 'https://staging.rota-nacional.ia.br/api/credito?usd=10'
```

### `GET /api/credito`

Saldo e extrato do crédito — as últimas movimentações, sem devolver o token.

- **URL:** `https://staging.rota-nacional.ia.br/api/credito`
- **Auth:** `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou header `X-Credito`). Não é conta: é portador de saldo.

**Resposta `200`**

- `saldo_micros` (int) — Saldo em micro-dólares (1e-6 USD).
- `saldo_usd` (string) — Saldo formatado.
- `criado_em` (string) — Quando o crédito foi aberto.
- `movimentos` (object[]) — Entradas e saídas recentes, com produto e recurso.

**Erros**

- `401` — Sem token ou token desconhecido.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/credito -H 'Authorization: Bearer cred_…'
```

### `GET /api/credito/pix`

Crédito por Pix: a chave, o câmbio fixo, os pacotes em reais e o que o comprovante aceita.

- **URL:** `https://staging.rota-nacional.ia.br/api/credito/pix`
- **Auth:** `none` — Público.

**Resposta `200`**

- `chave` (string) — A chave Pix que recebe o pagamento.
- `brl_por_usd` (number) — Câmbio fixo usado nos pacotes.
- `pacotes` (object[]) — Os pacotes (1, 5, 10 ou 25 dólares), cada um com `brl_centavos` e `copia_e_cola` (o Pix copia e cola do valor, o mesmo texto do QR: o app do banco já vem com o valor).
- `comprovante` (object) — Tipos aceitos (foto ou PDF) e o tamanho máximo, em bytes.
- `liberacao` (string) — `manual`: o dono confere o Pix e libera.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/credito/pix
```

### `POST /api/credito/pix`

Pede crédito pago por Pix: multipart com `usd`, `comprovante` (foto ou PDF até 2 MB) e `email`; o resto é opcional.

O código de crédito sai na resposta e passa a valer quando o dono confere o Pix e libera (manual, em geral no mesmo dia). O `email` é obrigatório: é por ele que o dono fala com a pessoa. Opcionais: `nome`, `pagina` (a página de onde pediu, até 2.000 caracteres) e o que a pessoa comprava quando recebeu o 402 — `recurso` (até 2.000), `descricao` (até 300) e `preco_usd` (decimal, ex. `0.50`); e `navegador_id` (UUID que liga os pedidos do mesmo navegador). Tudo o que chega fica registrado no pedido — o comprovante inclusive —, com a conta logada (conferida pelo cookie da sessão), a rede e o navegador de quem pediu.

- **URL:** `https://staging.rota-nacional.ia.br/api/credito/pix`
- **Auth:** `none` — Público.

**Resposta `200`**

- `id` (string) — Id do pedido, para acompanhar.
- `estado` (string) — `pendente` até a decisão.
- `credito` (string) — O token `cred_…`, mostrado UMA vez; vale depois da liberação.
- `estado_em` (string) — Onde acompanhar o pedido.

**Erros**

- `400` — Pacote fora da lista (1, 5, 10 ou 25), sem comprovante ou sem e-mail válido.
- `413` — Comprovante acima de 2 MB.
- `415` — Comprovante que não é foto (JPEG, PNG, WebP) nem PDF.
- `429` — A rede já mandou os pedidos do dia.
- `502` — O e-mail ao dono não saiu: o pedido fica registrado como `falhou`; mande de novo.
- `503` — Fila de conferência cheia, ou Pix indisponível neste app.

**Exemplo**

```sh
curl -s -XPOST https://staging.rota-nacional.ia.br/api/credito/pix -F usd=5 -F email=voce@empresa.com.br -F comprovante=@pix.pdf
```

### `GET /api/credito/pix/:id`

Estado de um pedido de crédito por Pix: `pendente`, `liberado`, `recusado` ou `falhou`.

- **URL:** `https://staging.rota-nacional.ia.br/api/credito/pix/:id`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

- `id` (string, obrigatório) — Id do pedido (32 hex). Ex.: `0123456789abcdef0123456789abcdef`.

**Resposta `200`**

- `estado` (string) — `pendente`, `liberado`, `recusado` ou `falhou` (o e-mail ao dono não saiu; mande de novo).
- `usd` (int) — O pacote pedido.
- `decidido_em` (string) — Quando o dono decidiu, ou `null`.

**Erros**

- `404` — Pedido desconhecido.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/credito/pix/0123456789abcdef0123456789abcdef
```

### `GET /api/credito/asaas`

Pix automático: se está disponível neste app, os pacotes em reais e o saldo que o produto vende.

- **URL:** `https://staging.rota-nacional.ia.br/api/credito/asaas`
- **Auth:** `none` — Público.

**Resposta `200`**

- `disponivel` (boolean) — `false` quando o app não tem o Asaas configurado (use o Pix com comprovante). → ver `boolean` em **Estruturas**.
- `pacotes` (object[]) — Os pacotes de crédito (1, 5, 10 ou 25 dólares), com `brl_centavos`.
- `saldo` (object) — Quando o produto vende saldo em reais: a faixa e se a conta logada pode comprar.
- `precisa_documento` (boolean) — Se o CPF ou CNPJ de quem paga ainda é pedido. → ver `boolean` em **Estruturas**.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/credito/asaas
```

### `POST /api/credito/asaas`

Gera um Pix dinâmico: JSON com `oferta` (`pacote` com `usd`, ou `saldo` com `centavos`) e o pagador.

O pagamento libera sozinho o que se comprou: o pacote vira o token `cred_…` que já vem na resposta; o saldo cai na organização da conta logada. Na primeira compra vão `documento` (CPF ou CNPJ, que segue para o gateway e não fica guardado aqui) e `nome`; `email`, `pagina` e `navegador_id` são opcionais e ficam registrados.

- **URL:** `https://staging.rota-nacional.ia.br/api/credito/asaas`
- **Auth:** `none` — Público.

**Resposta `200`**

- `id` (string) — Id da cobrança, para acompanhar.
- `credito` (string) — No pacote: o token `cred_…`, mostrado UMA vez; vale quando o Pix cair.
- `pix` (object) — `copia_e_cola`, `imagem` (QR em PNG, data URI) e `expira_em`.
- `estado_em` (string) — Onde acompanhar o pagamento.

**Erros**

- `400` — Pacote fora da lista (1, 5, 10 ou 25), valor fora da faixa, ou CPF/CNPJ, nome ou e-mail inválido.
- `429` — A rede já gerou as cobranças do dia.
- `502` — O gateway não gerou o Pix; tente de novo.
- `503` — Pix automático indisponível neste app, ou cobranças demais esperando pagamento.

**Exemplo**

```sh
curl -s -XPOST https://staging.rota-nacional.ia.br/api/credito/asaas -H 'content-type: application/json' -d '{"oferta":"pacote","usd":5,"documento":"000.000.000-00","nome":"Ana"}'
```

### `GET /api/credito/asaas/:id`

Estado de uma cobrança Pix automática: `pendente`, `pago`, `vencido`, `estornado` ou `falhou`.

- **URL:** `https://staging.rota-nacional.ia.br/api/credito/asaas/:id`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

- `id` (string, obrigatório) — Id da cobrança (32 hex). Ex.: `0123456789abcdef0123456789abcdef`.

**Resposta `200`**

- `estado` (string) — `pago` libera o token do pacote ou o saldo; o Pix pago depois do vencimento vale.
- `pago_em` (string) — Quando o pagamento foi confirmado, ou `null`.

**Erros**

- `404` — Cobrança desconhecida.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/credito/asaas/0123456789abcdef0123456789abcdef
```

## Modelos

### `GET /v1/models`

O catálogo curado de modelos `rota/*`, com janela de contexto e para que cada um serve.

- **URL:** `https://staging.rota-nacional.ia.br/v1/models`
- **Auth:** `none` — Público.

**Resposta `200`**

- `object` (string) — `list`.
- `data` (object[]) — Os modelos: `id`, `display_name`, `context_window`, `description`.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/models
```

### `POST /v1/chat/completions`

Chat compatível com a OpenAI, com `stream: true` em SSE. Os dados pessoais são tratados antes do modelo.

O corpo é o da OpenAI (`model`, `messages`, `max_tokens`, `temperature`, `tools`…). Antes de qualquer envio, a barreira troca CPF, CNPJ, e-mail, telefone e nomes por marcadores (`placeholder`), os remove (`redact`) ou recusa o pedido (`block`), conforme a política da organização. `rota/auto` escolhe o modelo pelo conteúdo. Imagem e documento no corpo são recusados com erro claro: use `/v1/privacy/extract` antes.

- **URL:** `https://staging.rota-nacional.ia.br/v1/chat/completions`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Corpo** (`application/json`)

- `model` (string) — Um id do catálogo (`rota/*`, em `GET /v1/models`); `rota/auto` escolhe pelo conteúdo.
- `messages` (object[]) — A conversa: `role` (`system`, `user`, `assistant` ou `tool`) e `content` de cada mensagem; o conteúdo passa pela barreira.
- `max_tokens` (number) — O teto de tokens da resposta; conta na cota e no débito do crédito.
- `stream` (bool) — `true` devolve a resposta em SSE, pedaço a pedaço, sem esperar o fim.

**Exemplo de corpo**

```json
{
  "model": "rota/rapido",
  "messages": [
    {
      "role": "user",
      "content": "Olá"
    }
  ],
  "max_tokens": 64
}
```

**Resposta `200`**

- `choices` (object[]) — As respostas, no formato da OpenAI.
- `usage` (object) — `prompt_tokens`, `completion_tokens`, `total_tokens`.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado ou origem de rede fora da política da organização.
- `422` — A política de privacidade `block` recusou o envio: havia dados pessoais.
- `429` — Limite por minuto ou cota do mês.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/chat/completions -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"model":"rota/rapido","messages":[{"role":"user","content":"Olá"}],"max_tokens":64}'
```

### `POST /v1/messages`

A API Messages da Anthropic (Claude Code e compatíveis), pela mesma barreira de privacidade, cota e auditoria.

O corpo é o da Anthropic (`model`, `max_tokens`, `messages`, `system`, `tools`, `stream`). A resposta e o fluxo saem no formato da Anthropic. No Claude Code: `ANTHROPIC_BASE_URL=$ORIGIN` e a chave em `ANTHROPIC_AUTH_TOKEN`.

- **URL:** `https://staging.rota-nacional.ia.br/v1/messages`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Corpo** (`application/json`)

- `model` (string) — Um id do catálogo (`rota/*`, em `GET /v1/models`); `rota/auto` escolhe pelo conteúdo.
- `max_tokens` (number) — O teto de tokens da resposta; conta na cota e no débito do crédito.
- `messages` (object[]) — A conversa: `role` (`system`, `user`, `assistant` ou `tool`) e `content` de cada mensagem; o conteúdo passa pela barreira.
- `stream` (bool) — `true` devolve a resposta em SSE, pedaço a pedaço, sem esperar o fim.

**Exemplo de corpo**

```json
{
  "model": "rota/rapido",
  "max_tokens": 64,
  "messages": [
    {
      "role": "user",
      "content": "Olá"
    }
  ]
}
```

**Resposta `200`**

- `content` (object[]) — Blocos `text` e `tool_use`.
- `stop_reason` (string) — `end_turn`, `max_tokens` ou `tool_use`.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado ou origem de rede fora da política da organização.
- `422` — A política de privacidade `block` recusou o envio: havia dados pessoais.
- `429` — Limite por minuto ou cota do mês.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/messages -H "Authorization: Bearer $ROTA_API_KEY" -H 'anthropic-version: 2023-06-01' -H 'content-type: application/json' -d '{"model":"rota/rapido","max_tokens":64,"messages":[{"role":"user","content":"Olá"}]}'
```

## Privacidade

### `POST /v1/privacy/clean`

Limpa dados pessoais de um texto, JSON ou lista, sem modelo nenhum: marcadores, remoção ou bloqueio.

Mande `text`, `input` ou `items`; `policy` só endurece a da organização. A resposta traz o texto limpo e as categorias encontradas, nunca os valores.

- **URL:** `https://staging.rota-nacional.ia.br/v1/privacy/clean`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Corpo** (`application/json`)

- `text` (string) — O texto a limpar (ou `input`, um JSON, ou `items`, uma lista curta).
- `policy` (string) — `placeholder`, `redact` ou `block`; só endurece a política da organização.

**Exemplo de corpo**

```json
{
  "text": "Contato: teste@example.com"
}
```

**Resposta `200`**

- `clean_text` (string) — O texto com os marcadores (`[CPF_1]`, `[EMAIL_1]`…).
- `findings` (object[]) — Categoria, contagem e ação.
- `audit_id` (string) — O registro cifrado da chamada.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado ou origem de rede fora da política da organização.
- `422` — A política de privacidade `block` recusou o envio: havia dados pessoais.
- `429` — Limite por minuto ou cota do mês.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/privacy/clean -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"text":"Contato: teste@example.com"}'
```

### `POST /v1/privacy/jobs`

A mesma limpeza como job consultável depois (`GET /v1/privacy/jobs/:id`), para lotes.

- **URL:** `https://staging.rota-nacional.ia.br/v1/privacy/jobs`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Corpo** (`application/json`)

- `items` (string[]) — Os textos do lote, cada um limpo à parte; a resposta traz só categorias e contagens.

**Exemplo de corpo**

```json
{
  "items": [
    "Ana, CPF 529.982.247-25"
  ]
}
```

**Resposta `202`**

- `id` (string) — O id do job.
- `status` (string) — `completed` ou `blocked`.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado ou origem de rede fora da política da organização.
- `422` — A política de privacidade `block` recusou o envio: havia dados pessoais.
- `429` — Limite por minuto ou cota do mês.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/privacy/jobs -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"items":["Ana, CPF 529.982.247-25"]}'
```

### `GET /v1/privacy/jobs/:id`

O resultado de um job de limpeza: categorias, contagens e o registro de auditoria, sem o conteúdo.

- **URL:** `https://staging.rota-nacional.ia.br/v1/privacy/jobs/:id`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Parâmetros de caminho**

- `id` (string, obrigatório) — O id do job (`privjob_…`). Ex.: `privjob_0123456789abcdef`.

**Resposta `200`**

- `status` (string) — `completed` ou `failed`.
- `privacy` (object) — Categorias, contagens e total.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `404` — Job desconhecido para esta organização.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/privacy/jobs/privjob_0123456789abcdef -H "Authorization: Bearer $ROTA_API_KEY"
```

### `POST /v1/privacy/extract`

Extrai o texto de um PDF (ou de uma imagem, por OCR em beta) e o devolve já limpo pela barreira.

Multipart com `file` (até 25 MB). O arquivo não fica guardado; PDF escaneado ou imagem ilegível recebem 422 claro.

- **URL:** `https://staging.rota-nacional.ia.br/v1/privacy/extract`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Resposta `200`**

- `text` (string) — O texto limpo.
- `findings` (object[]) — Categoria, contagem e ação.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado ou origem de rede fora da política da organização.
- `413` — Documento acima de 25 MB.
- `422` — Sem texto extraível, ou bloqueado pela política.
- `429` — Limite por minuto ou cota do mês.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/privacy/extract -H "Authorization: Bearer $ROTA_API_KEY" -F file=@documento.pdf
```

### `POST /v1/audio/transcriptions`

Transcreve um áudio (compatível com a OpenAI) e devolve o texto já limpo pela barreira.

Multipart com `file` (até 25 MB), `language` e `response_format` (`json` ou `text`). O áudio não fica guardado.

- **URL:** `https://staging.rota-nacional.ia.br/v1/audio/transcriptions`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Resposta `200`**

- `text` (string) — A transcrição limpa.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado ou origem de rede fora da política da organização.
- `413` — Áudio acima de 25 MB.
- `422` — A política de privacidade `block` recusou o envio: havia dados pessoais.
- `429` — Limite por minuto ou cota do mês.
- `504` — Áudio longo demais para a transcrição síncrona.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/audio/transcriptions -H "Authorization: Bearer $ROTA_API_KEY" -F file=@reuniao.mp3
```

## Capacidades rn.*

### `GET /v1/capabilities`

As capacidades `rn.*` que os workers ligados anunciam agora.

- **URL:** `https://staging.rota-nacional.ia.br/v1/capabilities`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Resposta `200`**

- `capabilities` (string[]) — As capacidades disponíveis.
- `workers` (object[]) — Cada worker visto nos últimos 2 min.

**Erros**

- `401` — Chave de API ausente ou inválida.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/capabilities -H "Authorization: Bearer $ROTA_API_KEY"
```

### `POST /v1/embeddings`

Vetores de textos para busca por significado (espera até 2 min; senão, 202 com o job).

Prévia (`rn.*`): o contrato pode mudar e depende de worker ligado (veja `GET /v1/capabilities`).

- **URL:** `https://staging.rota-nacional.ia.br/v1/embeddings`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Corpo** (`application/json`)

- `input` (string[]) — O texto, ou a lista de textos, a vetorizar; passa pela barreira antes do worker.

**Resposta `200`**

- `id` (string) — O id do job (`rnj_…`).
- `status` (string) — `queued`, `leased`, `completed`, `failed` ou `cancelled`.
- `status_url` (string) — Onde acompanhar.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/embeddings -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"input":["política de privacidade"]}'
```

### `POST /v1/audio/speech`

Voz a partir de um texto (espera até 5 min; senão, 202 com o job).

Prévia (`rn.*`): o contrato pode mudar e depende de worker ligado (veja `GET /v1/capabilities`).

- **URL:** `https://staging.rota-nacional.ia.br/v1/audio/speech`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Corpo** (`application/json`)

- `text` (string) — O texto a falar; obrigatório, e passa pela barreira antes do worker.

**Resposta `200`**

- `id` (string) — O id do job (`rnj_…`).
- `status` (string) — `queued`, `leased`, `completed`, `failed` ou `cancelled`.
- `status_url` (string) — Onde acompanhar.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/audio/speech -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"text":"Bem-vindo à Rota Nacional."}'
```

### `POST /v1/audio/music`

Música a partir de uma descrição (60, 120 ou 180 s).

Prévia (`rn.*`): o contrato pode mudar e depende de worker ligado (veja `GET /v1/capabilities`).

- **URL:** `https://staging.rota-nacional.ia.br/v1/audio/music`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Corpo** (`application/json`)

- `style` (string) — A descrição do estilo da música (instrumentos, clima, andamento).
- `seconds` (number) — A duração: 60, 120 ou 180 segundos (padrão 60).

**Resposta `202`**

- `id` (string) — O id do job (`rnj_…`).
- `status` (string) — `queued`, `leased`, `completed`, `failed` ou `cancelled`.
- `status_url` (string) — Onde acompanhar.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/audio/music -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"style":"Instrumental ambiente","seconds":60}'
```

### `POST /v1/audio/compositions`

Composição de voz e fundo com ganhos e rampas.

Prévia (`rn.*`): o contrato pode mudar e depende de worker ligado (veja `GET /v1/capabilities`).

- **URL:** `https://staging.rota-nacional.ia.br/v1/audio/compositions`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Resposta `202`**

- `id` (string) — O id do job (`rnj_…`).
- `status` (string) — `queued`, `leased`, `completed`, `failed` ou `cancelled`.
- `status_url` (string) — Onde acompanhar.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/audio/compositions -H "Authorization: Bearer $ROTA_API_KEY" -F voice=@voz.mp3 -F background=@fundo.mp3
```

### `POST /v1/images/generations`

Imagem a partir de uma descrição.

Prévia (`rn.*`): o contrato pode mudar e depende de worker ligado (veja `GET /v1/capabilities`).

- **URL:** `https://staging.rota-nacional.ia.br/v1/images/generations`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Corpo** (`application/json`)

- `prompt` (string) — A descrição da imagem; obrigatória, e passa pela barreira antes do worker.

**Resposta `202`**

- `id` (string) — O id do job (`rnj_…`).
- `status` (string) — `queued`, `leased`, `completed`, `failed` ou `cancelled`.
- `status_url` (string) — Onde acompanhar.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/images/generations -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"prompt":"Uma cidade-jardim ao amanhecer"}'
```

### `POST /v1/images/edits`

Edição de uma imagem com uma instrução.

Prévia (`rn.*`): o contrato pode mudar e depende de worker ligado (veja `GET /v1/capabilities`).

- **URL:** `https://staging.rota-nacional.ia.br/v1/images/edits`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Resposta `202`**

- `id` (string) — O id do job (`rnj_…`).
- `status` (string) — `queued`, `leased`, `completed`, `failed` ou `cancelled`.
- `status_url` (string) — Onde acompanhar.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/images/edits -H "Authorization: Bearer $ROTA_API_KEY" -F image=@foto.png -F prompt='fundo neutro'
```

### `POST /v1/ocr`

Texto de uma imagem ou documento (espera até 3 min; senão, 202 com o job).

Prévia (`rn.*`): o contrato pode mudar e depende de worker ligado (veja `GET /v1/capabilities`).

- **URL:** `https://staging.rota-nacional.ia.br/v1/ocr`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Resposta `200`**

- `id` (string) — O id do job (`rnj_…`).
- `status` (string) — `queued`, `leased`, `completed`, `failed` ou `cancelled`.
- `status_url` (string) — Onde acompanhar.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/ocr -H "Authorization: Bearer $ROTA_API_KEY" -F file=@documento.pdf
```

### `POST /v1/documents/fidelity/jobs`

OCR documental fiel (páginas, imagens), como job.

Prévia (`rn.*`): o contrato pode mudar e depende de worker ligado (veja `GET /v1/capabilities`).

- **URL:** `https://staging.rota-nacional.ia.br/v1/documents/fidelity/jobs`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Resposta `202`**

- `id` (string) — O id do job (`rnj_…`).
- `status` (string) — `queued`, `leased`, `completed`, `failed` ou `cancelled`.
- `status_url` (string) — Onde acompanhar.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/documents/fidelity/jobs -H "Authorization: Bearer $ROTA_API_KEY" -F file=@documento.pdf
```

### `POST /v1/documents/review/jobs`

Revisão documental como job.

Prévia (`rn.*`): o contrato pode mudar e depende de worker ligado (veja `GET /v1/capabilities`).

- **URL:** `https://staging.rota-nacional.ia.br/v1/documents/review/jobs`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Corpo** (`application/json`)

- `document` (string) — O texto do documento; o resto do JSON (instruções, esquema do resultado) segue ao worker depois da barreira.

**Resposta `202`**

- `id` (string) — O id do job (`rnj_…`).
- `status` (string) — `queued`, `leased`, `completed`, `failed` ou `cancelled`.
- `status_url` (string) — Onde acompanhar.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/documents/review/jobs -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"document":"..."}'
```

### `GET /v1/jobs/:id`

O estado de um job `rn.*` da organização.

- **URL:** `https://staging.rota-nacional.ia.br/v1/jobs/:id`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Parâmetros de caminho**

- `id` (string, obrigatório) — O id do job. Ex.: `rnj_0123456789abcdef`.

**Resposta `200`**

- `status` (string) — O estado.
- `progress_pct` (number) — O progresso, quando o worker informa.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `404` — Job desconhecido para esta organização.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/jobs/rnj_0123456789abcdef -H "Authorization: Bearer $ROTA_API_KEY"
```

### `GET /v1/jobs/:id/result`

O resultado de um job concluído: o arquivo gerado, ou o JSON já limpo pela barreira.

- **URL:** `https://staging.rota-nacional.ia.br/v1/jobs/:id/result`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Parâmetros de caminho**

- `id` (string, obrigatório) — O id do job. Ex.: `rnj_0123456789abcdef`.

**Resposta `200`**

- `result` (object) — O resultado, quando é JSON.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `404` — Job desconhecido.
- `409` — Job ainda não concluído.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/v1/jobs/rnj_0123456789abcdef/result -H "Authorization: Bearer $ROTA_API_KEY"
```

### `DELETE /v1/jobs/:id`

Cancela um job que ainda está na fila.

- **URL:** `https://staging.rota-nacional.ia.br/v1/jobs/:id`
- **Auth:** `chave` — Chave de API da conta: `Authorization: Bearer mmk_…` ou `X-Api-Key: mmk_…`. Criada na página da conta (Chaves de API), vale só no produto em que nasceu e age como a conta (ou a organização dona dela). A chave criada na conta vale na API do Rota Nacional; as `sk-rota-…` de antes continuam valendo.

**Parâmetros de caminho**

- `id` (string, obrigatório) — O id do job. Ex.: `rnj_0123456789abcdef`.

**Resposta `200`**

- `status` (string) — `cancelled`.

**Erros**

- `401` — Chave de API ausente ou inválida.
- `404` — Job desconhecido.
- `409` — O job já saiu da fila.

**Exemplo**

```sh
curl -s -X DELETE https://staging.rota-nacional.ia.br/v1/jobs/rnj_0123456789abcdef -H "Authorization: Bearer $ROTA_API_KEY"
```

## Painel

### `GET /api/app/perfil`

Quem está no painel e a organização aberta: o acesso à API, o teste, os limites, a política e a origem.

- **URL:** `https://staging.rota-nacional.ia.br/api/app/perfil`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Headers**

- `X-Organization-Id` (string) — A organização em que o pedido age (sem ele, a conta pessoal); o vínculo e o papel são conferidos na conta.

**Resposta `200`**

- `user` (object) — `id`, `email`, `display_name`, `plan`, `api_access_status`, `trial_days_remaining`, `tenant_role`, `can_manage_tenant` e `needs_terms_acceptance`.
- `organization` (object) — `id`, `name`, `personal`, `pii_policy`, os limites (`rpm_limit`, `monthly_request_limit`, `monthly_token_limit`), a origem (`network`) e o `role`.
- `legal_retention_days` (number) — Os dias da retenção legal cifrada que o aceite cobre.

**Erros**

- `401` — Sem sessão da conta.
- `404` — Organização desconhecida para esta conta.

**Exemplo**

```js
await MMConta.fetch("https://staging.rota-nacional.ia.br/api/app/perfil").then(r => r.json());
```

### `POST /api/app/aceite`

Registra o aceite dos Termos de Uso e da retenção legal cifrada de prompts e saídas, pela pessoa da sessão.

- **URL:** `https://staging.rota-nacional.ia.br/api/app/aceite`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Headers**

- `X-Organization-Id` (string) — A organização em que o pedido age (sem ele, a conta pessoal); o vínculo e o papel são conferidos na conta.

**Corpo** (`application/json`)

- `accepted_terms` (bool, obrigatório) — `true`: aceita os Termos de Uso.
- `accepted_legal_retention` (bool, obrigatório) — `true`: autoriza a retenção legal cifrada pelo prazo do perfil.

**Resposta `200`**

- `user` (object) — O perfil de novo, já com `needs_terms_acceptance: false`.
- `organization` (object) — A organização aberta.

**Erros**

- `400` — Faltou aceitar um dos dois (`terms_required`).
- `401` — Sem sessão da conta.

**Exemplo**

```js
await MMConta.fetch("https://staging.rota-nacional.ia.br/api/app/aceite", {method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify({accepted_terms: true, accepted_legal_retention: true})});
```

### `PATCH /api/app/organizacao`

Muda a origem de inferência da organização: os países e as redes de onde a chave pode chamar a API.

- **URL:** `https://staging.rota-nacional.ia.br/api/app/organizacao`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Headers**

- `X-Organization-Id` (string) — A organização em que o pedido age (sem ele, a conta pessoal); o vínculo e o papel são conferidos na conta.

**Corpo** (`application/json`)

- `inference_geo_policy` (string) — `allowlist` (só os países e IPs listados) ou `disabled`.
- `allowed_countries` (string[]) — Países permitidos, em ISO 3166-1 alfa-2 (`BR`).
- `allowed_ips` (string[]) — IPs ou faixas CIDR permitidos.

**Resposta `200`**

- `ok` (bool) — `true` quando gravou.
- `network` (object) — A origem gravada.

**Erros**

- `400` — Política, país ou IP inválido, ou nenhum país nem IP na `allowlist`.
- `401` — Sem sessão da conta.
- `403` — Só o dono ou um administrador muda a origem (ou falta o aceite).
- `404` — Organização desconhecida para esta conta.

**Exemplo**

```js
await MMConta.fetch("https://staging.rota-nacional.ia.br/api/app/organizacao", {method: "PATCH", headers: {"content-type": "application/json"}, body: JSON.stringify({inference_geo_policy: "allowlist", allowed_countries: ["BR"], allowed_ips: []})});
```

### `GET /api/app/resumo`

O resumo do painel: o acesso, hoje, o mês, a cota, os últimos 30 dias e os modelos mais usados do mês.

- **URL:** `https://staging.rota-nacional.ia.br/api/app/resumo`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Headers**

- `X-Organization-Id` (string) — A organização em que o pedido age (sem ele, a conta pessoal); o vínculo e o papel são conferidos na conta.

**Resposta `200`**

- `access` (object) — `api_access_status`, `access_reason`, o teste e a liberação comercial.
- `today` (object) — `requests`, `total_tokens` e `pii_total` de hoje (UTC).
- `month` (object) — Os mesmos números no mês.
- `quota` (object) — Os limites, o usado, o que resta e `reset_at`.
- `series` (object[]) — Um dia por item: `date`, `requests`, `total_tokens`, `pii_total`.
- `top_models` (object[]) — Até 5: `model_id`, `requests`, `total_tokens`.

**Erros**

- `401` — Sem sessão da conta.
- `403` — Sem o aceite dos Termos e da retenção legal (`terms_required`).
- `404` — Organização desconhecida para esta conta.

**Exemplo**

```js
await MMConta.fetch("https://staging.rota-nacional.ia.br/api/app/resumo").then(r => r.json());
```

### `GET /api/app/quota`

A cota do mês: o plano, o limite por minuto, os pedidos e tokens usados e o que resta, e quando reinicia.

- **URL:** `https://staging.rota-nacional.ia.br/api/app/quota`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Headers**

- `X-Organization-Id` (string) — A organização em que o pedido age (sem ele, a conta pessoal); o vínculo e o papel são conferidos na conta.

**Resposta `200`**

- `quota` (object) — `plan`, `rpm_limit`, os limites do mês, o usado, o restante e `reset_at`.

**Erros**

- `401` — Sem sessão da conta.
- `403` — Sem o aceite dos Termos e da retenção legal (`terms_required`).
- `404` — Organização desconhecida para esta conta.

**Exemplo**

```js
await MMConta.fetch("https://staging.rota-nacional.ia.br/api/app/quota").then(r => r.json());
```

### `GET /api/app/uso`

O uso do mais novo para o mais velho, em páginas: só metadados, nunca o texto nem os valores pessoais.

- **URL:** `https://staging.rota-nacional.ia.br/api/app/uso`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Query**

- `cursor` (string) — O `next_cursor` da página anterior. Ex.: `2026-09-29 12:00:00.000|evt_1`.
- `limit` (int) — Eventos por página, de 1 a 100 (padrão 50). Ex.: `50`.

**Headers**

- `X-Organization-Id` (string) — A organização em que o pedido age (sem ele, a conta pessoal); o vínculo e o papel são conferidos na conta.

**Resposta `200`**

- `events` (object[]) — Quando, modelo, rota, status, latência, tokens, a política e as categorias e contagens de dados pessoais, a chave e a origem.
- `has_more` (bool) — Há mais eventos depois desta página.
- `next_cursor` (string, pode ser null) — O cursor da próxima página.

**Erros**

- `401` — Sem sessão da conta.
- `403` — Sem o aceite dos Termos e da retenção legal (`terms_required`).
- `404` — Organização desconhecida para esta conta.

**Exemplo**

```js
await MMConta.fetch("https://staging.rota-nacional.ia.br/api/app/uso?limit=50").then(r => r.json());
```

### `GET /api/app/modelos`

O catálogo com a preferência da pessoa: o bloqueado recusa a chamada da chave dela com 403; e o padrão.

- **URL:** `https://staging.rota-nacional.ia.br/api/app/modelos`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Headers**

- `X-Organization-Id` (string) — A organização em que o pedido age (sem ele, a conta pessoal); o vínculo e o papel são conferidos na conta.

**Resposta `200`**

- `models` (object[]) — O catálogo com `enabled` e `is_default` de cada modelo.

**Erros**

- `401` — Sem sessão da conta.
- `403` — Sem o aceite dos Termos e da retenção legal (`terms_required`).
- `404` — Organização desconhecida para esta conta.

**Exemplo**

```js
await MMConta.fetch("https://staging.rota-nacional.ia.br/api/app/modelos").then(r => r.json());
```

### `POST /api/app/modelos`

Permite ou bloqueia um modelo do catálogo para as chaves da pessoa, ou o torna o padrão.

- **URL:** `https://staging.rota-nacional.ia.br/api/app/modelos`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Headers**

- `X-Organization-Id` (string) — A organização em que o pedido age (sem ele, a conta pessoal); o vínculo e o papel são conferidos na conta.

**Corpo** (`application/json`)

- `model_id` (string, obrigatório) — O id do modelo no catálogo (`rota/*`).
- `enabled` (bool) — `false` bloqueia: a API recusa o modelo com 403.
- `is_default` (bool) — `true` torna o modelo o padrão (e permitido).

**Resposta `200`**

- `models` (object[]) — O catálogo com a preferência já mudada.

**Erros**

- `400` — Id fora do catálogo.
- `401` — Sem sessão da conta.
- `403` — Sem o aceite dos Termos e da retenção legal (`terms_required`).
- `404` — Organização desconhecida para esta conta.

**Exemplo**

```js
await MMConta.fetch("https://staging.rota-nacional.ia.br/api/app/modelos", {method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify({model_id: "rota/rapido", enabled: false})});
```

### `GET /api/app/creditos`

O saldo de crédito em reais, os preços por milhão de tokens e o extrato do Pix; a compra é o Pix da casa.

- **URL:** `https://staging.rota-nacional.ia.br/api/app/creditos`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Headers**

- `X-Organization-Id` (string) — A organização em que o pedido age (sem ele, a conta pessoal); o vínculo e o papel são conferidos na conta.

**Resposta `200`**

- `balance_centavos` (number) — O saldo em centavos de real.
- `can_buy` (bool) — Se quem pede compra (na organização, só o dono ou um administrador).
- `prices` (object[]) — Os modelos vendidos por crédito, com entrada e saída por milhão de tokens.
- `transactions` (object[]) — As compras por Pix: tipo, valor, data e descrição.

**Erros**

- `401` — Sem sessão da conta.
- `403` — Sem o aceite dos Termos e da retenção legal (`terms_required`).
- `404` — Organização desconhecida para esta conta.

**Exemplo**

```js
await MMConta.fetch("https://staging.rota-nacional.ia.br/api/app/creditos").then(r => r.json());
```

### `POST /api/app/privacy/clean`

O teste da barreira no painel: um texto curto pela mesma limpeza da API, com a política da organização.

Só `text`, até 8 KB, e no máximo 10 por minuto; conta na cota do mês e fica na auditoria cifrada.

- **URL:** `https://staging.rota-nacional.ia.br/api/app/privacy/clean`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Headers**

- `X-Organization-Id` (string) — A organização em que o pedido age (sem ele, a conta pessoal); o vínculo e o papel são conferidos na conta.

**Corpo** (`application/json`)

- `text` (string, obrigatório) — O texto de teste (fictício), até 8 KB.

**Resposta `200`**

- `clean_text` (string) — O que chegaria ao modelo, com os marcadores.
- `privacy` (object) — Categorias, contagens e total, nunca os valores.

**Erros**

- `401` — Sem sessão da conta.
- `403` — Acesso não liberado, ou falta o aceite.
- `404` — Organização desconhecida para esta conta.
- `413` — Texto acima de 8 KB.
- `422` — Bloqueado pela política.
- `429` — Limite por minuto ou cota.

**Exemplo**

```js
await MMConta.fetch("https://staging.rota-nacional.ia.br/api/app/privacy/clean", {method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify({text: "Contato: teste@example.com"})});
```

## Site

### `GET /api/public/stats`

Os números públicos da home: pedidos, tokens e dados pessoais tratados, os modelos mais usados e os 14 dias.

- **URL:** `https://staging.rota-nacional.ia.br/api/public/stats`
- **Auth:** `none` — Público.

**Resposta `200`**

- `totals` (object) — `requests`, `tokens`, `pii_items` e `active_models`, desde o início.
- `last_30_days` (object) — `requests`, `tokens` e `pii_items` dos últimos 30 dias.
- `top_models` (object[]) — Os mais usados em 30 dias: `id`, `display_name`, `requests` e `tokens`.
- `series` (object[]) — Um dia por item: `date`, `requests` e `tokens`.

**Exemplo**

```sh
curl -s https://staging.rota-nacional.ia.br/api/public/stats
```

## Estruturas

### `PaymentQuota`

- `free` (PaymentFree[]) — Free allowances and their windows. → ver `PaymentFree` em **Estruturas**.
- `paid` (PaymentPrice[]) — List prices in USD. The operation's 402 is the payable quote. → ver `PaymentPrice` em **Estruturas**.
- `how_to_pay` (string) — Payment instructions and availability restrictions.
- `live` (string, pode ser null) — Authoritative product quota endpoint.
- `free_now` (string[], opcional) — SKUs temporarily free despite their list price.
- `trial` (PaymentTrial, opcional) — Registration trial, when offered. → ver `PaymentTrial` em **Estruturas**.

### `PaymentX402`

x402 payment configuration in force. Comes from `planPublic` and is the same across the products.

- `provider` (string) — Always `x402` — the only billing protocol accepted.
- `mode` (string) — Seller mode: `live` charges for real, `dev` lets calls through unpaid.
- `network` (string) — USDC network: `base` in production, `base-sepolia` in staging.
- `chain_id` (int) — EVM chain ID of the network above, so the wallet signs on the right chain.
- `pay_to` (string, pode ser null) — Address that receives the payment.
- `homolog` (bool) — Staging seam on: the loop can be closed without spending USDC.
- `dev` (bool) — Development mode: the 402 is simulated.
- `dev_gate` (bool) — A homologation credential is configured; this grants no access.
- `gratis` (string[], opcional) — Temporarily free SKUs.
- `facilitator` (string) — URL of the facilitator that verifies and settles the payment.
- `asset` (string) — Accepted currency — always `USDC`.
- `asset_address` (string) — USDC contract on the network above.
- `faucet` (string, pode ser null) — Test-USDC faucet; only on base-sepolia.
- `wallets` (object) — Links to wallets that speak x402 (metamask, coinbase, base_app).

### `PaymentCredit`

- `url` (string) — POST to purchase credit; GET with X-Credito to inspect its balance.
- `header` (string) — Header for a previously issued credit token: X-Credito.

### `PaymentFree`

- `o_que` (string) — Operation or allowance.
- `limite` (string) — Allowance and eligibility.
- `janela` (string, pode ser null) — Reset window, when applicable.

### `PaymentPrice`

- `o_que` (string) — Operation and billing unit.
- `price_usd` (number) — Current list price in USD.

### `PaymentTrial`

- `days` (int) — Trial duration in days.
- `how` (string) — Eligibility and activation steps.