Para agentes de IA

A API do Chatfood foi documentada para ser usada por agentes de IA e automações: criar fluxos, disparar broadcasts, ler resultados. Esta página resume o que um agente precisa. O guia completo, escrito para modelos, está em /llms-full.txt.

API v1 em lançamento

As rotas citadas aqui são as da API pública /v1 (por exemplo GET /v1/me, GET /v1/pages, POST /v1/broadcasts). Enquanto a /v1 não estiver publicada em produção, os tokens cf_live_ e os arquivos de descoberta já funcionam, mas o OpenAPI de agentes publicado ainda lista as rotas anteriores.

1. Obter o token

Um agente nunca deve precisar da senha de ninguém. Uma pessoa entra no painel e cria um token para ele:

1. Abra Configurações > Tokens de API e clique em Novo token.
2. Dê um nome que identifique o agente e escolha uma conta só: o token não enxerga as demais.
3. Escolha os escopos mínimos. Cada área fica em Sem acesso, Leitura ou Escrita (area:read ou area:write; escrita inclui leitura):
   • relatórios: metrics:read;
   • enviar broadcasts: broadcasts:write e flows:read;
   • montar e publicar fluxos: flows:write.
4. Defina uma expiração.
5. Entregue ao agente o valor cf_live_.... Ele aparece uma única vez.

O agente envia o token em Authorization: Bearer cf_live_... ou X-Api-Key: cf_live_..., e começa toda sessão com GET /v1/me, que diz quais contas e permissões o token alcança. O token nunca passa das permissões do dono, nunca alcança rotas administrativas e pode ser revogado a qualquer momento. Veja Primeiros passos com a API para a tabela completa de escopos.

2. Como o agente descobre a API

Arquivo	Para que serve
https://docs.chatfood.app/llms.txt	Índice curto, no padrão llmstxt.org: o que a API faz, como autenticar, início rápido e links.
https://docs.chatfood.app/llms-full.txt	Guia completo: modelo de contas e páginas, contrato do script dos fluxos, broadcasts, jornadas, leads, métricas, receitas com curl, erros e boas práticas.
https://docs.chatfood.app/.well-known/agent.json	Manifesto em JSON: autenticação, capacidades e as rotas de cada capacidade.
https://api.chatfood.app/swagger/agents/swagger.json	OpenAPI 3 com só as rotas que um token pode chamar, cada uma com o escopo exigido em x-required-scope. Gerado com a mesma regra que o servidor aplica: rota fora dele responde 403 a um token.

Os três primeiros são servidos pela própria API. O GraphQL (POST https://api.chatfood.app/graphql) é só leitura e tem introspecção ligada.

Capacidades descritas no manifesto: descobrir o escopo do token, gerenciar páginas, montar fluxos, enviar broadcasts, gerenciar jornadas, ler leads, ler métricas, gerenciar pixels e gerenciar sites.

3. Limites e erros

• 120 chamadas por minuto por token. Acima disso, 429 com Retry-After: espere e continue.
• 401: token ausente, vencido ou revogado. Pare e peça um novo token; não repita em loop.
• 403 citando um escopo: falta esse escopo ao token. 403 sem escopo: o recurso é de outra conta.
• 400: corrija o payload; não repita igual.
• Erros vêm em application/problem+json (type, title, status, detail).
• Repetir é seguro em GET. Em escritas, só depois de confirmar, lendo, que a primeira tentativa não teve efeito: POST /v1/broadcasts não é idempotente.

Detalhes em Erros e limites.

4. Boas práticas para agentes

• Menor privilégio, um token por conta e por finalidade, com validade.
• Nunca imprima, registre ou envie o token a terceiros.
• Confirme com uma pessoa antes de qualquer escrita que chega a leads (broadcasts, ativação de jornadas, publicação de fluxos) e prefira agendar a enviar na hora.
• Leia antes de escrever: PUT substitui o recurso inteiro.

Mais em Boas práticas.

MCP

Em breve.