# Rota Nacional — referência completa da API

> Gerada do catálogo em https://inferencia.sistemaaguia.com · build `dev`
> 117 endpoints · 6 estruturas
> Índice curto: https://inferencia.sistemaaguia.com/llms.txt · Spec: https://inferencia.sistemaaguia.com/openapi.json · MCP: https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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.
- `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.
- `chave_ou_token` — A chave de API, a credencial da carteira (`Bearer mmw_…`) ou o `token` do job (`?token=`) que vem nas URLs do 202 de quem pagou por x402 sem chave.
- `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 `X-Credito`). Para saldo recuperado de x402, use a credencial de carteira `mmw_…` em Bearer ou `X-Wallet-Token`, emitida por `/api/auth/wallet/agent/start` e `/api/auth/wallet/agent/token`.

## 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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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.

A SDK do produto também retorna profile e administration. administration contém {href} para o dono da plataforma que entrou com passkey, autenticador ou código de recuperação; nos demais casos, null. O servidor deriva esse campo da conta autenticada. authTime é a hora da entrada de uma sessão do navegador; numa chave de API ou num token OAuth, é null.

- **URL:** `https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com";
  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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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 feita há até 2 horas; 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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://inferencia.sistemaaguia.com/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();
})();
```

### `GET /api/account/apps`

Lista os apps conectados à sua conta neste produto.

Os clientes de MCP em que você entrou com a conta (OAuth), como o claude.ai ou o ChatGPT. Nunca devolve token.

- **URL:** `https://inferencia.sistemaaguia.com/api/account/apps`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

- `apps` (object[]) — Até 50: `id`, `nome` (o app; o host dele quando ele se identifica por documento de metadados), `criadoEm`, `usadoEm` (por hora, ou null).

**Erros**

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

**Exemplo**

```js
await fetch("https://inferencia.sistemaaguia.com/api/account/apps", {credentials: "same-origin"}).then(r => r.json());
```

### `POST /api/account/apps/revoke`

Desconecta um app da sua conta.

Para o acesso do app na hora; ele pede o login de novo. Repetir não faz mal.

- **URL:** `https://inferencia.sistemaaguia.com/api/account/apps/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` do app.

**Exemplo de corpo**

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

**Resposta `200`**

- `ok` (bool) — true

**Erros**

- `400` — invalid_app_id
- `401` — invalid_session
- `403` — invalid_origin / invalid_csrf
- `404` — app_not_found
- `503` — auth_unavailable

**Exemplo**

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

### `GET /api/account/callouts`

Lista os avisos que você fechou neste produto.

As chaves dos avisos que ficam fechados para a sua conta, em todo aparelho, como a explicação de uma área.

- **URL:** `https://inferencia.sistemaaguia.com/api/account/callouts`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

- `callouts` (string[]) — Até 200 chaves, em ordem alfabética.

**Erros**

- `401` — invalid_session
- `403` — product_required
- `503` — auth_unavailable

**Exemplo**

```js
await fetch("https://inferencia.sistemaaguia.com/api/account/callouts", {credentials: "same-origin"}).then(r => r.json());
```

### `POST /api/account/callouts/dismiss`

Fecha um aviso de vez.

O aviso não abre de novo para a sua conta neste produto. Repetir não faz mal.

- **URL:** `https://inferencia.sistemaaguia.com/api/account/callouts/dismiss`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

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

- `key` (string, obrigatório) — A chave do aviso: letras, números e `_.:-`, até 80.

**Exemplo de corpo**

```json
{
  "key": "financeiro_expense"
}
```

**Resposta `200`**

- `ok` (bool) — true

**Erros**

- `400` — invalid_callout
- `401` — invalid_session
- `403` — invalid_origin / invalid_csrf
- `409` — too_many_callouts
- `503` — auth_unavailable

**Exemplo**

```js
(async () => {
  const {csrf} = await fetch("https://inferencia.sistemaaguia.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://inferencia.sistemaaguia.com/api/account/callouts/dismiss", {method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({key: "financeiro_expense"})});
  return r.json();
})();
```

### `POST /api/account/callouts/reopen`

Reabre um aviso fechado.

Desfaz o fechar: o aviso volta para a sua conta neste produto. O produto guarda aqui também uma escolha de ligar e desligar, como os valores ocultos do Financeiro. Repetir não faz mal.

- **URL:** `https://inferencia.sistemaaguia.com/api/account/callouts/reopen`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

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

- `key` (string, obrigatório) — A chave do aviso: letras, números e `_.:-`, até 80.

**Exemplo de corpo**

```json
{
  "key": "financeiro_expense"
}
```

**Resposta `200`**

- `ok` (bool) — true

**Erros**

- `400` — invalid_callout
- `401` — invalid_session
- `403` — invalid_origin / invalid_csrf
- `503` — auth_unavailable

**Exemplo**

```js
(async () => {
  const {csrf} = await fetch("https://inferencia.sistemaaguia.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://inferencia.sistemaaguia.com/api/account/callouts/reopen", {method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({key: "financeiro_expense"})});
  return r.json();
})();
```

### `POST /api/auth/wallet/agent/start`

Começa a credencial de carteira do agente sem conta.

Sem conta: a carteira prova que é dela assinando a mensagem (EIP-4361). Assinar não paga nem transfere nada. A mensagem diz este produto e vale 5 minutos. Antes de assinar, compare a mensagem com a URL chamada. O domínio da primeira linha deve ser o host dessa URL. O URI deve ser a origem dela. Se um deles for diferente, não assine. Assine com personal_sign e envie a /api/auth/wallet/agent/token.

- **URL:** `https://inferencia.sistemaaguia.com/api/auth/wallet/agent/start`
- **Auth:** `none` — Público.

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

- `address` (string, obrigatório) — 0x…, a carteira (EOA ou contrato na Base)

**Exemplo de corpo**

```json
{
  "address": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23"
}
```

**Resposta `200`**

- `message` (string) — EIP-4361
- `issuedAt` (number) — segundos / seconds
- `expiresIn` (number) — 300

**Erros**

- `400` — invalid_wallet_address
- `503` — auth_unavailable

**Exemplo**

```sh
curl -s -XPOST https://inferencia.sistemaaguia.com/api/auth/wallet/agent/start -H 'content-type: application/json' -d '{"address":"0x2c7536E3605D9C16a7a3D7b1898e529396a65c23"}'
```

### `POST /api/auth/wallet/agent/token`

Recebe a credencial da carteira (mmw_…) deste produto.

A assinatura da carteira na mensagem do start, conferida aqui (chave própria) ou na Base (contrato, EIP-1271/6492). A credencial vale 30 dias: envie `Authorization: Bearer mmw_…` às rotas que aceitam a carteira como dona (dono `x402:<endereço>`). Vinculada a carteira a uma conta, o que ela fez aqui passa para a conta quando a pessoa entra.

- **URL:** `https://inferencia.sistemaaguia.com/api/auth/wallet/agent/token`
- **Auth:** `none` — Público.

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

- `address` (string, obrigatório) — 0x…, a mesma carteira do start / the same wallet as in start
- `issuedAt` (number, obrigatório) — o issuedAt do start / start's issuedAt
- `signature` (string, obrigatório) — personal_sign (0x…)

**Exemplo de corpo**

```json
{
  "address": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23",
  "issuedAt": 1791400000,
  "signature": "0x…"
}
```

**Resposta `200`**

- `token` (string) — mmw_…
- `owner` (string) — x402:0x…
- `expiresAt` (number) — segundos / seconds

**Erros**

- `400` — invalid_body
- `401` — invalid_wallet
- `429` — wallet_limited
- `503` — wallet_unavailable / auth_unavailable

**Exemplo**

```sh
curl -s -XPOST https://inferencia.sistemaaguia.com/api/auth/wallet/agent/token -H 'content-type: application/json' -d '{"address":"0x2c7536E3605D9C16a7a3D7b1898e529396a65c23","issuedAt":1791400000,"signature":"0x…"}'
```

### `POST /api/auth/claim/wallets`

Passa para a conta o que as carteiras dela fizeram sem conta.

A janela de entrar chama depois de toda entrada. Para cada carteira vinculada à conta: os direitos comprados aqui por x402 (dono x402:<endereço>) e o que este produto guarda desse dono. Repetir não move nada.

- **URL:** `https://inferencia.sistemaaguia.com/api/auth/claim/wallets`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

- `carteiras` (number) — wallets
- `direitos` (number) — rights moved

**Erros**

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

**Exemplo**

```sh
await MMConta.fetch(new URL("https://inferencia.sistemaaguia.com/api/auth/claim/wallets").pathname, { method: "POST", headers: { "content-type": "application/json" }, body: "{}" })
```

## Descoberta

### `GET /api/`

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

- **URL:** `https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/mcp`
- **Auth:** `none` — Público.

**Resposta `200`**

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

**Exemplo**

```sh
curl -s -XPOST https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/pricing
```

### `GET /api/billing`

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

- **URL:** `https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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/resumo`

Operador: o resumo agregado do funil, calculado neste app. O diário não sai do servidor.

Só contagens e listas agregadas: pessoas por etapa, valores, entradas, canais, países e aparelhos. Nenhuma sessão, navegador ou linha do diário sai. Traz as janelas de 1 e 7 dias UTC e os três dias do painel no fuso de Brasília. O app guarda 7 dias de diário.

- **URL:** `https://inferencia.sistemaaguia.com/api/funil/resumo`
- **Auth:** `none` — Público.

**Headers**

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

**Resposta `200`**

- `v` (number) — Versão do resumo: `1`.
- `produto` (string) — O produto.
- `fuso` (string) — O fuso dos dias do painel.
- `desde` (string) — O dia mais antigo do diário (`AAAA-MM-DD`, UTC); vazio sem diário.
- `atualizado` (string) — Quando o resumo foi calculado (ISO 8601).
- `janelas` (object) — `1d` e `7d`: a janela agregada, com `etapas`, `amostra`, `valores`, `qualidade` e as listas.
- `dias` (object[]) — Os três dias do painel: `{ day, from, to, janela, medicao }`.

**Erros**

- `401` — Unauthorized
- `404` — Not found
- `500` — Funnel summary failed
- `503` — Not configured

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/api/funil/resumo -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`), os jobs `rn.*` aceitos por dia (`usage.rn_job`) e o total de projetos (`accounts.tenants`). Com `METRICS_TOKEN` em Bearer acrescenta o financeiro do razão da casa.

- **URL:** `https://inferencia.sistemaaguia.com/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` (pedidos da API) e `rn_job` (jobs `rn.*` aceitos): o de hoje (`today`) e o 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://inferencia.sistemaaguia.com/api/metrics
```

### `POST /api/visit`

O aviso da tela que soma uma visita ao dia. Agentes não precisam chamar.

A tela manda o aviso no primeiro gesto de quem usa (toque, tecla ou clique), uma vez por página. Teste não conta: `X-MM-Smoke`, User-Agent `mm-smoke` ou `smoke: true` no corpo voltam com `counted: false`. Só o aviso da própria página conta: a chamada de fora de uma página do mesmo site (User-Agent de robô, ou sem `Sec-Fetch-Site: same-origin`) volta com `counted: false` e `reason: "robo"`.

- **URL:** `https://inferencia.sistemaaguia.com/api/visit`
- **Auth:** `none` — Público.

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

- `p` (string) — O caminho da página visitada.
- `smoke` (bool) — `true` marca o pedido como teste, e ele não entra na conta.

**Exemplo de corpo**

```json
{
  "p": "/"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true`.
- `counted` (bool) — Se a visita entrou na conta do dia.
- `reason` (string, opcional) — Por que não contou, quando `counted` é `false`.

**Exemplo**

```sh
curl -s -XPOST https://inferencia.sistemaaguia.com/api/visit -H 'content-type: application/json' -d '{"p":"/","smoke":true}'
```

### `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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/vitrine
```

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

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

- **URL:** `https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/vitrine/painel -H "Authorization: Bearer $METRICS_TOKEN"
```

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

Cursores por produto: `borda`, `borda5xx` (só 5xx) e `cli`. Só com token do operador.

- **URL:** `https://inferencia.sistemaaguia.com/api/vitrine/cursores`
- **Auth:** `none` — Público.

**Headers**

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

**Resposta `200`**

JSON: `{ [produto]: { borda?: ISO, borda5xx?: 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://inferencia.sistemaaguia.com/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. Para voz, envie multipart/form-data: `dados` contém este JSON (até 32 KiB) e `audio` contém um arquivo de áudio WebM, Ogg ou M4A (até 2 MB). O áudio pode substituir message. O navegador grava até dois minutos. O áudio vai como anexo ao e-mail do dono.

- **URL:** `https://inferencia.sistemaaguia.com/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`).
- `whatsapp` (string) — Número opcional para resposta, com código do país. Ex.: +5561999999999.
- `prefer_whatsapp` (bool) — Pede resposta por WhatsApp. Exige whatsapp.
- `tipo` (string) — Proposta: `patrocinio`, `parceria`, `anuncio` ou `consultoria`. Liga os campos abaixo.
- `empresa` (string) — Quem propõe, quando é empresa.
- `site` (string) — Site de quem propõe.
- `orcamento` (string) — Anúncio: `ate_100`, `100_500`, `500_2000`, `2000_mais` ou `a_combinar`. Consultoria, em dólar: `ate_2000`, `2000_5000`, `5000_10000`, `10000_mais` ou `nao_sei`.
- `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`.
- `projeto` (string) — Consultoria: o tipo de projeto (`llm_privado`, `voz`, `dados_sensiveis`, `gpu`, `integracao` ou `outro`).
- `prazo` (string) — Consultoria: quando começar (`agora`, `1_mes`, `1_3_meses` ou `explorando`).
- `formato` (string) — Consultoria: `projeto` (por escopo), `mensal` ou `assessoria`.
- `pais` (string) — Consultoria: o país de quem pede.
- `fuso` (string) — Consultoria: o fuso IANA, como `America/New_York`.
- `horarios` (string[]) — Consultoria: até 3 horários para a conversa, `AAAA-MM-DDTHH:MM` na hora do fuso.

**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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/partners
```

## Crédito

### `GET /api/credito/x402/saude`

Saúde do verificador x402: pendências, falta de hash e falha ou parada da conciliação.

- **URL:** `https://inferencia.sistemaaguia.com/api/credito/x402/saude`
- **Auth:** `none` — Público.

**Resposta `200`**

- `verificado_em` (string) — Hora da leitura, em UTC.
- `ativo` (boolean) — Verificador configurado no processo. → ver `boolean` em **Estruturas**.
- `tarefas` (object[]) — Falhas com id e motivo, sem dados do pagador. Contagem limitada indica +.

**Erros**

- `503` — Verificador indisponível neste processo.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/api/credito/x402/saude
```

### `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://inferencia.sistemaaguia.com/api/credito`
- **Auth:** `none` — Público.

**Query**

- `usd` (number, obrigatório) — Pacote: 0.1, 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.
- `usar_com_outra_credencial` (string) — O header `X-Credito`, para quando o `Authorization` já leva outra credencial.
- `saldo_em` (string) — Onde consultar saldo e extrato.
- `onde_gastar` (object) — `precos`: as ações pagas e os preços deste produto (`/api/pricing`); `produtos`: o APIs.json com os outros produtos da casa.

**Erros**

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

**Exemplo**

```sh
curl -s -XPOST 'https://inferencia.sistemaaguia.com/api/credito?usd=10'
```

### `GET /api/credito`

Saldo e extrato com cred_…; com mmw_…, saldo da carteira e até 20 pagamentos em recuperação.

- **URL:** `https://inferencia.sistemaaguia.com/api/credito`
- **Auth:** `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou `X-Credito`). Para saldo recuperado de x402, use a credencial de carteira `mmw_…` em Bearer ou `X-Wallet-Token`, emitida por `/api/auth/wallet/agent/start` e `/api/auth/wallet/agent/token`.

**Query**

- `movimentos` (string) — `1`: consulta só o histórico paginado, sem saldo.
- `de` (string) — Início inclusivo em UTC ISO 8601 com milissegundos. Padrão: 1970-01-01T00:00:00.000Z.
- `ate` (string) — Fim exclusivo em UTC ISO 8601 com milissegundos. Padrão: agora. Conserve o valor entre páginas.
- `antes` (string) — Cursor `proximo` da página anterior. Só com movimentos=1.
- `limite` (int) — 1 a 50 movimentos por página; padrão 20. Só com movimentos=1.

**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.
- `wallet` (string) — Só com mmw_…: endereço autenticado da carteira.
- `payments` (object[]) — Só com mmw_…: até 20 pagamentos, com id, produto, rede, tx_hash, micros, estado e criado_ms. creditado indica saldo recuperado.
- `proximo` (string|null) — Só com movimentos=1: cursor da próxima página ou null; movimentos inclui id, em, valor_usd, saldo_usd, motivo, produto e recurso. → ver `string|null` em **Estruturas**.
- `onde_gastar` (object) — `precos`: as ações pagas e os preços deste produto; `produtos`: o APIs.json com os outros produtos da casa.

**Erros**

- `400` — Período, limite ou cursor inválido.
- `401` — Sem token ou token desconhecido.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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 (3, 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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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 (3, 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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/credito/pix/0123456789abcdef0123456789abcdef
```

### `POST /api/credito/asaas/:id/cancelar`

Cancela uma cobrança pendente ao fechar o pagamento.

Exige o bilhete `cancelamento` devolvido na criação. Uma cobrança antiga de crédito aceita seu token em `credito`. Só atua no produto e ambiente de origem. Não estorna pagamentos nem remove o histórico. 202 indica cancelamento em andamento; a vigia retoma falhas externas.

- **URL:** `https://inferencia.sistemaaguia.com/api/credito/asaas/:id/cancelar`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

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

**Resposta `200`**

- `id` (string) — Id da cobrança.
- `estado` (string) — `cancelando`, `vencido` ou o estado final já confirmado.

**Erros**

- `404` — Cobrança ou bilhete inválido, produto ou ambiente diferente.

**Exemplo**

```sh
curl -s -XPOST https://inferencia.sistemaaguia.com/api/credito/asaas/0123456789abcdef0123456789abcdef/cancelar -H 'content-type: application/json' -d '{"cancelamento":"<bilhete>"}'
```

### `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://inferencia.sistemaaguia.com/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 (3, 5, 10 ou 25 dólares), com `brl_centavos`.
- `exatos` (object[]) — Preços declarados pelo app, com `usd` e `brl_centavos`. Só aparecem a partir de R$ 5,00 e até R$ 10.000.
- `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://inferencia.sistemaaguia.com/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. Com `forma: "cartao_boleto"`, a cobrança é livre: a resposta traz `pagamento_em`, a página do gateway onde se paga com cartão, boleto ou Pix (vence em três dias). Com `forma: "cartao"` e o `cartao` (`titular`, `numero`, `mes`, `ano`, `cvv`, `documento`, `email`, `cep`, `numero_endereco`, `telefone`), a cobrança é paga no cartão no mesmo pedido: 200 com `estado: "pago"`, 202 com `conferir` enquanto o emissor analisa, 422 quando o cartão é recusado; o cartão não fica guardado. O `usd` deve ser um valor de `pacotes` ou `exatos` do GET. O servidor define os centavos e recusa valores não declarados.

- **URL:** `https://inferencia.sistemaaguia.com/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 pagamento cair.
- `forma` (string) — `pix` (o padrão), `cartao` ou `cartao_boleto`.
- `pix` (object) — `copia_e_cola`, `imagem` (QR em PNG, data URI) e `expira_em`; só na forma `pix`.
- `pagamento_em` (string) — Na forma `cartao_boleto`: a página de pagamento do gateway.
- `estado` (string) — Na forma `cartao`: `pago`, ou `pendente` com `conferir`.
- `estado_em` (string) — Onde acompanhar o pagamento.
- `cancelamento` (string) — Bilhete para cancelar a cobrança pendente de Pix ou boleto.

**Erros**

- `400` — Crédito fora de `pacotes` e `exatos`, valor fora da faixa, CPF/CNPJ, nome ou e-mail inválido, dado do cartão inválido (`cartao_dados`, com o `campo`), ou o gateway recusou o pagador (`pagador_recusado`, com a razão em `detalhe`).
- `422` — Cartão recusado (`cartao_recusado`, com o `campo` quando o gateway diz qual); troque em `POST /api/credito/asaas/:id/cartao`.
- `429` — Limite de 3 tentativas por minuto ou 10 por dia, por conta ou rede, ou limite do cartão.
- `502` — O gateway não gerou o Pix; tente de novo.
- `503` — Pix automático indisponível neste app, o gateway ocupado (`asaas_ocupado`, espere `retry_after_s`), ou cobranças demais de quem não entrou esperando pagamento.

**Exemplo**

```sh
curl -s -XPOST https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/credito/asaas/0123456789abcdef0123456789abcdef
```

### `POST /api/credito/asaas/:id/cartao`

Paga com outro cartão a cobrança de cartão cujo cartão foi recusado: a mesma cobrança, sem cobrar duas vezes.

JSON com o `cartao` (os mesmos campos do `POST /api/credito/asaas`) e, sem conta, o `navegador_id` que criou a cobrança. Só a cobrança de cartão que espera pagamento, de quem a criou, e até cinco tentativas por cobrança.

- **URL:** `https://inferencia.sistemaaguia.com/api/credito/asaas/:id/cartao`
- **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`, ou `pendente` com `conferir` enquanto o emissor analisa.
- `estado_em` (string) — Onde acompanhar o pagamento.

**Erros**

- `400` — Dado do cartão inválido (`cartao_dados`, com o `campo`).
- `404` — Cobrança desconhecida, de outra pessoa ou que não é de cartão.
- `409` — A cobrança já venceu ou foi encerrada; comece o pagamento de novo.
- `422` — Cartão recusado (`cartao_recusado`).
- `429` — Passou das tentativas de cartão desta cobrança ou do dia.

**Exemplo**

```sh
curl -s -XPOST https://inferencia.sistemaaguia.com/api/credito/asaas/0123456789abcdef0123456789abcdef/cartao -H 'content-type: application/json' -d '{"cartao":{…}}'
```

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

A saúde do Pix e das assinaturas ativas deste app: falhas com motivo, para o painel.

- **URL:** `https://inferencia.sistemaaguia.com/api/credito/asaas/saude`
- **Auth:** `none` — Público.

**Resposta `200`**

- `ativo` (boolean) — `false` quando o Asaas e as assinaturas estão desligados. → ver `boolean` em **Estruturas**.
- `tarefas` (object[]) — Cada problema: `id`, `falhando` e `motivo`. Inclui Pix e, quando ativas, recuperação, fila e orçamento das assinaturas. Não consulta o provedor.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/api/credito/asaas/saude
```

## Modelos

### `GET /v1/models`

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

- **URL:** `https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/v1/chat/completions`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem chave, a chamada paga por x402: o corpo traz o preço em reais (`preco_brl`), o `accepts` e os termos. No chat, o preço é o teto (os tokens de entrada estimados e o `max_tokens`, padrão 1.024); a sobra fica no saldo da carteira.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado (sem chave, só os modelos vendidos por crédito: `model_not_sold_per_use`) 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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/v1/messages`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem chave, a chamada paga por x402: o corpo traz o preço em reais (`preco_brl`), o `accepts` e os termos. No chat, o preço é o teto (os tokens de entrada estimados e o `max_tokens`, padrão 1.024); a sobra fica no saldo da carteira.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado (sem chave, só os modelos vendidos por crédito: `model_not_sold_per_use`) 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://inferencia.sistemaaguia.com/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á"}]}'
```

## Native gateway

### `POST /v1/providers/{provider}/v1/chat/completions`

Native chat completions

Requires an organization API key and an active private provider connection with native consent. The original provider body and model are preserved. Personal data is sent without the privacy barrier. Use the protected rota/* catalog when the request requires that barrier. Resources remain scoped to the organization and the connection that created them. A submitted request is not retried by the gateway. Provider charges remain on the connected provider account.

- **URL:** `https://inferencia.sistemaaguia.com/v1/providers/{provider}/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.
- Send the original native JSON body. JSON is limited to 32 MiB. Examples use synthetic text. FILE_ID, BATCH_ID and INPUT_FILE_ID must come from successful gateway responses in this organization. Batch input requires a validated file uploaded with purpose=batch.

**Parâmetros de caminho**

- `provider` (string, obrigatório) — The provider identifier configured by the administrator.

**Headers**

- `X-RN-Connection-Id` (string) — Optional private connection identifier. Existing resources retain their original connection.

**Resposta `200`**

Original provider response: native JSON, event stream or file bytes. The content type is preserved.

**Erros**

- `400` — Invalid or unsupported native input.
- `401` — An organization API key is required.
- `403` — The organization or network policy denied access.
- `404` — The resource is not registered in this organization, or the endpoint is unsupported.
- `409` — Referenced resources use different connections.
- `413` — The request exceeds the body limit.
- `429` — The request rate or a provider limit was exceeded.
- `503` — No active private connection is available for this organization and provider.

**Exemplo**

```sh
curl -sS "https://inferencia.sistemaaguia.com/v1/providers/openai/v1/chat/completions" -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"Hello"}],"max_tokens":16}'
```

### `POST /v1/providers/openai/v1/responses`

Native OpenAI Responses request

Requires an organization API key and an active private provider connection with native consent. The original provider body and model are preserved. Personal data is sent without the privacy barrier. Use the protected rota/* catalog when the request requires that barrier. Resources remain scoped to the organization and the connection that created them. A submitted request is not retried by the gateway. Provider charges remain on the connected provider account.

- **URL:** `https://inferencia.sistemaaguia.com/v1/providers/openai/v1/responses`
- **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.
- Send the original native JSON body. JSON is limited to 32 MiB. Examples use synthetic text. FILE_ID, BATCH_ID and INPUT_FILE_ID must come from successful gateway responses in this organization. Batch input requires a validated file uploaded with purpose=batch.

**Headers**

- `X-RN-Connection-Id` (string) — Optional private connection identifier. Existing resources retain their original connection.

**Resposta `200`**

Original provider response: native JSON, event stream or file bytes. The content type is preserved.

**Erros**

- `400` — Invalid or unsupported native input.
- `401` — An organization API key is required.
- `403` — The organization or network policy denied access.
- `404` — The resource is not registered in this organization, or the endpoint is unsupported.
- `409` — Referenced resources use different connections.
- `413` — The request exceeds the body limit.
- `429` — The request rate or a provider limit was exceeded.
- `503` — No active private connection is available for this organization and provider.

**Exemplo**

```sh
curl -sS "https://inferencia.sistemaaguia.com/v1/providers/openai/v1/responses" -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"model":"gpt-6-luna","input":"Hello","max_output_tokens":16,"store":false}'
```

### `POST /v1/providers/{provider}/v1/messages`

Native Messages request

Requires an organization API key and an active private provider connection with native consent. The original provider body and model are preserved. Personal data is sent without the privacy barrier. Use the protected rota/* catalog when the request requires that barrier. Resources remain scoped to the organization and the connection that created them. A submitted request is not retried by the gateway. Provider charges remain on the connected provider account.

- **URL:** `https://inferencia.sistemaaguia.com/v1/providers/{provider}/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.
- Send the original native JSON body. JSON is limited to 32 MiB. Examples use synthetic text. FILE_ID, BATCH_ID and INPUT_FILE_ID must come from successful gateway responses in this organization. Batch input requires a validated file uploaded with purpose=batch.

**Parâmetros de caminho**

- `provider` (string, obrigatório) — The provider identifier configured by the administrator.

**Headers**

- `X-RN-Connection-Id` (string) — Optional private connection identifier. Existing resources retain their original connection.

**Resposta `200`**

Original provider response: native JSON, event stream or file bytes. The content type is preserved.

**Erros**

- `400` — Invalid or unsupported native input.
- `401` — An organization API key is required.
- `403` — The organization or network policy denied access.
- `404` — The resource is not registered in this organization, or the endpoint is unsupported.
- `409` — Referenced resources use different connections.
- `413` — The request exceeds the body limit.
- `429` — The request rate or a provider limit was exceeded.
- `503` — No active private connection is available for this organization and provider.

**Exemplo**

```sh
curl -sS "https://inferencia.sistemaaguia.com/v1/providers/anthropic/v1/messages" -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -H 'anthropic-version: 2023-06-01' -d '{"model":"claude-haiku-5-5","max_tokens":16,"messages":[{"role":"user","content":"Hello"}]}'
```

### `POST /v1/providers/{provider}/v1beta/models/{model}:generateContent`

Native content generation

Requires an organization API key and an active private provider connection with native consent. The original provider body and model are preserved. Personal data is sent without the privacy barrier. Use the protected rota/* catalog when the request requires that barrier. Resources remain scoped to the organization and the connection that created them. A submitted request is not retried by the gateway. Provider charges remain on the connected provider account.

- **URL:** `https://inferencia.sistemaaguia.com/v1/providers/{provider}/v1beta/models/{model}:generateContent`
- **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.
- Send the original native JSON body. JSON is limited to 32 MiB. Examples use synthetic text. FILE_ID, BATCH_ID and INPUT_FILE_ID must come from successful gateway responses in this organization. Batch input requires a validated file uploaded with purpose=batch.

**Parâmetros de caminho**

- `provider` (string, obrigatório) — The provider identifier configured by the administrator.
- `model` (string, obrigatório) — An available model identifier from the connected provider.

**Headers**

- `X-RN-Connection-Id` (string) — Optional private connection identifier. Existing resources retain their original connection.

**Resposta `200`**

Original provider response: native JSON, event stream or file bytes. The content type is preserved.

**Erros**

- `400` — Invalid or unsupported native input.
- `401` — An organization API key is required.
- `403` — The organization or network policy denied access.
- `404` — The resource is not registered in this organization, or the endpoint is unsupported.
- `409` — Referenced resources use different connections.
- `413` — The request exceeds the body limit.
- `429` — The request rate or a provider limit was exceeded.
- `503` — No active private connection is available for this organization and provider.

**Exemplo**

```sh
curl -sS "https://inferencia.sistemaaguia.com/v1/providers/gemini/v1beta/models/gemini-3.5-flash:generateContent" -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"contents":[{"parts":[{"text":"Hello"}]}]}'
```

### `POST /v1/providers/{provider}/v1beta/models/{model}:streamGenerateContent`

Native content stream

Requires an organization API key and an active private provider connection with native consent. The original provider body and model are preserved. Personal data is sent without the privacy barrier. Use the protected rota/* catalog when the request requires that barrier. Resources remain scoped to the organization and the connection that created them. A submitted request is not retried by the gateway. Provider charges remain on the connected provider account.

- **URL:** `https://inferencia.sistemaaguia.com/v1/providers/{provider}/v1beta/models/{model}:streamGenerateContent`
- **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.
- Send the original native JSON body. JSON is limited to 32 MiB. Examples use synthetic text. FILE_ID, BATCH_ID and INPUT_FILE_ID must come from successful gateway responses in this organization. Batch input requires a validated file uploaded with purpose=batch.

**Parâmetros de caminho**

- `provider` (string, obrigatório) — The provider identifier configured by the administrator.
- `model` (string, obrigatório) — An available model identifier from the connected provider.

**Headers**

- `X-RN-Connection-Id` (string) — Optional private connection identifier. Existing resources retain their original connection.

**Resposta `200`**

Original provider response: native JSON, event stream or file bytes. The content type is preserved.

**Erros**

- `400` — Invalid or unsupported native input.
- `401` — An organization API key is required.
- `403` — The organization or network policy denied access.
- `404` — The resource is not registered in this organization, or the endpoint is unsupported.
- `409` — Referenced resources use different connections.
- `413` — The request exceeds the body limit.
- `429` — The request rate or a provider limit was exceeded.
- `503` — No active private connection is available for this organization and provider.

**Exemplo**

```sh
curl -sS "https://inferencia.sistemaaguia.com/v1/providers/gemini/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse" -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"contents":[{"parts":[{"text":"Hello"}]}]}'
```

### `POST /v1/providers/{provider}/v1/batches`

Create a native batch

Requires an organization API key and an active private provider connection with native consent. The original provider body and model are preserved. Personal data is sent without the privacy barrier. Use the protected rota/* catalog when the request requires that barrier. Resources remain scoped to the organization and the connection that created them. A submitted request is not retried by the gateway. Provider charges remain on the connected provider account.

- **URL:** `https://inferencia.sistemaaguia.com/v1/providers/{provider}/v1/batches`
- **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.
- Send the original native JSON body. JSON is limited to 32 MiB. Examples use synthetic text. FILE_ID, BATCH_ID and INPUT_FILE_ID must come from successful gateway responses in this organization. Batch input requires a validated file uploaded with purpose=batch.

**Parâmetros de caminho**

- `provider` (string, obrigatório) — The provider identifier configured by the administrator.

**Headers**

- `X-RN-Connection-Id` (string) — Optional private connection identifier. Existing resources retain their original connection.

**Resposta `200`**

Original provider response: native JSON, event stream or file bytes. The content type is preserved.

**Erros**

- `400` — Invalid or unsupported native input.
- `401` — An organization API key is required.
- `403` — The organization or network policy denied access.
- `404` — The resource is not registered in this organization, or the endpoint is unsupported.
- `409` — Referenced resources use different connections.
- `413` — The request exceeds the body limit.
- `429` — The request rate or a provider limit was exceeded.
- `503` — No active private connection is available for this organization and provider.

**Exemplo**

```sh
curl -sS "https://inferencia.sistemaaguia.com/v1/providers/openai/v1/batches" -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d "{\"input_file_id\":\"$INPUT_FILE_ID\",\"endpoint\":\"/v1/responses\",\"completion_window\":\"24h\"}"
```

### `GET /v1/providers/{provider}/v1/batches/{id}`

Read an owned native batch

Requires an organization API key and an active private provider connection with native consent. The original provider body and model are preserved. Personal data is sent without the privacy barrier. Use the protected rota/* catalog when the request requires that barrier. Resources remain scoped to the organization and the connection that created them. A submitted request is not retried by the gateway. Provider charges remain on the connected provider account.

- **URL:** `https://inferencia.sistemaaguia.com/v1/providers/{provider}/v1/batches/{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**

- `provider` (string, obrigatório) — The provider identifier configured by the administrator.
- `id` (string, obrigatório) — A resource identifier returned through this gateway to this organization.

**Headers**

- `X-RN-Connection-Id` (string) — Optional private connection identifier. Existing resources retain their original connection.

**Resposta `200`**

Original provider response: native JSON, event stream or file bytes. The content type is preserved.

**Erros**

- `400` — Invalid or unsupported native input.
- `401` — An organization API key is required.
- `403` — The organization or network policy denied access.
- `404` — The resource is not registered in this organization, or the endpoint is unsupported.
- `409` — Referenced resources use different connections.
- `413` — The request exceeds the body limit.
- `429` — The request rate or a provider limit was exceeded.
- `503` — No active private connection is available for this organization and provider.

**Exemplo**

```sh
curl -sS "https://inferencia.sistemaaguia.com/v1/providers/openai/v1/batches/$BATCH_ID" -H "Authorization: Bearer $ROTA_API_KEY"
```

### `GET /v1/providers/{provider}/v1/files/{id}/content`

Read an owned native file

Requires an organization API key and an active private provider connection with native consent. The original provider body and model are preserved. Personal data is sent without the privacy barrier. Use the protected rota/* catalog when the request requires that barrier. Resources remain scoped to the organization and the connection that created them. A submitted request is not retried by the gateway. Provider charges remain on the connected provider account.

- **URL:** `https://inferencia.sistemaaguia.com/v1/providers/{provider}/v1/files/{id}/content`
- **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**

- `provider` (string, obrigatório) — The provider identifier configured by the administrator.
- `id` (string, obrigatório) — A resource identifier returned through this gateway to this organization.

**Headers**

- `X-RN-Connection-Id` (string) — Optional private connection identifier. Existing resources retain their original connection.

**Resposta `200`**

Original provider response: native JSON, event stream or file bytes. The content type is preserved.

**Erros**

- `400` — Invalid or unsupported native input.
- `401` — An organization API key is required.
- `403` — The organization or network policy denied access.
- `404` — The resource is not registered in this organization, or the endpoint is unsupported.
- `409` — Referenced resources use different connections.
- `413` — The request exceeds the body limit.
- `429` — The request rate or a provider limit was exceeded.
- `503` — No active private connection is available for this organization and provider.

**Exemplo**

```sh
curl -sS "https://inferencia.sistemaaguia.com/v1/providers/openai/v1/files/$FILE_ID/content" -H "Authorization: Bearer $ROTA_API_KEY"
```

## 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://inferencia.sistemaaguia.com/v1/privacy/clean`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem chave, a chamada paga por x402: o corpo traz o preço em reais (`preco_brl`), o `accepts` e os termos. No chat, o preço é o teto (os tokens de entrada estimados e o `max_tokens`, padrão 1.024); a sobra fica no saldo da carteira.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado (sem chave, só os modelos vendidos por crédito: `model_not_sold_per_use`) 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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/v1/privacy/jobs`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem chave, a chamada paga por x402: o corpo traz o preço em reais (`preco_brl`), o `accepts` e os termos. No chat, o preço é o teto (os tokens de entrada estimados e o `max_tokens`, padrão 1.024); a sobra fica no saldo da carteira.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado (sem chave, só os modelos vendidos por crédito: `model_not_sold_per_use`) 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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `404` — Job desconhecido para esta organização.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/v1/privacy/extract`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**Resposta `200`**

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

**Erros**

- `401` — Chave de API ausente ou inválida (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem chave, a chamada paga por x402: o corpo traz o preço em reais (`preco_brl`), o `accepts` e os termos. No chat, o preço é o teto (os tokens de entrada estimados e o `max_tokens`, padrão 1.024); a sobra fica no saldo da carteira.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado (sem chave, só os modelos vendidos por crédito: `model_not_sold_per_use`) 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://inferencia.sistemaaguia.com/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. Preço: R$ 0,01 por MB de áudio (ou fração). Paga do saldo em reais da organização (Pix no painel, pacotes de R$ 10,00 a R$ 100,00) ou por x402 com `X-PAYMENT` (USDC na Base, mínimo de US$ 0,001 por chamada), também sem chave: a carteira que paga vira a conta. O débito volta ao saldo de quem pagou se o job falhar, for cancelado ou vencer na fila.

- **URL:** `https://inferencia.sistemaaguia.com/v1/audio/transcriptions`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**Resposta `200`**

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

**Erros**

- `401` — Chave de API ausente ou inválida (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem saldo que cubra a chamada nem pagamento x402: o corpo traz o `accepts` do x402, o `preco_brl` e o `buy_credit_url`.
- `403` — Conta aguardando liberação, teste gratuito encerrado, modelo não liberado (sem chave, só os modelos vendidos por crédito: `model_not_sold_per_use`) 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://inferencia.sistemaaguia.com/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 (sem chave, só a lista; com a chave, também os workers).

- **URL:** `https://inferencia.sistemaaguia.com/v1/capabilities`
- **Auth:** `none` — Público.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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`). Preço: R$ 0,0002 por texto. Paga do saldo em reais da organização (Pix no painel, pacotes de R$ 10,00 a R$ 100,00) ou por x402 com `X-PAYMENT` (USDC na Base, mínimo de US$ 0,001 por chamada), também sem chave: a carteira que paga vira a conta. O débito volta ao saldo de quem pagou se o job falhar, for cancelado ou vencer na fila.

- **URL:** `https://inferencia.sistemaaguia.com/v1/embeddings`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

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

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

**Resposta `200`**

- `data` (object[]) — Vetores na ordem dos textos, no formato da OpenAI.
- `job` (object) — Recibo com id e result_url para recuperar o resultado sem nova cobrança.
- `model` (string) — O modelo da rota.

**Erros**

- `401` — Chave de API ausente ou inválida (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem saldo que cubra a chamada nem pagamento x402: o corpo traz o `accepts` do x402, o `preco_brl` e, com a chave, o `buy_credit_url`.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis (`capability_unavailable`: nenhum worker atende a capacidade agora; nada foi cobrado).

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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`). Preço: R$ 0,02 por mil caracteres (ou fração). Paga do saldo em reais da organização (Pix no painel, pacotes de R$ 10,00 a R$ 100,00) ou por x402 com `X-PAYMENT` (USDC na Base, mínimo de US$ 0,001 por chamada), também sem chave: a carteira que paga vira a conta. O débito volta ao saldo de quem pagou se o job falhar, for cancelado ou vencer na fila.

- **URL:** `https://inferencia.sistemaaguia.com/v1/audio/speech`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem saldo que cubra a chamada nem pagamento x402: o corpo traz o `accepts` do x402, o `preco_brl` e, com a chave, o `buy_credit_url`.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis (`capability_unavailable`: nenhum worker atende a capacidade agora; nada foi cobrado).

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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`). Preço: R$ 0,10 por minuto de música. Paga do saldo em reais da organização (Pix no painel, pacotes de R$ 10,00 a R$ 100,00) ou por x402 com `X-PAYMENT` (USDC na Base, mínimo de US$ 0,001 por chamada), também sem chave: a carteira que paga vira a conta. O débito volta ao saldo de quem pagou se o job falhar, for cancelado ou vencer na fila.

- **URL:** `https://inferencia.sistemaaguia.com/v1/audio/music`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem saldo que cubra a chamada nem pagamento x402: o corpo traz o `accepts` do x402, o `preco_brl` e, com a chave, o `buy_credit_url`.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis (`capability_unavailable`: nenhum worker atende a capacidade agora; nada foi cobrado).

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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`). Preço: R$ 0,01 por composição. Paga do saldo em reais da organização (Pix no painel, pacotes de R$ 10,00 a R$ 100,00) ou por x402 com `X-PAYMENT` (USDC na Base, mínimo de US$ 0,001 por chamada), também sem chave: a carteira que paga vira a conta. O débito volta ao saldo de quem pagou se o job falhar, for cancelado ou vencer na fila.

- **URL:** `https://inferencia.sistemaaguia.com/v1/audio/compositions`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem saldo que cubra a chamada nem pagamento x402: o corpo traz o `accepts` do x402, o `preco_brl` e, com a chave, o `buy_credit_url`.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis (`capability_unavailable`: nenhum worker atende a capacidade agora; nada foi cobrado).

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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`). Preço: R$ 0,10 por imagem. Paga do saldo em reais da organização (Pix no painel, pacotes de R$ 10,00 a R$ 100,00) ou por x402 com `X-PAYMENT` (USDC na Base, mínimo de US$ 0,001 por chamada), também sem chave: a carteira que paga vira a conta. O débito volta ao saldo de quem pagou se o job falhar, for cancelado ou vencer na fila.

- **URL:** `https://inferencia.sistemaaguia.com/v1/images/generations`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem saldo que cubra a chamada nem pagamento x402: o corpo traz o `accepts` do x402, o `preco_brl` e, com a chave, o `buy_credit_url`.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis (`capability_unavailable`: nenhum worker atende a capacidade agora; nada foi cobrado).

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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`). Preço: R$ 0,10 por imagem. Paga do saldo em reais da organização (Pix no painel, pacotes de R$ 10,00 a R$ 100,00) ou por x402 com `X-PAYMENT` (USDC na Base, mínimo de US$ 0,001 por chamada), também sem chave: a carteira que paga vira a conta. O débito volta ao saldo de quem pagou se o job falhar, for cancelado ou vencer na fila.

- **URL:** `https://inferencia.sistemaaguia.com/v1/images/edits`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem saldo que cubra a chamada nem pagamento x402: o corpo traz o `accepts` do x402, o `preco_brl` e, com a chave, o `buy_credit_url`.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis (`capability_unavailable`: nenhum worker atende a capacidade agora; nada foi cobrado).

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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`). Preço: R$ 0,01 por página lida. Paga do saldo em reais da organização (Pix no painel, pacotes de R$ 10,00 a R$ 100,00) ou por x402 com `X-PAYMENT` (USDC na Base, mínimo de US$ 0,001 por chamada), também sem chave: a carteira que paga vira a conta. O débito volta ao saldo de quem pagou se o job falhar, for cancelado ou vencer na fila.

- **URL:** `https://inferencia.sistemaaguia.com/v1/ocr`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

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

- `file` (file) — A imagem ou o PDF (multipart).
- `max_pages` (number) — O máximo de páginas do PDF a ler, de 1 a 40 (padrão 40). A cobrança reserva esse máximo e devolve as páginas não lidas; no x402, paga-se o máximo.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem saldo que cubra a chamada nem pagamento x402: o corpo traz o `accepts` do x402, o `preco_brl` e, com a chave, o `buy_credit_url`.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis (`capability_unavailable`: nenhum worker atende a capacidade agora; nada foi cobrado).

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/v1/ocr -H "Authorization: Bearer $ROTA_API_KEY" -F file=@documento.pdf -F max_pages=5
```

### `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`). Preço: R$ 0,01 por página lida. Paga do saldo em reais da organização (Pix no painel, pacotes de R$ 10,00 a R$ 100,00) ou por x402 com `X-PAYMENT` (USDC na Base, mínimo de US$ 0,001 por chamada), também sem chave: a carteira que paga vira a conta. O débito volta ao saldo de quem pagou se o job falhar, for cancelado ou vencer na fila.

- **URL:** `https://inferencia.sistemaaguia.com/v1/documents/fidelity/jobs`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem saldo que cubra a chamada nem pagamento x402: o corpo traz o `accepts` do x402, o `preco_brl` e, com a chave, o `buy_credit_url`.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis (`capability_unavailable`: nenhum worker atende a capacidade agora; nada foi cobrado).

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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`). Preço: R$ 0,05 por página. Paga do saldo em reais da organização (Pix no painel, pacotes de R$ 10,00 a R$ 100,00) ou por x402 com `X-PAYMENT` (USDC na Base, mínimo de US$ 0,001 por chamada), também sem chave: a carteira que paga vira a conta. O débito volta ao saldo de quem pagou se o job falhar, for cancelado ou vencer na fila.

- **URL:** `https://inferencia.sistemaaguia.com/v1/documents/review/jobs`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

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

- `markdown` (string) — O documento em Markdown, de 1 a 2.000.000 caracteres.
- `instructions` (string) — Instruções da revisão, de 1 a 20.000 caracteres.
- `schema` (object) — O esquema JSON do resultado esperado.
- `pages` (object[]) — De 1 a 40 páginas. Cada uma contém page (inteiro positivo), mime (image/…) e dataBase64 (imagem em base64).

**Resposta `202`**

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

**Erros**

- `400` — Formato inválido (`invalid_input`): nada é cobrado nem enviado à fila.
- `401` — Chave de API ausente ou inválida (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem saldo que cubra a chamada nem pagamento x402: o corpo traz o `accepts` do x402, o `preco_brl` e, com a chave, o `buy_credit_url`.
- `413` — Entrada acima do limite.
- `503` — Workers indisponíveis (`capability_unavailable`: nenhum worker atende a capacidade agora; nada foi cobrado).

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/v1/documents/review/jobs -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' --data-binary @revisao.json
```

### `POST /v1/moderations`

Moderação de mensagens pela política da organização, no formato da OpenAI (espera até 30 s; senão, 202 com o job).

Prévia (`rn.*`): o contrato pode mudar e depende de worker ligado (veja `GET /v1/capabilities`). Preço: R$ 0,002 por mensagem. Paga do saldo em reais da organização (Pix no painel, pacotes de R$ 10,00 a R$ 100,00) ou por x402 com `X-PAYMENT` (USDC na Base, mínimo de US$ 0,001 por chamada), também sem chave: a carteira que paga vira a conta. O débito volta ao saldo de quem pagou se o job falhar, for cancelado ou vencer na fila.

- **URL:** `https://inferencia.sistemaaguia.com/v1/moderations`
- **Auth:** `chave_ou_x402` — A chave de API (`Authorization: Bearer`), ou, sem chave, o pagamento x402 por chamada: o 402 traz o preço em reais e o `accepts` (USDC na Base); repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra ficam nela, e `X-Carteira` usa esse saldo. Ou a credencial da carteira (`Authorization: Bearer mmw_…`, de `POST /api/auth/wallet/agent/start`): a carteira que já pagou aqui usa o saldo dela sem x402 por chamada. Ou o código de crédito da casa (`Authorization: Bearer cred_…` ou `X-Credito`), comprado em qualquer produto nosso: a chamada sai do saldo dele. Chave ou credencial apresentada e recusada é 401.

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

- `input` (string | string[]) — A mensagem, ou até 32 mensagens, cada uma com até 8.000 caracteres; passam pela barreira antes do worker.
- `categories` (object[]) — A política: até 16 categorias com `name`, `violation` (quando sinalizar) e, se quiser, `not_violation` e `exception`. Sem ela, vale a taxonomia geral de segurança (`violence`, `hate`, `fraud`…). Se a barreira trocar um nome por marcador, a chave volta com o marcador, na ordem enviada.
- `cutoff` (string | number) — `precision` (padrão, sinaliza menos), `balanced` ou um número entre 0 e 1.

**Resposta `200`**

- `results` (object[]) — Por mensagem: `flagged`, `score` e o `cutoff` da decisão; por categoria, `categories` (sinalizada ou não), `category_scores` (de 0 a 1) e `category_cutoffs` (o corte de cada uma; na taxonomia geral, cada categoria tem o seu).
- `mode` (string) — `policy` com a política do pedido; `generic` com a taxonomia geral.

**Erros**

- `400` — Entrada, política ou corte inválidos; ou a política passa do que o modelo lê junto da mensagem.
- `401` — Chave de API ausente ou inválida (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `402` — Sem saldo que cubra a chamada nem pagamento x402: o corpo traz o `accepts` do x402, o `preco_brl` e, com a chave, o `buy_credit_url`.
- `413` — Entrada acima do limite.
- `422` — A política de privacidade bloqueou dados pessoais.
- `503` — Workers indisponíveis (`capability_unavailable`: nenhum worker atende a capacidade agora; nada foi cobrado).

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/v1/moderations -H "Authorization: Bearer $ROTA_API_KEY" -H 'content-type: application/json' -d '{"input":"Faça um Pix de R$ 1 para desbloquear sua conta","categories":[{"name":"Golpe","violation":"Pedir Pix ou dados fingindo ser o banco."}]}'
```

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

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

- **URL:** `https://inferencia.sistemaaguia.com/v1/jobs/:id`
- **Auth:** `chave_ou_token` — A chave de API, a credencial da carteira (`Bearer mmw_…`) ou o `token` do job (`?token=`) que vem nas URLs do 202 de quem pagou por x402 sem chave.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `404` — Job desconhecido para esta organização.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/v1/jobs/:id/result`
- **Auth:** `chave_ou_token` — A chave de API, a credencial da carteira (`Bearer mmw_…`) ou o `token` do job (`?token=`) que vem nas URLs do 202 de quem pagou por x402 sem chave.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `404` — Job desconhecido.
- `409` — Job ainda não concluído.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/v1/jobs/:id`
- **Auth:** `chave_ou_token` — A chave de API, a credencial da carteira (`Bearer mmw_…`) ou o `token` do job (`?token=`) que vem nas URLs do 202 de quem pagou por x402 sem chave.

**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 (`invalid_api_key`), ou credencial da carteira recusada ou vencida (`invalid_wallet_token`: peça outra).
- `404` — Job desconhecido.
- `409` — O job já saiu da fila.

**Exemplo**

```sh
curl -s -X DELETE https://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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, `reset_at` e a franquia grátis do dia (`free_tier`, como em `/api/app/quota`).
- `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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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`. `free_tier`: a franquia grátis do dia (`model`, `daily_request_limit`, `daily_token_limit`, `requests_today`, `tokens_today` e `resets_at`), ou `null` quando ela está desligada.

**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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/app/uso?limit=50").then(r => r.json());
```

### `POST /api/app/playground`

Experimenta um modelo pela sessão do painel, com a política, a cota e a cobrança da organização.

Até 4.000 caracteres e 512 tokens de saída. A comparação na tela faz duas chamadas separadas. Não precisa expor uma chave no navegador.

- **URL:** `https://inferencia.sistemaaguia.com/api/app/playground`
- **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` (string, obrigatório) — Um modelo público rota/*.
- `prompt` (string, obrigatório) — Pedido de 1 a 4.000 caracteres.
- `max_tokens` (number) — De 1 a 512; padrão 256.
- `temperature` (number) — De 0 a 2; padrão 0,7.

**Resposta `200`**

- `choices` (object[]) — Resposta no formato de chat compatível.
- `usage` (object) — Tokens informados pelo provedor.

**Erros**

- `400` — Modelo, pedido ou parâmetro inválido.
- `401` — Sem sessão da conta.
- `402` — Falta saldo ou o modelo exige crédito.
- `403` — Sem o aceite dos Termos e da retenção legal (`terms_required`).
- `404` — Organização desconhecida para esta conta.
- `422` — Política de privacidade bloqueou o pedido.
- `429` — Cota ou limite por minuto.
- `503` — Nenhuma conexão disponível.

**Exemplo**

```js
await MMConta.fetch("https://inferencia.sistemaaguia.com/api/app/playground", {method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify({model: "rota/rapido", prompt: "Explique a fotossíntese em duas frases.", max_tokens: 128})});
```

### `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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/app/modelos", {method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify({model_id: "rota/rapido", enabled: false})});
```

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

O saldo de crédito em reais da organização aberta (ou da conta) e as últimas compras. A compra usa o pagamento da casa (`POST /api/credito/asaas`).

- **URL:** `https://inferencia.sistemaaguia.com/api/credito/asaas/saldo`
- **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`**

- `moeda` (string) — Sempre `BRL`.
- `centavos` (number) — O saldo em centavos de real.
- `pode_comprar` (bool) — Se quem pede compra (na organização, só o dono ou um administrador).
- `compras` (object[]) — As últimas 20 compras: `estado` (`pago`, `pendente`, `vencido`, `estornado`), `centavos` e as datas.

**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://inferencia.sistemaaguia.com/api/credito/asaas/saldo").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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/app/privacy/clean", {method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify({text: "Contato: teste@example.com"})});
```

### `GET /api/app/lab/estado`

O laboratório numa resposta: o acesso e cada ferramenta com o estado, o uso da organização em 24 h, o teto e a fila.

- **URL:** `https://inferencia.sistemaaguia.com/api/app/lab/estado`
- **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) — `status` do acesso à API, `reason` e o fim do teste (`trial_expires_at`).
- `tools` (object[]) — `id`, `capability` (`rn.*`), `status` (`live`, `offline` ou `soon`), `daily_limit`, `used_24h` e `queued`.

**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://inferencia.sistemaaguia.com/api/app/lab/estado").then(r => r.json());
```

### `POST /api/app/lab/:ferramenta`

Executa uma ferramenta pela rota da API dela, com a barreira, a fila e a auditoria, e os tetos do laboratório.

JSON: `chat` (`messages`, até 12, de até 4.000 caracteres), `voz` (`text`, até 500), `musica` (`style`, até 300; 60 s). Multipart: `transcricao` (`file` de áudio e `language` pt, en ou es), `mixagem` (`voice` e `background`, até 6 MB cada), `leitura` e `leitura-fiel` (`file` PDF ou imagem, até 8 MB). A rota espera o worker até 15 s; depois, devolve o job para acompanhar. `revisao`, `imagem` e `busca` respondem 409 até chegarem.

- **URL:** `https://inferencia.sistemaaguia.com/api/app/lab/:ferramenta`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Parâmetros de caminho**

- `ferramenta` (string, obrigatório) — `chat`, `transcricao`, `voz`, `musica`, `mixagem`, `leitura` ou `leitura-fiel`. Ex.: `voz`.

**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`**

- `job` (object) — `id`, `status`, `progress_pct`, `stage` e `error`, quando a ferramenta roda na fila.
- `poll_url` (string) — Onde acompanhar o job.
- `result_url` (string) — Onde baixar o resultado, com o job concluído.
- `result` (object) — O resultado JSON, quando o worker termina na espera da rota.
- `text` (string) — O texto da resposta (chat), já com os marcadores da barreira.
- `received` (string) — No chat, a última mensagem como a IA a recebeu, depois da barreira.

**Erros**

- `400` — Entrada fora do formato ou dos limites (`lab_*`).
- `401` — Sem sessão da conta.
- `403` — Acesso à API não liberado, ou falta o aceite.
- `404` — Organização desconhecida para esta conta.
- `409` — Ferramenta em breve (`lab_tool_soon`).
- `413` — Arquivo acima do limite (`lab_file_too_large`).
- `415` — Tipo de arquivo não aceito (`lab_file_type`).
- `429` — Teto de 24 h da ferramenta (`lab_daily_limit`), limite por minuto ou cota do mês.
- `503` — Ferramenta indisponível (`lab_tool_offline`), fila cheia (`lab_queue_full`) ou envios demais (`lab_busy`).

**Exemplo**

```js
await MMConta.fetch("https://inferencia.sistemaaguia.com/api/app/lab/voz", {method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify({text: "Olá! Este áudio foi gerado agora."})});
```

### `GET /api/app/lab/jobs/:id`

O estado de um job do laboratório, com espera longa: responde quando ele sai do estado `desde`, ou em 15 s.

- **URL:** `https://inferencia.sistemaaguia.com/api/app/lab/jobs/:id`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Parâmetros de caminho**

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

**Query**

- `desde` (string) — O `mark` da resposta anterior; vazio responde na hora. Ex.: `queued::`.

**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`**

- `job` (object) — O job: `status`, `progress_pct` e `stage`.
- `mark` (string) — A marca do estado, para o próximo `desde`.
- `result_url` (string) — Onde baixar o resultado, com o job concluído.

**Erros**

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

**Exemplo**

```js
await MMConta.fetch("https://inferencia.sistemaaguia.com/api/app/lab/jobs/rnj_0123456789abcdef0123456789abcdef?desde=").then(r => r.json());
```

### `GET /api/app/lab/jobs/:id/result`

O resultado do job concluído: o arquivo (o áudio gerado) ou o JSON, sem os dados pessoais.

- **URL:** `https://inferencia.sistemaaguia.com/api/app/lab/jobs/:id/result`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Parâmetros de caminho**

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

**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`**

- `job` (object) — O job concluído, quando o resultado é JSON.
- `result` (object) — O resultado em JSON (texto, páginas ou campos), já sem os dados pessoais; áudio vem como o próprio arquivo.

**Erros**

- `401` — Sem sessão da conta.
- `403` — Sem o aceite dos Termos e da retenção legal (`terms_required`).
- `404` — Job desconhecido para esta organização.
- `409` — O job ainda não terminou.

**Exemplo**

```js
await MMConta.fetch("https://inferencia.sistemaaguia.com/api/app/lab/jobs/rnj_0123456789abcdef0123456789abcdef/result").then(r => r.json());
```

### `DELETE /api/app/lab/jobs/:id`

Cancela um job do laboratório que ainda está na fila.

- **URL:** `https://inferencia.sistemaaguia.com/api/app/lab/jobs/:id`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Parâmetros de caminho**

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

**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`**

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

**Erros**

- `401` — Sem sessão da conta.
- `403` — Sem o aceite dos Termos e da retenção legal (`terms_required`).
- `404` — Job desconhecido para esta organização.
- `409` — O job já saiu da fila (`rn_job_not_cancellable`).

**Exemplo**

```js
await MMConta.fetch("https://inferencia.sistemaaguia.com/api/app/lab/jobs/rnj_0123456789abcdef0123456789abcdef", {method: "DELETE", headers: {"content-type": "application/json"}, body: JSON.stringify({})});
```

## Bots

### `GET /api/app/bots`

Consulta bots, conversas e memória da organização aberta.

Exige sessão. Até 20 mensagens por bot. Sem gravação, o conteúdo vive em RAM por 30 minutos após a última alteração ou até reiniciar. Com gravação, a cópia é cifrada, retém mensagens por até 30 dias e expira após 30 dias sem alteração. Não é uma implementação A2A ou ACP.

- **URL:** `https://inferencia.sistemaaguia.com/api/app/bots`
- **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`**

- `bots` (object[]) — Até quatro bots: id, nome, instrucao, modelo, mensagens e tarefa.
- `memoria` (string) — Notas comuns enviadas como dados a cada bot, até 4.000 caracteres.
- `gravar` (bool) — Escolha de persistência desta organização; padrão false.
- `integracoes` (bool) — Acesso externo por chave da organização, autorizado no app. Padrão false.
- `administra` (bool) — A sessão pode editar bots, memória e gravação.
- `versao` (number) — Versão crescente. Ignore respostas anteriores à versão já recebida.

**Erros**

- `400` — Entrada inválida.
- `401` — Sem sessão da conta.
- `403` — Sem aceite ou sem papel de administrador para configurar.
- `404` — Organização desconhecida para esta conta.
- `409` — Uma tarefa já está em andamento ou outra alteração ocupa o espaço.
- `413` — Corpo ou histórico acima do limite.
- `429` — Limite por minuto ou cota de inferência.
- `503` — Capacidade, banco ou chave de cifra indisponível.

**Exemplo**

```js
await MMConta.fetch("https://inferencia.sistemaaguia.com/api/app/bots").then(r => r.json());
```

### `PATCH /api/app/bots`

Edita bots, memória, gravação ou acesso externo.

Só dono ou administrador da organização. Apenas a permissão de conexão pode mudar com tarefa em curso. Gravação também controla a captura de auditoria destas chamadas. Desligar a gravação remove a cópia salva do módulo; não expurga auditorias anteriores. A política das outras rotas /v1/* não muda.

- **URL:** `https://inferencia.sistemaaguia.com/api/app/bots`
- **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`)

- `acao` (string, obrigatório) — bot, remover, memoria, gravacao ou integracoes.
- `ativo` (bool) — Em integracoes: permite acesso às conversas pelas chaves desta organização.
- `id` (string) — Em bot: id existente para editar; omita para criar, até quatro. Em remover: id do bot a excluir, exceto o último do espaço.
- `nome` (string) — Em bot: nome de 1 a 60 caracteres.
- `instrucao` (string) — Em bot: instruções de 1 a 2.000 caracteres.
- `modelo` (string) — Em bot: id rota/*, exceto rota/local nesta versão.
- `texto` (string) — Em memoria: até 4.000 caracteres; vazio apaga as notas.
- `gravar` (bool) — Em gravacao: true salva cifrado, false mantém somente em RAM.

**Resposta `200`**

- `bots` (object[]) — Até quatro bots: id, nome, instrucao, modelo, mensagens e tarefa.
- `memoria` (string) — Notas comuns enviadas como dados a cada bot, até 4.000 caracteres.
- `gravar` (bool) — Escolha de persistência desta organização; padrão false.
- `integracoes` (bool) — Acesso externo por chave da organização, autorizado no app. Padrão false.
- `administra` (bool) — A sessão pode editar bots, memória e gravação.
- `versao` (number) — Versão crescente. Ignore respostas anteriores à versão já recebida.

**Erros**

- `400` — Entrada inválida.
- `401` — Sem sessão da conta.
- `403` — Sem aceite ou sem papel de administrador para configurar.
- `404` — Organização desconhecida para esta conta.
- `409` — Uma tarefa já está em andamento ou outra alteração ocupa o espaço.
- `413` — Corpo ou histórico acima do limite.
- `429` — Limite por minuto ou cota de inferência.
- `503` — Capacidade, banco ou chave de cifra indisponível.

**Exemplo**

```js
await MMConta.fetch("https://inferencia.sistemaaguia.com/api/app/bots", {method: "PATCH", headers: {"content-type": "application/json"}, body: JSON.stringify({acao: "memoria", texto: "Responda em português."})});
```

### `POST /api/app/bots/mensagens`

Envia uma mensagem ou encaminha a última resposta de outro bot.

Responde 202 com a tarefa em andamento. A inferência usa a política, os limites e o crédito da organização. Até 1.024 tokens de saída, 150 segundos e uma tarefa por organização. Erro da inferência aparece em tarefa.erro. O id evita nova execução enquanto a mensagem estiver no histórico; não há retry automático.

- **URL:** `https://inferencia.sistemaaguia.com/api/app/bots/mensagens`
- **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`)

- `id` (string, obrigatório) — UUID da ação. Preserve ao repetir após falha de rede.
- `bot` (string, obrigatório) — Id do bot de destino.
- `texto` (string, obrigatório) — Pedido de 1 a 4.000 caracteres.
- `origem` (string) — Id de outro bot. Anexa sua última resposta ao pedido.

**Resposta `200`**

- `bots` (object[]) — Até quatro bots: id, nome, instrucao, modelo, mensagens e tarefa.
- `memoria` (string) — Notas comuns enviadas como dados a cada bot, até 4.000 caracteres.
- `gravar` (bool) — Escolha de persistência desta organização; padrão false.
- `integracoes` (bool) — Acesso externo por chave da organização, autorizado no app. Padrão false.
- `administra` (bool) — A sessão pode editar bots, memória e gravação.
- `versao` (number) — Versão crescente. Ignore respostas anteriores à versão já recebida.

**Erros**

- `400` — Entrada inválida.
- `401` — Sem sessão da conta.
- `403` — Sem aceite ou sem papel de administrador para configurar.
- `404` — Organização desconhecida para esta conta.
- `409` — Uma tarefa já está em andamento ou outra alteração ocupa o espaço.
- `413` — Corpo ou histórico acima do limite.
- `429` — Limite por minuto ou cota de inferência.
- `503` — Capacidade, banco ou chave de cifra indisponível.

**Exemplo**

```js
await MMConta.fetch("https://inferencia.sistemaaguia.com/api/app/bots/mensagens", {method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify({id: crypto.randomUUID(), bot: "assistente", texto: "Planeje as tarefas de hoje."})});
```

### `POST /api/app/bots/cancelar`

Interrompe a tarefa do bot da organização.

Marca a tarefa como cancelada e pede cancelamento ao motor. Uma resposta tardia não entra no histórico. Trabalho que o provedor já processou pode ter custo.

- **URL:** `https://inferencia.sistemaaguia.com/api/app/bots/cancelar`
- **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`)

- `bot` (string, obrigatório) — Id do bot cuja tarefa será interrompida.

**Resposta `200`**

- `bots` (object[]) — Até quatro bots: id, nome, instrucao, modelo, mensagens e tarefa.
- `memoria` (string) — Notas comuns enviadas como dados a cada bot, até 4.000 caracteres.
- `gravar` (bool) — Escolha de persistência desta organização; padrão false.
- `integracoes` (bool) — Acesso externo por chave da organização, autorizado no app. Padrão false.
- `administra` (bool) — A sessão pode editar bots, memória e gravação.
- `versao` (number) — Versão crescente. Ignore respostas anteriores à versão já recebida.

**Erros**

- `400` — Entrada inválida.
- `401` — Sem sessão da conta.
- `403` — Sem aceite ou sem papel de administrador para configurar.
- `404` — Organização desconhecida para esta conta.
- `409` — Uma tarefa já está em andamento ou outra alteração ocupa o espaço.
- `413` — Corpo ou histórico acima do limite.
- `429` — Limite por minuto ou cota de inferência.
- `503` — Capacidade, banco ou chave de cifra indisponível.

**Exemplo**

```js
await MMConta.fetch("https://inferencia.sistemaaguia.com/api/app/bots/cancelar", {method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify({bot: "assistente"})});
```

### `GET /api/app/bots/eventos`

Acompanha o estado dos bots por eventos do servidor.

text/event-stream. Cada data contém o mesmo objeto do GET /api/app/bots. A conexão dura até 25 segundos; reconecte para conferir sessão e organização. Até quatro conexões por organização e 64 por processo. Sem broker externo.

- **URL:** `https://inferencia.sistemaaguia.com/api/app/bots/eventos`
- **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`**

- `bots` (object[]) — Até quatro bots: id, nome, instrucao, modelo, mensagens e tarefa.
- `memoria` (string) — Notas comuns enviadas como dados a cada bot, até 4.000 caracteres.
- `gravar` (bool) — Escolha de persistência desta organização; padrão false.
- `integracoes` (bool) — Acesso externo por chave da organização, autorizado no app. Padrão false.
- `administra` (bool) — A sessão pode editar bots, memória e gravação.
- `versao` (number) — Versão crescente. Ignore respostas anteriores à versão já recebida.

**Erros**

- `400` — Entrada inválida.
- `401` — Sem sessão da conta.
- `403` — Sem aceite ou sem papel de administrador para configurar.
- `404` — Organização desconhecida para esta conta.
- `409` — Uma tarefa já está em andamento ou outra alteração ocupa o espaço.
- `413` — Corpo ou histórico acima do limite.
- `429` — Limite por minuto ou cota de inferência.
- `503` — Capacidade, banco ou chave de cifra indisponível.

**Exemplo**

```js
await MMConta.fetch("https://inferencia.sistemaaguia.com/api/app/bots/eventos");
```

### `GET /v1/bots`

Consulta pela chave os bots, as conversas e a memória da organização.

Chave da conta ou organização, com conexão externa autorizada em Bots. Consulta o mesmo espaço do app. Sem autorização, 403 bots_external_disabled.

- **URL:** `https://inferencia.sistemaaguia.com/v1/bots`
- **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`**

- `bots` (object[]) — Até quatro bots: id, nome, instrucao, modelo, mensagens e tarefa.
- `memoria` (string) — Notas comuns enviadas como dados a cada bot, até 4.000 caracteres.
- `gravar` (bool) — Escolha de persistência desta organização; padrão false.
- `integracoes` (bool) — Acesso externo por chave da organização, autorizado no app. Padrão false.
- `administra` (bool) — A sessão pode editar bots, memória e gravação.
- `versao` (number) — Versão crescente. Ignore respostas anteriores à versão já recebida.

**Erros**

- `400` — Entrada inválida.
- `401` — Sem sessão da conta.
- `403` — Sem aceite ou sem papel de administrador para configurar.
- `404` — Organização desconhecida para esta conta.
- `409` — Uma tarefa já está em andamento ou outra alteração ocupa o espaço.
- `413` — Corpo ou histórico acima do limite.
- `429` — Limite por minuto ou cota de inferência.
- `503` — Capacidade, banco ou chave de cifra indisponível.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/v1/bots -H "Authorization: Bearer $ROTA_API_KEY"
```

### `POST /v1/bots/mensagens`

Envia pela chave um pedido a um bot ou encaminha a última resposta de outro.

Chave da conta ou organização, com conexão externa autorizada em Bots. Responde 202 com a tarefa em andamento. A inferência usa a política, os limites e o crédito da organização. Até 1.024 tokens de saída, 150 segundos e uma tarefa por organização. Erro da inferência aparece em tarefa.erro. O id evita nova execução enquanto a mensagem estiver no histórico; não há retry automático.

- **URL:** `https://inferencia.sistemaaguia.com/v1/bots/mensagens`
- **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`)

- `id` (string, obrigatório) — UUID da ação. Preserve ao repetir após falha de rede.
- `bot` (string, obrigatório) — Id do bot de destino.
- `texto` (string, obrigatório) — Pedido de 1 a 4.000 caracteres.
- `origem` (string) — Id de outro bot. Anexa sua última resposta ao pedido.

**Resposta `200`**

- `bots` (object[]) — Até quatro bots: id, nome, instrucao, modelo, mensagens e tarefa.
- `memoria` (string) — Notas comuns enviadas como dados a cada bot, até 4.000 caracteres.
- `gravar` (bool) — Escolha de persistência desta organização; padrão false.
- `integracoes` (bool) — Acesso externo por chave da organização, autorizado no app. Padrão false.
- `administra` (bool) — A sessão pode editar bots, memória e gravação.
- `versao` (number) — Versão crescente. Ignore respostas anteriores à versão já recebida.

**Erros**

- `400` — Entrada inválida.
- `401` — Sem sessão da conta.
- `403` — Sem aceite ou sem papel de administrador para configurar.
- `404` — Organização desconhecida para esta conta.
- `409` — Uma tarefa já está em andamento ou outra alteração ocupa o espaço.
- `413` — Corpo ou histórico acima do limite.
- `429` — Limite por minuto ou cota de inferência.
- `503` — Capacidade, banco ou chave de cifra indisponível.

**Exemplo**

```sh
curl -s -X POST https://inferencia.sistemaaguia.com/v1/bots/mensagens -H "Authorization: Bearer $ROTA_API_KEY" -H "Content-Type: application/json" -d '{"id":"0f8c1e2a-5b7d-4c3e-9a1b-2d4e6f8a0b1c","bot":"assistente","texto":"Planeje as tarefas de hoje."}'
```

### `POST /v1/bots/cancelar`

Interrompe pela chave a tarefa em andamento de um bot.

Chave da conta ou organização, com conexão externa autorizada em Bots. Marca a tarefa como cancelada e pede cancelamento ao motor. Uma resposta tardia não entra no histórico. Trabalho que o provedor já processou pode ter custo.

- **URL:** `https://inferencia.sistemaaguia.com/v1/bots/cancelar`
- **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`)

- `bot` (string, obrigatório) — Id do bot cuja tarefa será interrompida.

**Resposta `200`**

- `bots` (object[]) — Até quatro bots: id, nome, instrucao, modelo, mensagens e tarefa.
- `memoria` (string) — Notas comuns enviadas como dados a cada bot, até 4.000 caracteres.
- `gravar` (bool) — Escolha de persistência desta organização; padrão false.
- `integracoes` (bool) — Acesso externo por chave da organização, autorizado no app. Padrão false.
- `administra` (bool) — A sessão pode editar bots, memória e gravação.
- `versao` (number) — Versão crescente. Ignore respostas anteriores à versão já recebida.

**Erros**

- `400` — Entrada inválida.
- `401` — Sem sessão da conta.
- `403` — Sem aceite ou sem papel de administrador para configurar.
- `404` — Organização desconhecida para esta conta.
- `409` — Uma tarefa já está em andamento ou outra alteração ocupa o espaço.
- `413` — Corpo ou histórico acima do limite.
- `429` — Limite por minuto ou cota de inferência.
- `503` — Capacidade, banco ou chave de cifra indisponível.

**Exemplo**

```sh
curl -s -X POST https://inferencia.sistemaaguia.com/v1/bots/cancelar -H "Authorization: Bearer $ROTA_API_KEY" -H "Content-Type: application/json" -d '{"bot":"assistente"}'
```

### `PATCH /v1/bots/memoria`

Atualiza a memória compartilhada pelo agente externo.

Requer conexão autorizada. Envie a versao lida por consultar_bots; mudança concorrente retorna 409. Não muda a política de gravação.

- **URL:** `https://inferencia.sistemaaguia.com/v1/bots/memoria`
- **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`)

- `texto` (string, obrigatório) — Notas completas, até 4.000 caracteres.
- `versao` (number, obrigatório) — Versão lida antes da edição.

**Resposta `200`**

- `bots` (object[]) — Até quatro bots: id, nome, instrucao, modelo, mensagens e tarefa.
- `memoria` (string) — Notas comuns enviadas como dados a cada bot, até 4.000 caracteres.
- `gravar` (bool) — Escolha de persistência desta organização; padrão false.
- `integracoes` (bool) — Acesso externo por chave da organização, autorizado no app. Padrão false.
- `administra` (bool) — A sessão pode editar bots, memória e gravação.
- `versao` (number) — Versão crescente. Ignore respostas anteriores à versão já recebida.

**Erros**

- `400` — Entrada inválida.
- `401` — Sem sessão da conta.
- `403` — Sem aceite ou sem papel de administrador para configurar.
- `404` — Organização desconhecida para esta conta.
- `409` — Uma tarefa já está em andamento ou outra alteração ocupa o espaço.
- `413` — Corpo ou histórico acima do limite.
- `429` — Limite por minuto ou cota de inferência.
- `503` — Capacidade, banco ou chave de cifra indisponível.

**Exemplo**

```sh
curl -s -X PATCH https://inferencia.sistemaaguia.com/v1/bots/memoria -H "Authorization: Bearer $ROTA_API_KEY" -H "Content-Type: application/json" -d '{"texto":"Responda em português.","versao":3}'
```

### `POST /v1/bots/resultados`

Registra o resultado produzido por um agente externo na conversa.

Requer conexão autorizada. Texto aparece com origem MCP. UUID repetido com os mesmos dados não duplica; dados diferentes retornam 409. Não executa inferência.

- **URL:** `https://inferencia.sistemaaguia.com/v1/bots/resultados`
- **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`)

- `id` (string, obrigatório) — UUID da ação.
- `bot` (string, obrigatório) — Bot cuja conversa recebe o resultado.
- `texto` (string, obrigatório) — Resultado de 1 a 8.000 caracteres.

**Resposta `200`**

- `bots` (object[]) — Até quatro bots: id, nome, instrucao, modelo, mensagens e tarefa.
- `memoria` (string) — Notas comuns enviadas como dados a cada bot, até 4.000 caracteres.
- `gravar` (bool) — Escolha de persistência desta organização; padrão false.
- `integracoes` (bool) — Acesso externo por chave da organização, autorizado no app. Padrão false.
- `administra` (bool) — A sessão pode editar bots, memória e gravação.
- `versao` (number) — Versão crescente. Ignore respostas anteriores à versão já recebida.

**Erros**

- `400` — Entrada inválida.
- `401` — Sem sessão da conta.
- `403` — Sem aceite ou sem papel de administrador para configurar.
- `404` — Organização desconhecida para esta conta.
- `409` — Uma tarefa já está em andamento ou outra alteração ocupa o espaço.
- `413` — Corpo ou histórico acima do limite.
- `429` — Limite por minuto ou cota de inferência.
- `503` — Capacidade, banco ou chave de cifra indisponível.

**Exemplo**

```sh
curl -s -X POST https://inferencia.sistemaaguia.com/v1/bots/resultados -H "Authorization: Bearer $ROTA_API_KEY" -H "Content-Type: application/json" -d '{"id":"6a1d4c2e-8b3f-4e5a-9c7d-1f2e3a4b5c6d","bot":"assistente","texto":"Relatório pronto."}'
```

## 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://inferencia.sistemaaguia.com/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://inferencia.sistemaaguia.com/api/public/stats
```

## Pacote Pi

### `GET /api/slot`

A oferta da casa que o pacote Pi mostra durante o turno: o texto e o link que conta o clique.

- **URL:** `https://inferencia.sistemaaguia.com/api/slot`
- **Auth:** `none` — Público.

**Query**

- `lingua` (string) — `pt` (padrão) ou `en`.

**Resposta `200`**

- `id` (string) — A oferta: `pix` (crédito do RN por Pix) ou `hookpulse`.
- `texto` (string) — Uma frase, na língua pedida.
- `url` (string) — O link do clique (`/api/slot/ir/:oferta`), que leva ao destino da oferta.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/api/slot?lingua=pt
```

### `POST /api/slot/exibicao`

Conta uma exibição da oferta. Aceita só a oferta e um id; campo a mais é recusado.

- **URL:** `https://inferencia.sistemaaguia.com/api/slot/exibicao`
- **Auth:** `none` — Público.

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

- `oferta` (string, obrigatório) — O `id` que o `GET /api/slot` devolveu.
- `id` (string, obrigatório) — Um UUID por exibição: o mesmo id conta uma vez.

**Resposta `200`**

204 sem corpo.

**Erros**

- `400` — Corpo diferente de `{ oferta, id }`, oferta desconhecida ou id inválido.

**Exemplo**

```sh
curl -s -XPOST https://inferencia.sistemaaguia.com/api/slot/exibicao -H 'content-type: application/json' -d '{"oferta":"pix","id":"0b5e8f3e-1d2c-4a6b-9f7e-2c1d3b4a5e6f"}'
```

### `GET /api/slot/ir/:oferta`

Conta o clique e leva ao destino fixo da oferta (302).

- **URL:** `https://inferencia.sistemaaguia.com/api/slot/ir/:oferta`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

- `oferta` (string, obrigatório) — `pix` ou `hookpulse`.

**Query**

- `lingua` (string) — `pt` (padrão) ou `en`.

**Resposta `200`**

302 para o destino da oferta.

**Erros**

- `404` — Oferta desconhecida.

**Exemplo**

```sh
curl -sI https://inferencia.sistemaaguia.com/api/slot/ir/pix
```

## Radar

### `GET /api/radar`

Bookmarks atualizados diariamente, com notícias, fatos relevantes e fonte original.

Todo o histórico público dos bookmarks, inclusive os que renderam Guia. O modelo decide quando há orientação útil ao RN; segurança fica em Cyber. Navegue por page ou leia /pt/radar/feed.json e /pt/radar/feed.xml. Páginas `/pt/radar/` e `/en/radar/`.

- **URL:** `https://inferencia.sistemaaguia.com/api/radar`
- **Auth:** `none` — Público.

**Query**

- `page` (number) — A página, de 1 em diante. Vinte peças por página, até o fim do acervo.

**Resposta `200`**

- `total` (number) — Quantas peças a lista tem.
- `pagina` (number) — A página devolvida.
- `paginas` (number) — Quantas páginas existem.
- `itens` (object[]) — As peças desta página.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/api/radar
```

### `GET /api/cyber`

Notícias de segurança, advisories e assuntos relacionados.

Todo o histórico Cyber, sem notícias gerais da Inova e sem gerar Guias. Navegue por page ou leia /pt/cyber/feed.json e /pt/cyber/feed.xml. Páginas `/pt/cyber/` e `/en/cyber/`.

- **URL:** `https://inferencia.sistemaaguia.com/api/cyber`
- **Auth:** `none` — Público.

**Query**

- `page` (number) — A página, de 1 em diante. Vinte peças por página, até o fim do acervo.

**Resposta `200`**

- `total` (number) — Quantas peças a lista tem.
- `pagina` (number) — A página devolvida.
- `paginas` (number) — Quantas páginas existem.
- `itens` (object[]) — As peças desta página.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/api/cyber
```

### `GET /api/guias`

Guias práticos com passos, critérios de verificação e fontes.

Derivados somente dos bookmarks do Radar quando o modelo encontra uma tarefa útil ao usuário do RN. Tamanho sozinho não basta; Cyber e notícias gerais da Inova não geram Guias. Páginas `/pt/guias/<slug>/` e `/en/guides/<slug>/`.

- **URL:** `https://inferencia.sistemaaguia.com/api/guias`
- **Auth:** `none` — Público.

**Query**

- `page` (number) — A página, de 1 em diante. Vinte peças por página, até o fim do acervo.

**Resposta `200`**

- `total` (number) — Quantas peças a lista tem.
- `pagina` (number) — A página devolvida.
- `paginas` (number) — Quantas páginas existem.
- `itens` (object[]) — As peças desta página.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/api/guias
```

### `GET /api/radar/:slug`

Uma peça do radar, em português e inglês, com a fonte e o teste grátis.

- **URL:** `https://inferencia.sistemaaguia.com/api/radar/:slug`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

- `slug` (string, obrigatório) — O slug estável da peça.

**Resposta `200`**

- `slug` (string) — O endereço estável da peça.
- `fonte` (string) — `briefing` (bookmark do Radar) ou `cyber` (segurança).
- `guia` (bool) — `true` para um guia prático, com texto e endereço próprios.
- `imagem` (object) — Quando disponível: capa WebP, OG JPEG e texto alternativo em português e inglês.
- `pt` (object) — Título, resumo, corpo, como a Rota ajuda e como usar, em português, e a página.
- `en` (object) — The same fields in English, plus the page URL.
- `original` (object) — A fonte original: `url` e `titulo`.
- `teste` (object) — O teste grátis de 30 dias, em `/pt/app/experimentar/` e `/en/app/try/`.
- `acoes` (object) — Optional API documentation links in pt and en, or null per language. Each block has id, tipo, zero-based paragraph posicao, rotulo, titulo, condicao, acao and href. Opening a link does not execute or charge an API request.

**Erros**

- `404` — Slug não publicado.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/api/radar/prompt-em-log-aberto
```

## Conteúdo

### `GET /api/cyber/:slug`

Uma publicação de cyber, em português e inglês.

- **URL:** `https://inferencia.sistemaaguia.com/api/cyber/:slug`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

- `slug` (string, obrigatório) — Slug publicado nesta área.

**Resposta `200`**

- `slug` (string) — O endereço estável da peça.
- `fonte` (string) — `briefing` (bookmark do Radar) ou `cyber` (segurança).
- `guia` (bool) — `true` para um guia prático, com texto e endereço próprios.
- `imagem` (object) — Quando disponível: capa WebP, OG JPEG e texto alternativo em português e inglês.
- `pt` (object) — Título, resumo, corpo, como a Rota ajuda e como usar, em português, e a página.
- `en` (object) — The same fields in English, plus the page URL.
- `original` (object) — A fonte original: `url` e `titulo`.
- `teste` (object) — O teste grátis de 30 dias, em `/pt/app/experimentar/` e `/en/app/try/`.
- `acoes` (object) — Optional API documentation links in pt and en, or null per language. Each block has id, tipo, zero-based paragraph posicao, rotulo, titulo, condicao, acao and href. Opening a link does not execute or charge an API request.

**Erros**

- `404` — Slug não publicado nesta área.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/api/cyber/acesso-remoto-e-ia-reduza-o-d6ed11
```

### `GET /api/guias/:slug`

Uma publicação de guias, em português e inglês.

- **URL:** `https://inferencia.sistemaaguia.com/api/guias/:slug`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

- `slug` (string, obrigatório) — Slug publicado nesta área.

**Resposta `200`**

- `slug` (string) — O endereço estável da peça.
- `fonte` (string) — `briefing` (bookmark do Radar) ou `cyber` (segurança).
- `guia` (bool) — `true` para um guia prático, com texto e endereço próprios.
- `imagem` (object) — Quando disponível: capa WebP, OG JPEG e texto alternativo em português e inglês.
- `pt` (object) — Título, resumo, corpo, como a Rota ajuda e como usar, em português, e a página.
- `en` (object) — The same fields in English, plus the page URL.
- `original` (object) — A fonte original: `url` e `titulo`.
- `teste` (object) — O teste grátis de 30 dias, em `/pt/app/experimentar/` e `/en/app/try/`.
- `acoes` (object) — Optional API documentation links in pt and en, or null per language. Each block has id, tipo, zero-based paragraph posicao, rotulo, titulo, condicao, acao and href. Opening a link does not execute or charge an API request.

**Erros**

- `404` — Slug não publicado nesta área.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/api/guias/como-comparar-modelos-sem-expor-documentos-5e896a
```

### `GET /api/conteudo/novidades`

IDs e datas das publicações de Radar, Cyber e Guias.

O navegador compara com as peças já vistas, sem enviar o histórico de leitura ao servidor.

- **URL:** `https://inferencia.sistemaaguia.com/api/conteudo/novidades`
- **Auth:** `none` — Público.

**Resposta `200`**

- `areas` (object) — Por área: total e itens com id e publicado_em.

## Newsletter

### `GET /api/newsletter`

Preferências de newsletter da conta autenticada.

- **URL:** `https://inferencia.sistemaaguia.com/api/newsletter`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

- `ativo` (bool) — Consentimento ativo.
- `areas` (string[]) — radar, cyber e/ou guias.
- `idioma` (string) — pt ou en.
- `verificado` (bool) — A conta tem e-mail verificado.

**Erros**

- `401` — Entre na conta.
- `503` — Newsletter indisponível.

**Exemplo**

```sh
curl -s https://inferencia.sistemaaguia.com/api/newsletter -H "Cookie: $ROTA_COOKIE"
```

### `PUT /api/newsletter`

Salvar ou cancelar a newsletter, com consentimento explícito.

Exige mesma origem e CSRF do SDK. Nunca recebe ID de conta nem endereço de e-mail. Só ativa a assinatura com e-mail verificado.

- **URL:** `https://inferencia.sistemaaguia.com/api/newsletter`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

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

- `ativo` (bool, obrigatório) — true para assinar, false para cancelar.
- `areas` (string[], obrigatório) — radar, cyber e/ou guias.
- `idioma` (string, obrigatório) — Idioma do resumo: pt (português) ou en (inglês).
- `consentimento` (bool, obrigatório) — true somente quando a pessoa autorizou o recebimento.

**Exemplo de corpo**

```json
{
  "ativo": true,
  "areas": [
    "guias"
  ],
  "idioma": "pt",
  "consentimento": true
}
```

**Resposta `200`**

- `ok` (bool) — Preferências salvas.
- `ativo` (bool) — Assinatura ativa.
- `areas` (string[]) — Assuntos escolhidos.
- `idioma` (string) — pt ou en.

**Erros**

- `400` — Seleção inválida.
- `401` — Entre na conta.
- `403` — E-mail verificado ou CSRF exigido.
- `429` — Limite de alterações.
- `503` — Newsletter indisponível.

**Exemplo**

```sh
curl -s -X PUT https://inferencia.sistemaaguia.com/api/newsletter -H "Cookie: $ROTA_COOKIE" -H "Origin: https://inferencia.sistemaaguia.com" -H "x-csrf-token: $ROTA_CSRF" -H "content-type: application/json" -d '{"ativo":true,"areas":["guias"],"idioma":"pt","consentimento":true}'
```

### `POST /api/newsletter/cancelar`

Cancelar pelo token do link recebido no e-mail.

O token é uma autorização restrita de cancelamento. GET não cancela. A interface pede confirmação; clientes de e-mail usam List-Unsubscribe=One-Click.

- **URL:** `https://inferencia.sistemaaguia.com/api/newsletter/cancelar`
- **Auth:** `none` — Público.

**Query**

- `token` (string) — Alternativa ao corpo no POST one-click de e-mail.

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

- `token` (string, obrigatório) — Token de cancelamento do e-mail, 43 caracteres.

**Resposta `200`**

- `ok` (bool) — Assinatura cancelada.

**Erros**

- `400` — Token ou confirmação inválidos.
- `404` — Token desconhecido ou vencido.

**Exemplo**

```sh
curl -s -X POST "https://inferencia.sistemaaguia.com/api/newsletter/cancelar?token=$CANCELAR_TOKEN" -H "content-type: application/x-www-form-urlencoded" -d "List-Unsubscribe=One-Click"
```

## 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.
- `charged_now` (string[], opcional) — SKUs charged at their list price even when free_now has `*`.
- `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.
- `alternavel` (bool) — Dev only: a request with `X-MM-Pagamento: real` pays for real instead of in test mode.
- `gratis` (string[], opcional) — Temporarily free SKUs.
- `cobrados` (string[], opcional) — SKUs charged even when `gratis` has `*`.
- `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.