Integração com IA · API Hooked

Visão Geral

A documentação da API Hooked é publicada em formato otimizado para agentes de IA (Claude, ChatGPT, Cursor, Perplexity, etc.) consumirem direto via URL. Se seu fluxo envolve uma IA ajudando a integrar com a API, basta apontá-la para os endpoints abaixo — em poucos requests ela tem todo o contexto necessário, sem precisar rastejar dezenas de páginas HTML.

Esses recursos são complementares ao site humano. Não substituem a leitura por um desenvolvedor, mas evitam que a IA gaste tokens navegando o HTML página por página.

Recursos disponíveis

A Hooked publica quatro endpoints especificamente úteis para agentes de IA:

URL	Formato	Tamanho	Quando usar
`/llms.txt`	Markdown	~7 KB	Ponto de entrada recomendado — índice navegável com links para todos os módulos, agrupados por categoria
`/llms-full.txt`	Markdown	~1 MB	Toda a documentação pública concatenada — uma leitura traz tudo
`/swagger.json`	OpenAPI 3.0.1	~600 KB	Contrato máquina-legível — ideal para gerar SDK ou validar payloads
`/postman-collection.json`	Postman v2.1	~250 KB	Coleção pronta para importar no Postman

A URL base do site da documentação é https://api-docs.hooked.com.br (ou o domínio onde você está lendo este guia).

Como apontar uma IA para a documentação

Claude (web ou desktop)

Cole a URL do índice diretamente no prompt:

https://api-docs.hooked.com.br/llms.txt

Com base nesse índice, me ajude a integrar com a API Hooked.
Preciso criar um pedido com 2 itens em Python.

Para tarefas que exigem mais contexto, aponte para o arquivo completo:

Leia https://api-docs.hooked.com.br/llms-full.txt e descreva
o fluxo completo de autenticação até o primeiro POST.

ChatGPT (com browsing ativado)

Baseando-se em https://api-docs.hooked.com.br/llms-full.txt,
escreva um cliente JavaScript que liste pessoas com paginação.

Cursor, Continue, GitHub Copilot Workspace e afins

Adicione https://api-docs.hooked.com.br/llms-full.txt como fonte de contexto do projeto (a UI varia por ferramenta — em Cursor: @Docs → Add new doc → cole a URL). A partir daí, o agente tem a doc da API disponível em todas as conversas.

Geração de SDK / validação de schema

Para ferramentas que esperam OpenAPI puro:

# Gerar cliente em qualquer linguagem suportada
openapi-generator-cli generate \
  -i https://api-docs.hooked.com.br/swagger.json \
  -g python \
  -o ./hooked-client

# Validar um payload contra o schema
npx @apidevtools/swagger-cli validate \
  https://api-docs.hooked.com.br/swagger.json

Exemplos de prompt que funcionam bem

A partir de https://api-docs.hooked.com.br/llms-full.txt,
me dê o body JSON correto para criar uma pessoa com endereço.

Olhando https://api-docs.hooked.com.br/swagger.json,
quais são os parâmetros de query do endpoint GET /api/pedidos?
Liste com tipo e se é obrigatório.

Use https://api-docs.hooked.com.br/llms.txt como índice e
me explique o que cada módulo da seção "Fiscal" representa.

Quero implementar webhook de NF-e. A partir de
https://api-docs.hooked.com.br/llms-full.txt, escreva o
endpoint receptor em Node.js validando a assinatura.

Por que isso existe

Documentação tradicional é HTML otimizado para humanos: navegação por sidebar, busca client-side, layout responsivo. Quando uma IA tenta consumir, ela precisa baixar dezenas de páginas, fazer strip de tags, inferir relações entre links — caro em tokens, lento, e perde contexto.

A solução é um padrão emergente proposto em 2024 por Jeremy Howard chamado llmstxt.org, hoje adotado por sites como Anthropic, Stripe, Cloudflare e Mintlify. Funciona como o robots.txt para LLMs: dois arquivos em texto puro na raiz do domínio, com convenção simples e descobrível.

Limites e cuidados

Token JWT expira. Se a IA gerar código que retorne 401, é só refazer o login (veja Primeiros Passos).
Apenas documentação pública. Módulos administrativos da Hooked não aparecem em llms.txt/llms-full.txt — agentes só veem o que está exposto a integradores externos.
swagger.json é a fonte de verdade do contrato. Em caso de divergência entre o texto humano e o JSON OpenAPI (raro), confie no swagger.
Não cole credenciais nos prompts. A IA pode gerar exemplos com seu token visível; substitua por placeholder antes de copiar/compartilhar.
Agentes podem alucinar. Sempre teste o código gerado contra a API real antes de colocar em produção.

Para automações em escala

Se você precisa que todos os seus desenvolvedores ou todos os jobs de uma pipeline tenham contexto da API automaticamente, aponte sua ferramenta interna (Claude Code, agentes em CI, MCP server custom) para https://api-docs.hooked.com.br/llms-full.txt. O arquivo é regenerado a cada deploy e sempre reflete a documentação publicada.