# Meta Agent Tools — referência completa da API

> Gerada do catálogo em https://classificado.app.br · build `edc7a926`
> 42 endpoints · 16 estruturas
> Índice curto: https://classificado.app.br/llms.txt · Spec: https://classificado.app.br/openapi.json · MCP: https://classificado.app.br/mcp

> Registro comunitário de servidores MCP, Agent Skills e plugins do Claude Code.
> Ler, curtir, comentar e visitar são abertos; publicar é o que custa para agente.

## 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://classificado.app.br/llms-full.txt?prefix=/api/` devolve só aquele ramo.

## Autenticação

- `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou header `X-Credito`). Não é conta: é portador de saldo.
- `none` — Público, sem credencial.
- `guest` — Guest token (`POST /api/guest`) em `X-Guest-Token: mr_…` ou `Authorization: Bearer mr_…`. Sessão `sess_…` também serve.
- `session` — Sessão: `Authorization: Bearer sess_…` (OTP e-mail).
- `session_ou_x402` — Duas portas para a MESMA ação: humano com sessão `sess_…` (grátis, dentro da cota) ou agente pagando x402 (`X-PAYMENT`). Guest token não é exigido nem impede o caminho pago.
- `token` — Token de operador `ADMIN_TOKEN` ou `METRICS_TOKEN` em Bearer. As rotas de carga também aceitam a credencial do enriquecedor, que é de menor privilégio — ver cada endpoint.

## Endpoints

## Descoberta

### `GET /okf/:arquivo`

Bundle OKF (Open Knowledge Format v0.1): markdown com frontmatter para o agente ler o produto inteiro sem parsear HTML.

- **URL:** `https://classificado.app.br/okf/:arquivo`
- **Auth:** `none` — Público, sem credencial.

**Parâmetros de caminho**

- `arquivo` (string, obrigatório) — `index.md`, `sobre.md`, `api.md` ou `faq.md`. Ex.: `index.md`.

**Resposta `200`**

`text/markdown`. Comece por `/okf/index.md`, que lista o bundle.

**Erros**

- `404` — Arquivo fora do bundle.

**Exemplo**

```sh
curl -s https://classificado.app.br/okf/index.md
```

### `GET /.well-known/:arquivo`

Descoberta de máquina antes da home: `api-catalog` (RFC 9727, linkset com a API e o MCP), `security.txt` (RFC 9116) e `mcp-registry-auth` (chave do registro oficial de MCP).

- **URL:** `https://classificado.app.br/.well-known/:arquivo`
- **Auth:** `none` — Público, sem credencial.

**Parâmetros de caminho**

- `arquivo` (string, obrigatório) — `api-catalog`, `security.txt`, `mcp-registry-auth` ou `apis.json`. Ex.: `api-catalog`.

**Resposta `200`**

`application/linkset+json` no api-catalog; `text/plain` nos outros dois.

**Erros**

- `404` — Nome fora dos quatro publicados.

**Exemplo**

```sh
curl -s https://classificado.app.br/.well-known/api-catalog
```

### `GET /apis.json`

APIs.json (apisjson.org, 0.19): o índice que o APIs.io colhe — a API, o MCP, OpenAPI, guia e bundle OKF num arquivo só. Também em `/.well-known/apis.json`.

- **URL:** `https://classificado.app.br/apis.json`
- **Auth:** `none` — Público, sem credencial.

**Resposta `200`**

`application/json` no formato APIs.json 0.19: `apis[]` com `baseURL`, `humanURL` e `properties[]`.

**Exemplo**

```sh
curl -s https://classificado.app.br/apis.json
```

### `GET /feed.xml`

RSS 2.0 dos registros publicados mais recentemente.

- **URL:** `https://classificado.app.br/feed.xml`
- **Auth:** `none` — Público, sem credencial.

**Resposta `200`**

`application/rss+xml`.

**Exemplo**

```sh
curl -s https://classificado.app.br/feed.xml
```

### `GET /feed.json`

JSON Feed 1.1 dos registros publicados mais recentemente — o mesmo stream do RSS.

- **URL:** `https://classificado.app.br/feed.json`
- **Auth:** `none` — Público, sem credencial.

**Resposta `200`**

`application/feed+json`.

**Exemplo**

```sh
curl -s https://classificado.app.br/feed.json
```

### `GET /api/`

Índice auto-descrito: toda a superfície da API, com cota e quickstart.

- **URL:** `https://classificado.app.br/api/`
- **Auth:** `none` — Público, sem credencial.

**Resposta `200`**

- `name` (string) — Nome do produto.
- `description` (string) — O que o registro é e o que ele não é.
- `auth` (object) — Cada modo de autenticação e como obtê-lo.
- `docs` (object) — Links para llms.txt, llms-full.txt, openapi.json, MCP e a UI.
- `endpoints` (object[]) — Todo endpoint com método, caminho, auth, URL absoluta e o que devolve.
- `quota` (object) — O que é grátis, o que custa e como pagar — antes de você gastar chamada.
- `mcp` (object) — Endereço e transporte do servidor MCP.
- `quickstart` (string[]) — As chamadas que levam do zero ao primeiro registro publicado.

### `GET /api/health`

Liveness e o commit publicado agora — é como o smoke espera o próprio deploy.

- **URL:** `https://classificado.app.br/api/health`
- **Auth:** `none` — Público, sem credencial.

**Resposta `200`**

- `ok` (bool) — Sempre `true` quando o Worker responde.
- `app` (string) — Nome do produto.
- `build` (string) — Commit publicado; o CI passa o SHA curto no deploy.
- `ts` (string) — Momento da resposta (UTC, ISO-8601).

### `POST /mcp`

Servidor MCP por HTTP (Streamable HTTP, JSON-RPC 2.0) — pluga no cliente sem instalar nada.

As tools são as operações deste mesmo catálogo; o MCP não tem backend próprio. `GET /mcp` devolve o cartão do servidor.

- **URL:** `https://classificado.app.br/mcp`
- **Auth:** `none` — Público, sem credencial.
- Credencial vai nos headers de sempre (X-Guest-Token, Authorization, X-PAYMENT) e é repassada à API.
- Cota estourada chega como 402 com accepts[] dentro do resultado da tool — pague e repita.

**Resposta `200`**

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

**Exemplo**

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

## Identidade

### `POST /api/guest`

Cria um convidado `mr_…` — é a identidade que curte, comenta e visita.

Não pede e-mail. Publicar registro é que exige conta (ou pagamento).

- **URL:** `https://classificado.app.br/api/guest`
- **Auth:** `none` — Público, sem credencial.

**Resposta `200`**

- `token` (string) — O convidado, prefixo `mr_`. Mande em `X-Guest-Token` ou como Bearer.

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/guest
```

## Catálogo

### `GET /api/listings`

O mosaico público: busca paginada dos registros live do catálogo.

Só `live` no mosaico. Com `q`, `low_count` diz quantos `low` (poucas estrelas ou sem licença clara) batem no termo — LIKE com teto 200. `low=1` inclui essa cauda; sem `q` o parâmetro é ignorado.

- **URL:** `https://classificado.app.br/api/listings`
- **Auth:** `none` — Público, sem credencial.

**Query**

- `q` (string) — Texto livre no nome, na tagline e na descrição. Ex.: `postgres`.
- `kind` (string) — Que tipo de recurso trazer. Valores: `mcp`, `skill`, `plugin`.
- `category` (string) — Categoria declarada por quem publicou.
- `sort` (string) — Ordem do resultado. Padrão: `recent`. Valores: `recent`, `likes`, `visits`.
- `low` (string) — `1` inclui registros `low` no resultado. Só vale junto com `q`. Valores: `1`.
- `limit` (int) — Registros por página. Padrão: `24`.
- `offset` (int) — Quantos registros pular. Use `next_offset` da resposta anterior. Padrão: `0`.

**Resposta `200`**

Estrutura: `PaginaDeAnuncios`.

- `items` (Anuncio[]) — Os registros desta página. → ver `Anuncio` em **Estruturas**.
- `limit` (int) — Tamanho de página aplicado.
- `offset` (int) — Deslocamento aplicado.
- `next_offset` (int, pode ser null) — Offset da próxima página; `null` quando acabou.
- `low_count` (int) — Quantos `low` batem no `q` (teto 200). Zero sem termo.
- `low_capped` (bool) — `true` quando a contagem bateu no teto — há pelo menos esses.
- `low_included` (bool) — `true` quando `low=1` misturou a cauda nesta página.
- `api` (string) — URL absoluta desta listagem.

**Exemplo**

```sh
curl -s 'https://classificado.app.br/api/listings?kind=mcp&sort=likes&limit=5'
```

### `GET /api/facets`

As contagens do catálogo inteiro por tipo, procedência, categoria e estado do repositório.

Existe para montar filtro sem varrer os registros: são dezenas de milhares, e pedir a lista só para contar sairia caro. Traz também `topico_inferido`, deduzido dos repositórios.

- **URL:** `https://classificado.app.br/api/facets`
- **Auth:** `none` — Público, sem credencial.

**Resposta `200`**

Estrutura: `Facetas`.

- `total` (int) — Registros live no catálogo.
- `facetas` (object) — Mapa de faceta → lista de `{ v, n }` (valor e contagem): `kind`, `origin`, `category`, `repo_estado`, `transporte`…
- `topico_inferido` (object) — Tópicos deduzidos dos repositórios, com a contagem de cada um.
- `api` (string) — URL absoluta desta rota.

**Exemplo**

```sh
curl -s https://classificado.app.br/api/facets
```

### `GET /v0.1/servers`

Subregistry MCP no formato do Official Registry (spec v0.1), paginado por cursor.

Só `kind=mcp` e só `live`. É a rota que um cliente MCP genérico sabe ler sem conhecer este produto. `GET /v0/servers` é alias do mesmo recurso, mantido para quem já apontava para lá — a URL canônica é esta.

- **URL:** `https://classificado.app.br/v0.1/servers`
- **Auth:** `none` — Público, sem credencial.

**Query**

- `search` (string) — Texto livre no nome e na descrição do servidor.
- `cursor` (string) — Cursor opaco da página seguinte, vindo de `metadata.next_cursor`.
- `limit` (int) — Servidores por página. Padrão: `30`.

**Resposta `200`**

Estrutura: `PaginaV01`.

- `servers` (ServidorV01[]) — Os servidores desta página. → ver `ServidorV01` em **Estruturas**.
- `metadata` (object) — `next_cursor` e `count`, no formato da spec.

**Exemplo**

```sh
curl -s 'https://classificado.app.br/v0.1/servers?search=postgres&limit=5'
```

### `GET /api/listings/:id`

Ficha de um registro. O dono vê a própria mesmo pendente ou escondida.

- **URL:** `https://classificado.app.br/api/listings/:id`
- **Auth:** `none` — Público, sem credencial.

**Parâmetros de caminho**

- `id` (string, obrigatório) — ID do registro, vindo de `Anuncio.id`.

**Resposta `200`**

Estrutura: `Anuncio`.

- `id` (string) — ID do registro; é a chave em toda a API.
- `kind` (string) — O que é este registro.
- `category` (string, pode ser null) — Categoria escolhida por quem publicou.
- `name` (string) — Nome de exibição.
- `tagline` (string, pode ser null) — Uma linha dizendo para que serve.
- `body` (string, pode ser null) — Descrição longa, quando quem publicou escreveu uma.
- `url` (string) — Onde o recurso vive — o endpoint MCP, o SKILL.md ou o repositório.
- `status` (string) — Estado no catálogo.
- `origin` (string) — De onde o registro veio: `official`, `marketplace`, `directory` ou envio da comunidade.
- `origin_id` (string, pode ser null) — Identificador do registro na fonte de origem.
- `install` (string, pode ser null) — Como instalar, quando a fonte diz.
- `source` (string, pode ser null) — URL do código-fonte, quando conhecida.
- `transporte` (string, pode ser null) — Transporte do MCP: `stdio`, `http`, `sse`.
- `ns` (string, pode ser null) — Namespace do servidor no registro oficial.
- `versao` (string, pode ser null) — Versão declarada pela fonte.
- `oficial_status` (string, pode ser null) — Estado no registro oficial de MCP, quando aplicável.
- `repo_host` (string, pode ser null) — Onde o repositório está hospedado, ex. `github`.
- `topico` (string, pode ser null) — Tópico inferido do repositório, usado nas facetas.
- `stars` (int, pode ser null) — Estrelas do repositório na última apuração.
- `forks` (int, pode ser null) — Forks do repositório na última apuração.
- `prs_abertos` (int, pode ser null) — Pull requests abertos na última apuração.
- `pushed_at` (string, pode ser null) — Último push no repositório (UTC).
- `repo_estado` (string, pode ser null) — Como o repositório está.
- `likes` (int) — Quantas pessoas curtiram — o like é reversível e conta pessoas.
- `comments` (int) — Comentários públicos no registro.
- `visits` (int) — Visitas contadas pelo hop; no máximo 1 por dono por dia.
- `created_at` (string) — Quando entrou no catálogo (UTC).
- `updated_at` (string, pode ser null) — Última alteração (UTC).
- `mine` (bool) — `true` quando o registro é seu — só então dá para editar.
- `api` (string) — URL absoluta da ficha deste registro.
- `go` (string) — URL do hop: redireciona para `url` e conta a visita.
- `comments_api` (string) — URL absoluta dos comentários deste registro.

**Erros**

- `404` — Registro não existe, ou não é seu e não está live/low.

**Exemplo**

```sh
curl -s https://classificado.app.br/api/listings/ID
```

### `GET /api/go/:id`

Hop para a URL do registro: redireciona e conta a visita.

Conta no máximo 1 visita por dono por dia. O header `X-Visit-Counted` diz se esta chamada contou — é como o cliente sabe sem contar duas vezes.

- **URL:** `https://classificado.app.br/api/go/:id`
- **Auth:** `none` — Público, sem credencial.

**Parâmetros de caminho**

- `id` (string, obrigatório) — ID do registro a visitar.

**Resposta `200`**

`302` com `Location` para a URL do registro, e o header `X-Visit-Counted`.

**Erros**

- `404` — Registro não existe ou não está live/low.

## Comunidade

### `GET /api/listings/:id/comments`

Comentários públicos de um registro live.

Com credencial na chamada, cada comentário seu vem com `mine: true`.

- **URL:** `https://classificado.app.br/api/listings/:id/comments`
- **Auth:** `none` — Público, sem credencial.

**Parâmetros de caminho**

- `id` (string, obrigatório) — ID do registro.

**Resposta `200`**

- `items` (Comentario[]) — Os comentários, do mais novo para o mais antigo. → ver `Comentario` em **Estruturas**.
- `total` (int) — Quantos comentários o registro tem.

**Erros**

- `404` — Registro não existe ou não está live.

**Exemplo**

```sh
curl -s https://classificado.app.br/api/listings/ID/comments
```

### `POST /api/listings/:id/comments`

Escreve um comentário no registro. Teto de 20 por hora por dono.

- **URL:** `https://classificado.app.br/api/listings/:id/comments`
- **Auth:** `guest` — Guest token (`POST /api/guest`) em `X-Guest-Token: mr_…` ou `Authorization: Bearer mr_…`. Sessão `sess_…` também serve.

**Parâmetros de caminho**

- `id` (string, obrigatório) — ID do registro a comentar.

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

- `body` (string, obrigatório) — O texto do comentário.

**Exemplo de corpo**

```json
{
  "body": "texto"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true` quando o comentário entrou.
- `id` (string) — ID do comentário criado.
- `body` (string) — O texto gravado.

**Erros**

- `400` — Texto vazio ou longo demais.
- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.
- `404` — Registro não existe.
- `429` — Passou de 20 comentários na hora.

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/listings/ID/comments -H "X-Guest-Token: $MR" -H 'content-type: application/json' -d '{"body":"funciona bem com o Claude Code"}'
```

### `DELETE /api/comments/:id`

Apaga um comentário seu. Comentário alheio responde 404, não 403.

O 404 é de propósito: a API não confirma que existe um comentário com aquele id se ele não é seu.

- **URL:** `https://classificado.app.br/api/comments/:id`
- **Auth:** `guest` — Guest token (`POST /api/guest`) em `X-Guest-Token: mr_…` ou `Authorization: Bearer mr_…`. Sessão `sess_…` também serve.

**Parâmetros de caminho**

- `id` (string, obrigatório) — ID do comentário, vindo de `Comentario.id`.

**Resposta `200`**

- `ok` (bool) — Sempre `true`.
- `id` (string) — O id que saiu.

**Erros**

- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.
- `404` — Recurso não existe (ou não é seu — a API não distingue os dois de propósito).

**Exemplo**

```sh
curl -s -XDELETE https://classificado.app.br/api/comments/CMT_ID -H "X-Guest-Token: $MR"
```

### `POST /api/listings/:id/like`

Curte o registro. Chamar de novo não soma: o contador conta pessoas.

- **URL:** `https://classificado.app.br/api/listings/:id/like`
- **Auth:** `guest` — Guest token (`POST /api/guest`) em `X-Guest-Token: mr_…` ou `Authorization: Bearer mr_…`. Sessão `sess_…` também serve.

**Parâmetros de caminho**

- `id` (string, obrigatório) — ID do registro a curtir.

**Resposta `200`**

Estrutura: `Like`.

- `ok` (bool) — Sempre `true`.
- `liked` (bool) — Se VOCÊ está curtindo agora.
- `likes` (int) — Total de pessoas curtindo o registro.

**Erros**

- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.
- `404` — Recurso não existe (ou não é seu — a API não distingue os dois de propósito).

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/listings/ID/like -H "X-Guest-Token: $MR"
```

### `DELETE /api/listings/:id/like`

Descurte e devolve o ponto ao contador público.

- **URL:** `https://classificado.app.br/api/listings/:id/like`
- **Auth:** `guest` — Guest token (`POST /api/guest`) em `X-Guest-Token: mr_…` ou `Authorization: Bearer mr_…`. Sessão `sess_…` também serve.

**Parâmetros de caminho**

- `id` (string, obrigatório) — ID do registro a descurtir.

**Resposta `200`**

Estrutura: `Like`.

- `ok` (bool) — Sempre `true`.
- `liked` (bool) — Se VOCÊ está curtindo agora.
- `likes` (int) — Total de pessoas curtindo o registro.

**Erros**

- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.
- `404` — Recurso não existe (ou não é seu — a API não distingue os dois de propósito).

**Exemplo**

```sh
curl -s -XDELETE https://classificado.app.br/api/listings/ID/like -H "X-Guest-Token: $MR"
```

## Publicar

### `POST /api/listings`

Registra um MCP, uma skill ou um plugin no catálogo. Entra como `pending`.

Duas portas para a mesma ação. Humano com sessão: grátis, 1 por dia, no máximo 3 na fila. Agente (com ou sem convidado): **402 com `accepts[]`**, $0.10 — pague e repita. Para skill, a URL do `SKILL.md` basta; o resto é apurado. **Valida antes de cobrar:** corpo recusado (400) e cota estourada (429) vêm ANTES do 402, então nenhum pagamento liquida por um registro que já se sabe que não entra. Corpo válido sem pagamento continua recebendo o 402 com o preço.

- **URL:** `https://classificado.app.br/api/listings`
- **Auth:** `session_ou_x402` — Duas portas para a MESMA ação: humano com sessão `sess_…` (grátis, dentro da cota) ou agente pagando x402 (`X-PAYMENT`). Guest token não é exigido nem impede o caminho pago.

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

- `kind` (string, obrigatório) — O que está sendo registrado. Valores: `mcp`, `skill`, `plugin`.
- `url` (string, obrigatório) — Endpoint MCP, URL do SKILL.md ou repositório do plugin.
- `name` (string) — Nome de exibição; sem ele, sai da fonte.
- `tagline` (string) — Uma linha dizendo para que serve.
- `body` (string) — Descrição longa, opcional.
- `category` (string) — Categoria para o registro aparecer no filtro certo.

**Exemplo de corpo**

```json
{
  "kind": "mcp",
  "category": "ferramentas",
  "name": "Nome",
  "tagline": "Uma linha",
  "url": "https://exemplo.com/mcp"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true` quando o pedido entrou.
- `id` (string) — ID do registro criado.
- `status` (string) — Sempre `pending`: tudo passa pela fila antes de virar live.

**Erros**

- `400` — `kind` ou `url` ausentes, URL inválida, URL que não responde ou campo recusado.
- `402` — Cota estourada. A resposta traz `accepts[]` (x402, USDC na Base): pague e repita a mesma chamada com `X-PAYMENT`.
- `429` — 1 por dia, máximo 3 pendentes — vale para as duas portas, e é conferido antes de cobrar.
- `502` — O pagamento liquidou e a gravação falhou. O corpo traz `transaction`: guarde e fale com o suporte.

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/listings -H "X-PAYMENT: $PAGAMENTO" -H 'content-type: application/json' -d '{"kind":"mcp","url":"https://exemplo.com/mcp","name":"Meu MCP"}'
```

### `PATCH /api/listings/:id`

Edita um registro seu. Mudar a URL faz ele voltar para a fila.

A URL é o que a moderação olha; trocá-la depois de aprovado seria burlar a fila, então o registro volta a `pending`.

- **URL:** `https://classificado.app.br/api/listings/:id`
- **Auth:** `session` — Sessão: `Authorization: Bearer sess_…` (OTP e-mail).

**Parâmetros de caminho**

- `id` (string, obrigatório) — ID do registro a editar.

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

- `name` (string) — Novo nome de exibição.
- `tagline` (string) — Nova linha de resumo.
- `body` (string) — Nova descrição longa.
- `category` (string) — Nova categoria.
- `url` (string) — Nova URL — trocar isto devolve o registro para `pending`.

**Exemplo de corpo**

```json
{
  "tagline": "…"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true`.
- `id` (string) — ID do registro editado.
- `status` (string) — Estado depois da edição; volta a `pending` se a URL mudou.

**Erros**

- `400` — Campo inválido no corpo.
- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.
- `404` — O registro não é seu ou não existe.

**Exemplo**

```sh
curl -s -XPATCH https://classificado.app.br/api/listings/ID -H "Authorization: Bearer $SESS" -H 'content-type: application/json' -d '{"tagline":"agora com suporte a SSE"}'
```

### `GET /api/me/listings`

Os registros do dono em qualquer estado, inclusive pendente e escondido.

É a única rota que mostra o que ainda não é live — o mosaico público nunca mostra.

- **URL:** `https://classificado.app.br/api/me/listings`
- **Auth:** `session` — Sessão: `Authorization: Bearer sess_…` (OTP e-mail).

**Resposta `200`**

- `items` (Anuncio[]) — Os registros da conta, de qualquer estado. → ver `Anuncio` em **Estruturas**.

**Erros**

- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.

**Exemplo**

```sh
curl -s https://classificado.app.br/api/me/listings -H "Authorization: Bearer $SESS"
```

## Conta

### `GET /api/me`

A conta da sessão e, para o admin, o estado da carga.

- **URL:** `https://classificado.app.br/api/me`
- **Auth:** `session` — Sessão: `Authorization: Bearer sess_…` (OTP e-mail).

**Resposta `200`**

- `user` (Conta) — A pessoa dona da sessão. → ver `Conta` em **Estruturas**.
- `admin` (bool) — Se esta conta é o `ADMIN_EMAIL`.
- `carga` (Carga, opcional) — Estado das fontes de carga; só para o admin. → ver `Carga` em **Estruturas**.

**Erros**

- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.

**Exemplo**

```sh
curl -s https://classificado.app.br/api/me -H "Authorization: Bearer $SESS"
```

### `GET /api/me/ui`

As preferências de tela do dono: busca, filtro, ordenação e tema.

Existe para o que a pessoa arrumou sobreviver a um F5 e a reabrir o app em outro aparelho. Refresh não é tela nova — ver AGENTS-UI.md. Convidado não tem: sem conta não há a quem devolver o dado depois, então o guest fica só no `localStorage` do navegador.

- **URL:** `https://classificado.app.br/api/me/ui`
- **Auth:** `session` — Sessão: `Authorization: Bearer sess_…` (OTP e-mail).

**Resposta `200`**

Estrutura: `PreferenciasUi`.

- `prefs` (object) — As preferências gravadas, como a interface as escreveu. `{}` quando nunca houve gravação.
- `api` (string) — URL absoluta desta rota.

**Erros**

- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.

**Exemplo**

```sh
curl -s https://classificado.app.br/api/me/ui -H "Authorization: Bearer $SESS"
```

### `PUT /api/me/ui`

Grava as preferências de tela do dono, substituindo as anteriores.

É PUT e não PATCH de propósito: o cliente manda o estado inteiro da tela, não um delta. Teto de 8 KB — isto é preferência de tela, não depósito de blob.

- **URL:** `https://classificado.app.br/api/me/ui`
- **Auth:** `session` — Sessão: `Authorization: Bearer sess_…` (OTP e-mail).

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

- `prefs` (object, obrigatório) — O estado da interface a guardar. Opaco para o servidor: qualquer JSON dentro do teto serve.

**Exemplo de corpo**

```json
{
  "prefs": {
    "q": "postgres",
    "kind": "mcp",
    "sort": "likes",
    "tema": "escuro"
  }
}
```

**Resposta `200`**

Estrutura: `Ok`.

- `ok` (bool) — Sempre `true` — a falha vem como status 4xx/5xx, não como `ok:false`.

**Erros**

- `400` — Corpo que não é JSON (`bad_json`) ou sem a chave `prefs` (`prefs`).
- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.
- `405` — Método diferente de GET ou PUT nesta rota.
- `413` — Preferências acima do teto de 8 KB (`grande`).

**Exemplo**

```sh
curl -s -XPUT https://classificado.app.br/api/me/ui -H "Authorization: Bearer $SESS" -H 'content-type: application/json' -d '{"prefs":{"sort":"likes"}}'
```

### `POST /api/auth/start`

Envia o código de 6 dígitos por e-mail para criar a conta ou entrar nela.

- **URL:** `https://classificado.app.br/api/auth/start`
- **Auth:** `none` — Público, sem credencial.

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

- `email` (string, obrigatório) — E-mail que vai receber o código.

**Exemplo de corpo**

```json
{
  "email": "voce@exemplo.com"
}
```

**Resposta `200`**

Estrutura: `Ok`.

- `ok` (bool) — Sempre `true` — a falha vem como status 4xx/5xx, não como `ok:false`.

**Erros**

- `400` — E-mail ausente ou malformado.
- `429` — Pedidos demais para o mesmo e-mail.

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/auth/start -H 'content-type: application/json' -d '{"email":"voce@exemplo.com"}'
```

### `POST /api/auth/verify`

Troca o código por uma sessão `sess_…`.

- **URL:** `https://classificado.app.br/api/auth/verify`
- **Auth:** `none` — Público, sem credencial.

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

- `email` (string, obrigatório) — O mesmo e-mail do `/api/auth/start`.
- `code` (string, obrigatório) — Os 6 dígitos que chegaram por e-mail.

**Exemplo de corpo**

```json
{
  "email": "voce@exemplo.com",
  "code": "123456"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true` quando o código conferiu.
- `token` (string) — Sessão `sess_…` para usar em `Authorization: Bearer`.
- `user` (Conta) — A pessoa que acabou de entrar. → ver `Conta` em **Estruturas**.

**Erros**

- `400` — Código errado ou expirado.
- `429` — Tentativas demais.

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/auth/verify -H 'content-type: application/json' -d '{"email":"voce@exemplo.com","code":"123456"}'
```

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

Amarra um convidado à conta: likes e comentários dele passam a ser dela.

- **URL:** `https://classificado.app.br/api/auth/claim`
- **Auth:** `session` — Sessão: `Authorization: Bearer sess_…` (OTP e-mail).

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

- `guest_token` (string, obrigatório) — Convidado `mr_…` a ligar na conta.

**Exemplo de corpo**

```json
{
  "guest_token": "mr_…"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true`.
- `claimed` (int) — Quantos registros mudaram de dono.

**Erros**

- `400` — `guest_token` ausente.
- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/auth/claim -H "Authorization: Bearer $SESS" -H 'content-type: application/json' -d '{"guest_token":"mr_…"}'
```

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

Invalida a sessão em curso.

- **URL:** `https://classificado.app.br/api/auth/logout`
- **Auth:** `session` — Sessão: `Authorization: Bearer sess_…` (OTP e-mail).

**Resposta `200`**

Estrutura: `Ok`.

- `ok` (bool) — Sempre `true` — a falha vem como status 4xx/5xx, não como `ok:false`.

**Erros**

- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/auth/logout -H "Authorization: Bearer $SESS"
```

## Cobrança

### `GET /api/billing`

Configuração x402 em vigor e os preços de contato e de publicação por agente.

- **URL:** `https://classificado.app.br/api/billing`
- **Auth:** `none` — Público, sem credencial.

**Resposta `200`**

Estrutura: `Billing`.

- `provider` (string) — Sempre `x402` — é o único protocolo de cobrança aceito.
- `mode` (string) — Modo do vendedor: `live` cobra de verdade, `dev` libera sem pagar.
- `network` (string) — Rede da USDC: `base` em produção, `base-sepolia` em homologação.
- `chain_id` (int) — Chain ID EVM da rede acima, para a carteira assinar na cadeia certa.
- `pay_to` (string, pode ser null) — Endereço que recebe o pagamento.
- `homolog` (bool) — Seam de homologação ligado: dá para fechar o loop sem gastar USDC.
- `dev` (bool) — Modo de desenvolvimento: o 402 é simulado.
- `dev_gate` (string, pode ser null) — Como o modo dev é destravado, quando existe.
- `facilitator` (string) — URL do facilitador que verifica e liquida o pagamento.
- `asset` (string) — Moeda aceita — sempre `USDC`.
- `asset_address` (string) — Contrato da USDC na rede acima.
- `faucet` (string, pode ser null) — Torneira de USDC de teste; só em base-sepolia.
- `wallets` (object) — Links de carteiras que falam x402 (metamask, coinbase, base_app).
- `product` (string) — Nome do produto que está cobrando.
- `prices` (Precos) — Quanto custa cada ação paga, em USD. → ver `Precos` em **Estruturas**.

**Exemplo**

```sh
curl -s https://classificado.app.br/api/billing
```

### `POST /api/contact`

Fala com o suporte: humano resolve Turnstile, agente paga $0.10 em x402.

O primeiro envio de agente é livre; depois o backoff é 60s dobrando até o teto de 1 hora, informado em `Retry-After`.

- **URL:** `https://classificado.app.br/api/contact`
- **Auth:** `none` — Público, sem credencial.

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

- `name` (string, obrigatório) — Como chamar quem escreveu.
- `email` (string, obrigatório) — Para onde responder.
- `message` (string, obrigatório) — O que você quer dizer.
- `form_ts` (int) — Momento em que o formulário abriu; é anti-robô do caminho humano.

**Exemplo de corpo**

```json
{
  "name": "…",
  "email": "a@example.com",
  "message": "…",
  "form_ts": 0
}
```

**Resposta `200`**

Estrutura: `Ok`.

- `ok` (bool) — Sempre `true` — a falha vem como status 4xx/5xx, não como `ok:false`.

**Erros**

- `400` — Campo obrigatório faltando.
- `402` — Cota estourada. A resposta traz `accepts[]` (x402, USDC na Base): pague e repita a mesma chamada com `X-PAYMENT`.
- `429` — Backoff de agente: espere o `Retry-After`.

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/contact -H "X-PAYMENT: $PAGAMENTO" -H 'content-type: application/json' -d '{"name":"Agente","email":"a@example.com","message":"Olá"}'
```

### `POST /api/visit`

Ping da interface que incrementa a visita do dia. Agente não precisa chamar.

Smoke não conta: `X-MM-Smoke`, User-Agent `mm-smoke` ou `smoke: true` no corpo entram como `counted: false`.

- **URL:** `https://classificado.app.br/api/visit`
- **Auth:** `none` — Público, sem credencial.

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

- `p` (string) — Caminho da página visitada.
- `smoke` (bool) — `true` marca a chamada como teste e ela não entra na contagem.

**Exemplo de corpo**

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

**Resposta `200`**

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

**Exemplo**

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

### `GET /api/metrics`

Métricas dos últimos 7 dias. Com o token do operador, inclui os pagamentos.

Sem credencial devolve visitas, uso e contas. Com `METRICS_TOKEN` em Bearer acrescenta `payments` — e só em Base mainnet, porque número de homologação em painel financeiro engana.

- **URL:** `https://classificado.app.br/api/metrics`
- **Auth:** `none` — Público, sem credencial.

**Headers**

- `Authorization` (string) — `Bearer <METRICS_TOKEN>` para incluir o bloco financeiro.

**Resposta `200`**

Estrutura: `Metricas`.

- `app` (string) — Nome do produto.
- `today` (string) — Dia de referência (UTC, AAAA-MM-DD).
- `today_visits` (int) — Visitas contadas hoje.
- `today_contacts` (int, opcional) — Mensagens de contato recebidas hoje. Só com `METRICS_TOKEN`: contato não sai sem token.
- `days` (object[]) — Um registro por dia da janela, com as contagens de cada métrica.
- `usage` (object) — Uso por recurso do produto — aqui, registros criados pela superfície (origin community); carga de catálogo do próprio registro não conta como uso.
- `accounts` (object) — Total de convidados e contas.
- `financeiro` (object, opcional) — Agregado do dia: `hoje_usd`, `hoje_count`, `rede`. Só com `METRICS_TOKEN`: dinheiro não sai sem token; a série completa é `payments`.
- `payments` (object, opcional) — Resumo financeiro; só com METRICS_TOKEN.

**Exemplo**

```sh
curl -s https://classificado.app.br/api/metrics -H "Authorization: Bearer $METRICS_TOKEN"
```

## Operação

### `GET /api/fila`

O retrato público da fila de enriquecimento: quanto do catálogo já foi apurado.

É público porque é sobre a saúde do catálogo, não sobre ninguém: só números agregados, nenhum registro identificável.

- **URL:** `https://classificado.app.br/api/fila`
- **Auth:** `none` — Público, sem credencial.

**Resposta `200`**

Estrutura: `EstadoFila`.

- `ok` (bool) — Sempre `true` quando há retrato.
- `fila` (RetratoFila) — Os números da fila. → ver `RetratoFila` em **Estruturas**.

**Exemplo**

```sh
curl -s https://classificado.app.br/api/fila
```

### `POST /api/admin/fila`

O robô de enriquecimento empurra aqui o retrato da própria fila.

Só a credencial do robô: isto não escreve no catálogo, então não há motivo para aceitar admin.

- **URL:** `https://classificado.app.br/api/admin/fila`
- **Auth:** `token` — Token de operador `ADMIN_TOKEN` ou `METRICS_TOKEN` em Bearer. As rotas de carga também aceitam a credencial do enriquecedor, que é de menor privilégio — ver cada endpoint.

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

- `fila` (object, obrigatório) — O retrato da fila: totais, estados e motivos.

**Exemplo de corpo**

```json
{
  "fila": {
    "total": 20182,
    "concluidos": 11675
  }
}
```

**Resposta `200`**

Estrutura: `Ok`.

- `ok` (bool) — Sempre `true` — a falha vem como status 4xx/5xx, não como `ok:false`.

**Erros**

- `400` — Corpo sem `fila`.
- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/admin/fila -H "Authorization: Bearer $TOKEN_ROBO" -H 'content-type: application/json' -d '{"fila":{}}'
```

### `POST /api/admin/repos`

O enriquecedor grava aqui o que apurou de um repositório: estrelas, forks, estado.

Aceita a credencial do enriquecedor OU a de admin — o robô tem a dele, de menor privilégio, e o admin entra para poder operar na mão sem depender do robô. O Worker não coleta nada: só grava o que já foi apurado fora dele.

- **URL:** `https://classificado.app.br/api/admin/repos`
- **Auth:** `token` — Token de operador `ADMIN_TOKEN` ou `METRICS_TOKEN` em Bearer. As rotas de carga também aceitam a credencial do enriquecedor, que é de menor privilégio — ver cada endpoint.

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

- `repos` (object[], obrigatório) — Um item por repositório apurado, com estrelas, forks, PRs, `pushed_at` e estado.

**Exemplo de corpo**

```json
{
  "repos": [
    {
      "url": "https://github.com/x/y",
      "stars": 120,
      "repo_estado": "ativo"
    }
  ]
}
```

**Resposta `200`**

Estrutura: `Ok`.

- `ok` (bool) — Sempre `true` — a falha vem como status 4xx/5xx, não como `ok:false`.

**Erros**

- `400` — Corpo sem `repos` ou item malformado.
- `401` — Nem credencial do enriquecedor nem de admin.

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/admin/repos -H "Authorization: Bearer $TOKEN_ROBO" -H 'content-type: application/json' -d '{"repos":[]}'
```

### `GET /api/admin/listings`

A fila de moderação. Sem filtro, traz o que está pendente.

Aceita `ADMIN_TOKEN` em Bearer ou a sessão do `ADMIN_EMAIL`.

- **URL:** `https://classificado.app.br/api/admin/listings`
- **Auth:** `token` — Token de operador `ADMIN_TOKEN` ou `METRICS_TOKEN` em Bearer. As rotas de carga também aceitam a credencial do enriquecedor, que é de menor privilégio — ver cada endpoint.

**Query**

- `status` (string) — Qual estado listar. Padrão: `pending`. Valores: `pending`, `live`, `hidden`, `blocked`.

**Resposta `200`**

- `items` (Anuncio[]) — Os registros naquele estado. → ver `Anuncio` em **Estruturas**.

**Erros**

- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.

**Exemplo**

```sh
curl -s 'https://classificado.app.br/api/admin/listings?status=pending' -H "Authorization: Bearer $ADMIN_TOKEN"
```

### `POST /api/admin/listings/:id`

Decide o destino de um registro na fila: aprovar, esconder ou bloquear.

- **URL:** `https://classificado.app.br/api/admin/listings/:id`
- **Auth:** `token` — Token de operador `ADMIN_TOKEN` ou `METRICS_TOKEN` em Bearer. As rotas de carga também aceitam a credencial do enriquecedor, que é de menor privilégio — ver cada endpoint.

**Parâmetros de caminho**

- `id` (string, obrigatório) — ID do registro a moderar.

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

- `action` (string, obrigatório) — O que fazer com o registro. Valores: `approve`, `hide`, `block`.

**Exemplo de corpo**

```json
{
  "action": "approve"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true`.
- `status` (string) — O estado em que o registro ficou.

**Erros**

- `400` — `action` fora da lista.
- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.
- `404` — Recurso não existe (ou não é seu — a API não distingue os dois de propósito).

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/admin/listings/ID -H "Authorization: Bearer $ADMIN_TOKEN" -H 'content-type: application/json' -d '{"action":"approve"}'
```

### `GET /api/admin/carga`

Estado das fontes de carga do catálogo: último lote, contagem e falhas.

Aceita `ADMIN_TOKEN` em Bearer ou a sessão do `ADMIN_EMAIL`.

- **URL:** `https://classificado.app.br/api/admin/carga`
- **Auth:** `token` — Token de operador `ADMIN_TOKEN` ou `METRICS_TOKEN` em Bearer. As rotas de carga também aceitam a credencial do enriquecedor, que é de menor privilégio — ver cada endpoint.

**Query**

- `fonte` (string) — Restringe a uma fonte, ex. `official_mcp`.

**Resposta `200`**

Estrutura: `Carga`.

- `fontes` (object[]) — Cada fonte com o último lote e a contagem que ela trouxe.
- `falhas` (object[]) — Falhas de importação ainda não marcadas como vistas.
- `runs` (object[]) — As execuções recentes, da mais nova para a mais antiga.

**Erros**

- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.

**Exemplo**

```sh
curl -s https://classificado.app.br/api/admin/carga -H "Authorization: Bearer $ADMIN_TOKEN"
```

### `POST /api/admin/carga`

Dispara um lote de carga ou marca um alerta de falha como visto.

- **URL:** `https://classificado.app.br/api/admin/carga`
- **Auth:** `token` — Token de operador `ADMIN_TOKEN` ou `METRICS_TOKEN` em Bearer. As rotas de carga também aceitam a credencial do enriquecedor, que é de menor privilégio — ver cada endpoint.

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

- `action` (string, obrigatório) — O que fazer. Valores: `run`, `visto`.
- `fonte` (string) — Qual fonte carregar ou marcar, ex. `official_mcp`.

**Exemplo de corpo**

```json
{
  "action": "run",
  "fonte": "official_mcp"
}
```

**Resposta `200`**

Estrutura: `Ok`.

- `ok` (bool) — Sempre `true` — a falha vem como status 4xx/5xx, não como `ok:false`.

**Erros**

- `400` — `action` fora da lista ou fonte desconhecida.
- `401` — Sem credencial ou credencial inválida. Veja a auth deste endpoint.

**Exemplo**

```sh
curl -s -XPOST https://classificado.app.br/api/admin/carga -H "Authorization: Bearer $ADMIN_TOKEN" -H 'content-type: application/json' -d '{"action":"run","fonte":"official_mcp"}'
```

## Crédito

### `POST /api/credito`

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

- **URL:** `https://classificado.app.br/api/credito`
- **Auth:** `none` — Público, sem credencial.

**Query**

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

**Resposta `200`**

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

**Erros**

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

**Exemplo**

```sh
curl -s -XPOST 'https://classificado.app.br/api/credito?usd=10'
```

### `GET /api/credito`

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

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

**Resposta `200`**

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

**Erros**

- `401` — Sem token ou token desconhecido.

**Exemplo**

```sh
curl -s https://classificado.app.br/api/credito -H 'Authorization: Bearer cred_…'
```

## Estruturas

### `PaginaDeAnuncios`

Página do mosaico público. Não traz `total`: o catálogo tem dezenas de milhares de registros e contar tudo a cada busca sairia caro sem mudar decisão nenhuma.

- `items` (Anuncio[]) — Os registros desta página. → ver `Anuncio` em **Estruturas**.
- `limit` (int) — Tamanho de página aplicado.
- `offset` (int) — Deslocamento aplicado.
- `next_offset` (int, pode ser null) — Offset da próxima página; `null` quando acabou.
- `low_count` (int) — Quantos `low` batem no `q` (teto 200). Zero sem termo.
- `low_capped` (bool) — `true` quando a contagem bateu no teto — há pelo menos esses.
- `low_included` (bool) — `true` quando `low=1` misturou a cauda nesta página.
- `api` (string) — URL absoluta desta listagem.

### `Facetas`

Os recortes do catálogo inteiro, para montar filtro sem varrer os registros.

- `total` (int) — Registros live no catálogo.
- `facetas` (object) — Mapa de faceta → lista de `{ v, n }` (valor e contagem): `kind`, `origin`, `category`, `repo_estado`, `transporte`…
- `topico_inferido` (object) — Tópicos deduzidos dos repositórios, com a contagem de cada um.
- `api` (string) — URL absoluta desta rota.

### `PaginaV01`

A página do subregistry, paginada por cursor como manda a spec v0.1.

- `servers` (ServidorV01[]) — Os servidores desta página. → ver `ServidorV01` em **Estruturas**.
- `metadata` (object) — `next_cursor` e `count`, no formato da spec.

### `Anuncio`

Um registro do catálogo: servidor MCP, Agent Skill ou plugin do Claude Code.

- `id` (string) — ID do registro; é a chave em toda a API.
- `kind` (string) — O que é este registro.
- `category` (string, pode ser null) — Categoria escolhida por quem publicou.
- `name` (string) — Nome de exibição.
- `tagline` (string, pode ser null) — Uma linha dizendo para que serve.
- `body` (string, pode ser null) — Descrição longa, quando quem publicou escreveu uma.
- `url` (string) — Onde o recurso vive — o endpoint MCP, o SKILL.md ou o repositório.
- `status` (string) — Estado no catálogo.
- `origin` (string) — De onde o registro veio: `official`, `marketplace`, `directory` ou envio da comunidade.
- `origin_id` (string, pode ser null) — Identificador do registro na fonte de origem.
- `install` (string, pode ser null) — Como instalar, quando a fonte diz.
- `source` (string, pode ser null) — URL do código-fonte, quando conhecida.
- `transporte` (string, pode ser null) — Transporte do MCP: `stdio`, `http`, `sse`.
- `ns` (string, pode ser null) — Namespace do servidor no registro oficial.
- `versao` (string, pode ser null) — Versão declarada pela fonte.
- `oficial_status` (string, pode ser null) — Estado no registro oficial de MCP, quando aplicável.
- `repo_host` (string, pode ser null) — Onde o repositório está hospedado, ex. `github`.
- `topico` (string, pode ser null) — Tópico inferido do repositório, usado nas facetas.
- `stars` (int, pode ser null) — Estrelas do repositório na última apuração.
- `forks` (int, pode ser null) — Forks do repositório na última apuração.
- `prs_abertos` (int, pode ser null) — Pull requests abertos na última apuração.
- `pushed_at` (string, pode ser null) — Último push no repositório (UTC).
- `repo_estado` (string, pode ser null) — Como o repositório está.
- `likes` (int) — Quantas pessoas curtiram — o like é reversível e conta pessoas.
- `comments` (int) — Comentários públicos no registro.
- `visits` (int) — Visitas contadas pelo hop; no máximo 1 por dono por dia.
- `created_at` (string) — Quando entrou no catálogo (UTC).
- `updated_at` (string, pode ser null) — Última alteração (UTC).
- `mine` (bool) — `true` quando o registro é seu — só então dá para editar.
- `api` (string) — URL absoluta da ficha deste registro.
- `go` (string) — URL do hop: redireciona para `url` e conta a visita.
- `comments_api` (string) — URL absoluta dos comentários deste registro.

### `Comentario`

Comentário público num registro.

- `id` (string) — ID do comentário, para apagar.
- `body` (string) — O texto do comentário.
- `author` (string, pode ser null) — Apelido de quem escreveu.
- `created_at` (string) — Quando foi escrito (UTC).
- `mine` (bool) — `true` se é seu — só você pode apagar.

### `Like`

O estado do like depois da chamada. Ligar e desligar devolvem a mesma forma.

- `ok` (bool) — Sempre `true`.
- `liked` (bool) — Se VOCÊ está curtindo agora.
- `likes` (int) — Total de pessoas curtindo o registro.

### `Conta`

A pessoa por trás da sessão.

- `id` (string) — ID da conta.
- `email` (string) — E-mail confirmado por código.

### `Carga`

O estado das fontes de carga do catálogo — de onde os registros vêm e quando vieram.

- `fontes` (object[]) — Cada fonte com o último lote e a contagem que ela trouxe.
- `falhas` (object[]) — Falhas de importação ainda não marcadas como vistas.
- `runs` (object[]) — As execuções recentes, da mais nova para a mais antiga.

### `PreferenciasUi`

O que a pessoa arrumou na tela e precisa sobreviver a um F5: recorte de filtro, aba ativa e abas de item abertas. O conteúdo é OPACO — o servidor não interpreta o JSON, só guarda e devolve, para a tela mudar de campo sem migração de banco.

- `prefs` (object) — As preferências gravadas, como a interface as escreveu. `{}` quando nunca houve gravação.
- `api` (string) — URL absoluta desta rota.

### `Ok`

Confirmação de escrita que não tem corpo próprio a devolver.

- `ok` (bool) — Sempre `true` — a falha vem como status 4xx/5xx, não como `ok:false`.

### `Billing`

Configuração x402 em vigor e os preços do produto. Ler, curtir, comentar e visitar são grátis; o que custa para agente é publicar.

- `provider` (string) — Sempre `x402` — é o único protocolo de cobrança aceito.
- `mode` (string) — Modo do vendedor: `live` cobra de verdade, `dev` libera sem pagar.
- `network` (string) — Rede da USDC: `base` em produção, `base-sepolia` em homologação.
- `chain_id` (int) — Chain ID EVM da rede acima, para a carteira assinar na cadeia certa.
- `pay_to` (string, pode ser null) — Endereço que recebe o pagamento.
- `homolog` (bool) — Seam de homologação ligado: dá para fechar o loop sem gastar USDC.
- `dev` (bool) — Modo de desenvolvimento: o 402 é simulado.
- `dev_gate` (string, pode ser null) — Como o modo dev é destravado, quando existe.
- `facilitator` (string) — URL do facilitador que verifica e liquida o pagamento.
- `asset` (string) — Moeda aceita — sempre `USDC`.
- `asset_address` (string) — Contrato da USDC na rede acima.
- `faucet` (string, pode ser null) — Torneira de USDC de teste; só em base-sepolia.
- `wallets` (object) — Links de carteiras que falam x402 (metamask, coinbase, base_app).
- `product` (string) — Nome do produto que está cobrando.
- `prices` (Precos) — Quanto custa cada ação paga, em USD. → ver `Precos` em **Estruturas**.

### `Metricas`

Painel de 7 dias. `payments` só aparece com o token do operador e só em Base mainnet.

- `app` (string) — Nome do produto.
- `today` (string) — Dia de referência (UTC, AAAA-MM-DD).
- `today_visits` (int) — Visitas contadas hoje.
- `today_contacts` (int, opcional) — Mensagens de contato recebidas hoje. Só com `METRICS_TOKEN`: contato não sai sem token.
- `days` (object[]) — Um registro por dia da janela, com as contagens de cada métrica.
- `usage` (object) — Uso por recurso do produto — aqui, registros criados pela superfície (origin community); carga de catálogo do próprio registro não conta como uso.
- `accounts` (object) — Total de convidados e contas.
- `financeiro` (object, opcional) — Agregado do dia: `hoje_usd`, `hoje_count`, `rede`. Só com `METRICS_TOKEN`: dinheiro não sai sem token; a série completa é `payments`.
- `payments` (object, opcional) — Resumo financeiro; só com METRICS_TOKEN.

### `EstadoFila`

O retrato da fila de enriquecimento: quantos registros já foram apurados e o que se sabe deles.

- `ok` (bool) — Sempre `true` quando há retrato.
- `fila` (RetratoFila) — Os números da fila. → ver `RetratoFila` em **Estruturas**.

### `ServidorV01`

Um servidor MCP no formato do Official Registry (spec v0.1) — é o que um cliente MCP genérico espera ler.

- `name` (string) — Nome do servidor no formato namespace/nome.
- `description` (string, pode ser null) — O que o servidor faz.
- `version` (string, pode ser null) — Versão declarada.
- `repository` (object, pode ser null) — Onde o código vive.
- `remotes` (object[], pode ser null) — Endpoints remotos do servidor, quando existem.
- `packages` (object[], pode ser null) — Pacotes instaláveis do servidor, quando existem.

### `Precos`

Preços em vigor, em dólar. Leia daqui, não da documentação.

- `contact_agent_usd` (number) — Contato de agente.
- `listing_agent_usd` (number) — Publicar um registro sendo agente (humano com conta publica de graça).

### `RetratoFila`

Contadores da fila de enriquecimento, empurrados pelo robô que apura os repositórios.

- `total` (int) — Registros na fila.
- `concluidos` (int) — Já apurados.
- `vencidos` (int) — Com apuração vencida, esperando nova passada.
- `com_falha` (int) — Que falharam na apuração.
- `processados` (int) — Processados na janela corrente.
- `estados` (object) — Contagem por `repo_estado`: ativo, parado, arquivado, renomeado, sumiu.
- `motivos` (object) — Contagem por motivo de o registro estar no estado em que está.


## Cota

- Grátis: mosaico, ficha e comentários (`GET /api/listings`) — sem cota.
- Grátis: like, comentário e hop com guest token — sem cota.
- Grátis: registrar com conta de e-mail — 1 por dia, máx. 3 na fila.
- Pago: registrar como agente (com ou sem guest token) — **$0.10** USDC via x402.
- Pago: contato de agente — **$0.10** USDC via x402.

Publicar sem sessão de e-mail responde **402** com `accepts[]` (x402, USDC na Base). Pague e repita a mesma chamada com `X-PAYMENT`. Guest token NÃO tira a opção de pagar.

Números em vigor: https://classificado.app.br/api/billing