# PageAudit

> Auditor técnico de SEO (title, meta description, canonical, Open Graph, Twitter
> Card, headings, JSON-LD, robots) com workspace de abas persistente. O cliente
> principal é agente de IA: tudo que a interface mostra tem endpoint equivalente.

Sem chave para começar. `POST /api/audit` com `{"url": "..."}` devolve o relatório
completo numa chamada. Para manter estado entre chamadas, pegue um guest token em
`POST /api/guest` e use as abas.

## Descoberta

- [Índice da API](https://www.pageaudit.online/api/): toda a superfície, auto-descrita, em JSON
- [llms.txt](https://www.pageaudit.online/llms.txt): este arquivo
- [OpenAPI](https://www.pageaudit.online/openapi.json): spec de máquina
- [Health](https://www.pageaudit.online/api/health): liveness e commit publicado
- UI humana: botão **API** no topo + **Agent resource hub** no rodapé (mesmos links).

## Endpoints principais

- `POST /api/audit` — Audita uma URL e devolve o relatório completo numa chamada. É o atalho para agente: não precisa de token nem de aba. (auth: none)
- `GET /api/audits/:id` — Relê um audit já feito, inteiro, sem re-auditar a página. (auth: guest)
- `GET /api/shared/:slug` — Relatório compartilhado em JSON, sem credencial. É o par legível por máquina de `/r/:slug`. (auth: none)
- `POST /api/audits/:id/share` — Publica o audit num slug não enumerável (idempotente). (auth: guest)
- `DELETE /api/audits/:id/share` — Revoga o compartilhamento. (auth: guest)
- `POST /api/guest` — Cria um guest token `pa_…` — é o que dá acesso às abas sem conta. (auth: none)
- `GET /api/tabs` — Workspace de abas do dono, com o resultado da aba ativa já reidratado. (auth: guest)
- `POST /api/tabs` — Abre uma aba para a URL (ou foca a existente) e persiste no backend. (auth: guest)
- `GET /api/tabs/:id` — Uma aba com o resultado completo do último run. (auth: guest)
- `PATCH /api/tabs/:id` — Renomeia ou ativa a aba. (auth: guest)
- `DELETE /api/tabs/:id` — Fecha a aba. O histórico em `audits` continua. (auth: guest)
- `POST /api/tabs/:id/run` — Re-audita a URL da aba e grava um novo audit. (auth: guest)
- `GET /api/gate` — Quantos audits grátis restam no IP e se o Turnstile já é exigido. (auth: none)
- `GET /api/billing` — Abas grátis, preço da aba extra e parâmetros x402. (auth: none)
- `GET /api/me` — Usuário da sessão e os últimos 50 audits dele. (auth: session)
- `POST /api/auth/start` — Envia o código OTP para o e-mail. (auth: none)
- `POST /api/auth/verify` — Troca o código por uma sessão `sess_…`. (auth: none)
- `POST /api/auth/claim` — Move audits e abas do guest para a conta. (auth: session)
- `POST /api/auth/logout` — Invalida a sessão. (auth: session)
- `POST /api/contact` — Suporte: humano com Turnstile (grátis) ou agente com x402 $0.10 (X-PAYMENT, sem captcha). (auth: none)
- `POST /api/visit` — Ping de audiência da própria UI. Agente não precisa chamar. (auth: none)
- `GET /api/metrics` — Métricas de uso dos últimos 7 dias. Operação, não produto. (auth: token)
- `GET /r/:slug` — Página HTML do relatório compartilhado (noindex). Para JSON use `/api/shared/:slug`. (auth: none)

## O que fica guardado

- Cada run grava uma linha em `audits` com o resultado inteiro: summary, issues, counts, o JSON-LD cru e todos os headers da resposta.
- Não guardado: O HTML da página — baixado até 2 MB, analisado e descartado. Reler exige novo run.
- Não guardado: `Set-Cookie` do alvo, removido de propósito: é credencial de terceiro e nenhuma checagem usa.
- Não guardado: A cadeia de redirects: o fetch segue os saltos, então só a URL final sobrevive.
- Nada some em silêncio. Corte por tamanho aparece em `truncated[]` (`jsonld_size`, `jsonld_nodes_over_50`, `result_size`) e `summary.jsonLdBlocks` / `summary.jsonLdDropped` dizem quantos blocos existiam e quantos ficaram de fora.

## Limites

- Audits por IP/hora e cota grátis diária por IP; passando disso o gate pede Turnstile.
- Abas grátis por dono limitadas; aba extra é paga via x402.
- Consulte https://www.pageaudit.online/api/gate e https://www.pageaudit.online/api/billing para os valores em vigor.

## Contato (agentes)

- `POST /api/contact` sem captcha exige **$0.10 USDC** via x402 (`X-PAYMENT`).
- Humanos usam Turnstile na UI (grátis).

## MCP / skill

- Skill do app: `.agents/skills/pageaudit/SKILL.md` (repo) — paridade com esta superfície.
- MCP: `agent/mcp/server.mjs` (tools = operações acima; não inventa backend).
- **Regra de ouro:** mexeu na UI/API → atualiza `apidocs.js` + skill + MCP + este llms.txt no mesmo PR.