Documentação · API
Referência da API v1
Todos os endpoints desta página existem em produção e estão descritos, com schemas, no OpenAPI servido pela própria API. O que não está aqui não existe ainda.
Spec OpenAPI
A fonte canônica é o documento OpenAPI 3.1 servido pela própria API: https://api.genopt.ai/v1/openapi.json. Ele é escrito à mão contra o código das rotas — a regra da casa (ADR-023) é que rota planejada não entra no spec, então qualquer gerador de client que você apontar para ele produz só chamadas que funcionam.
Autenticação
Todas as rotas não-públicas exigem Authorization: Bearer <token>. Estado atual, sem rodeios: o token aceito hoje é o token interno da plataforma — a API é consumida server-side pelos nossos apps e integrações (é assim que os SDKs a usam). API keys de cliente autosserviço (prefixo gop_live_, armazenadas como SHA-256) são a Fase 8 do roadmap. As duas rotas públicas de verificação de evidência não pedem chave, por desenho. Rate limits por token: em implantação — quando ativos, os números entram no spec e nesta página.
curl -s https://api.genopt.ai/v1/brands/<brandId>/confabulations?window=7d \
-H 'Authorization: Bearer <SEU_TOKEN>'Endpoints
| Endpoint | Auth | O que faz |
|---|---|---|
| POST /v1/scans | Bearer | Enfileira um scan completo da marca (202 + scanId; execução assíncrona no worker). |
| GET /v1/scans/:id | Bearer | Status e resultado de um scan: contadores de runs por status, menções, custo. |
| GET /v1/brands/:id/confabulations | Bearer | Matriz engine × intent × classe de citação + lista das execuções CONFABULATED. Filtros: engine, intent, window (7d|30d|all). |
| GET /v1/runs/:id/evidence | Bearer | Evidência completa de um run: resposta bruta, snapshot SHA-256, status de verificação e histórico. |
| POST /v1/runs/:id/verify | Bearer | Enfileira a reverificação do run ("verificar novamente"). Exige classificação prévia; 202 + jobId. |
| GET /v1/runs/:id/evidence-bundle | Bearer | Bundle de evidência exportável. ?format=json (default) ou ?format=html (documento print-friendly). |
| GET /v1/brands/:id/ground-truth | Bearer | Fatos de ground truth da marca, com fonte, hash e flag de ativo. |
| POST /v1/brands/:id/ground-truth/refresh | Bearer | Dispara a coleta de ground truth manualmente. 202 + jobId. |
| GET /v1/public/evidence/:hash | público | Verificação pública: o hash existe? Metadata mínima, nunca a resposta bruta. |
| POST /v1/public/evidence/:hash/check | público | Verificação pública: envia o conteúdo em mãos e recebe verified/modified. |
Erros
Erros voltam como JSON com um campo error legível (e campos extras quando ajudam a agir — o 429 diz quantos scans o plano permite).
| Código | Quando acontece |
|---|---|
| 400 | Corpo ou query inválidos — a resposta detalha o campo (zod flatten). |
| 401 | Token ausente ou inválido no header Authorization. |
| 404 | Recurso não existe (marca, scan, run ou hash). |
| 409 | Estado incompatível — ex.: reverificar run sem classificação prévia. |
| 429 | Teto do plano atingido (scans/mês) — a resposta traz maxScans e scansThisMonth. |
| 503 | Dependência indisponível: fila (REDIS_URL) ou nenhum engine configurado. |
Superfícies relacionadas
Preferindo não falar HTTP na mão: os SDKs TypeScript e Python cobrem exatamente esta tabela, e o servidor MCP expõe as mesmas consultas como tools para agentes. Verificação de evidência sem código: /verify.