Documentação
Como o GenOpt funciona — e o que a API expõe hoje
Documentação mínima e honesta: o fluxo de medição, os endpoints que existem em produção e o que ainda é roadmap. Nada listado aqui é promessa.
Como funciona
O GenOpt mede o que as IAs generativas dizem sobre uma marca em quatro passos. Primeiro, você cadastra a marca e os prompts monitorados — as perguntas que um cliente real faria, com e sem citar o nome. Segundo, o scan executa esses prompts nos engines do seu plano (ChatGPT, Gemini, Claude, Perplexity, Grok, DeepSeek, Google AI Overviews e Google AI Mode), consultando os modelos pelas APIs e, no caso dos produtos de busca do Google, o provedor DataForSEO. A cadência é publicada por engine: diária nos engines baratos, semanal nos caros — a conta de custo que sustenta essa decisão está aberta em /precos.
Terceiro, cada resposta é armazenada bruta, com metadados e um hash SHA-256 — esse hash é o que torna a evidência verificável depois, inclusive por quem não tem conta. Quarto, um classificador (com juiz automático nos casos ambíguos) atribui a cada resposta uma das 5 classes do ADR-031: STRONG, DESCRIPTIVE, ECHO, CONFABULATED ou ABSENT. As métricas agregadas — share of voice, taxa de confabulação, citação por intenção — são calculadas com fórmulas publicadas em /metodologia: qualquer número da tela pode ser refeito na mão.
API
A autenticação usa o header Authorization: Bearer — hoje com o token interno da plataforma, de uso server-side; API keys de cliente autosserviço (prefixo gop_live_, armazenadas do nosso lado apenas como SHA-256) são a Fase 8 do roadmap. Os dois endpoints públicos de verificação não pedem chave. A referência completa, com erros e o spec OpenAPI, está em /docs/api. Estes são os endpoints existentes hoje; o que não está na lista não existe ainda:
| Endpoint | Auth | O que faz |
|---|---|---|
| POST /v1/scans | Bearer | Dispara um scan para uma marca: executa os prompts monitorados nos engines do plano e enfileira a classificação. |
| GET /v1/brands/:id/confabulations | Bearer | Lista as respostas classificadas como confabulação para a marca, com engine, prompt, data e referência da evidência. |
| GET /v1/runs/:id/evidence | Bearer | Devolve a evidência de uma execução: resposta bruta, metadados e hash SHA-256. |
| POST /v1/runs/:id/verify | Bearer | Recalcula o hash da evidência armazenada e confirma a integridade da execução. |
| GET /v1/runs/:id/evidence-bundle | Bearer | Empacota a evidência completa da execução (resposta, contexto, hashes) para arquivamento ou perícia. |
| GET /v1/public/evidence/:hash | público | Consulta pública de evidência por hash SHA-256 — não requer autenticação. |
| POST /v1/public/evidence/:hash/check | público | Verificação pública de integridade: envia o conteúdo em mãos e recebe se ele bate byte a byte com o hash capturado. |
Verificação pública de evidência
Toda evidência emitida pelo GenOpt — uma resposta de IA armazenada, um bundle de execução — pode ser conferida por qualquer pessoa, sem conta e sem pedir permissão. O caminho de interface é /verify: cole o hash SHA-256 e receba a confirmação de que a evidência existe e está íntegra. O caminho programático são os dois endpoints públicos da tabela acima. É deliberado que a verificação não exija login: um hash que só o emissor consegue conferir não prova nada. Se você recebeu um relatório do GenOpt de um terceiro — uma agência, um fornecedor — e quer saber se os dados são reais, esse é o caminho.
MCP, SDKs e webhooks
O servidor MCP existe e está documentado em /docs/mcp: 5 tools (busca de marca, confabulações, evidência, reverificação e verificação pública de hash) via JSON-RPC 2.0, com configuração pronta para Claude Desktop. Os SDKs TypeScript e Python existem e estão em /docs/sdk — a publicação no npm e no PyPI ainda está pendente, e a página diz isso com todas as letras. Webhooks continuam sendo roadmap: não há webhook publicado, e preferimos dizer isso a lançar um stub. Se a sua integração depende deles, escreva para contato@genopt.ai contando o caso de uso: a ordem do roadmap é decidida com isso.