Limites e paginação
Rate limit
Por chave, por classe de rota, em janela fixa de 60 s:
| Classe | Rotas | Máximo por minuto |
|---|---|---|
leitura | todos os GET, sugerir keywords | 120 |
escrita | perfil, teto, editar/apagar/agendar peça, traduzir, conexão | 30 |
gasto | pesquisar, satélite, monitorar, criar peça, análises, melhorar intent | 6 |
publicacao | publicar, responder | 6 |
Toda resposta traz:
RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 41 ← segundos até a janela virarAo estourar: 429 limite_excedido com Retry-After. A sessão do app (a tela) não passa por este limite.
Paginação
Listas grandes (GET /v1/pesquisas) usam cursor:
GET /v1/pesquisas?limite=50
→ { "itens": [...], "proximoCursor": "WyIyMDI2LTA5LTEw…" }
GET /v1/pesquisas?limite=50&cursor=WyIyMDI2LTA5LTEw…
→ { "itens": [...], "proximoCursor": null }limite de 1 a 200 (padrão 50). Cursor inválido: 400 parametro_invalido. Ordem: mais nova primeiro (criadoEm desc, id desc), estável entre páginas. As listas menores (pecas, leads, clientes, hoje) vêm inteiras.
Tamanhos
| Campo | Máximo |
|---|---|
intent | 2.000 caracteres |
keywords | 30 itens de 120 caracteres |
brief da peça | 20.000 caracteres |
body ao editar peça | 200.000 caracteres |
texto da resposta a lead | 1.000 caracteres |
Idempotency-Key | 200 caracteres |
| Nome da chave | 80 caracteres |
Corpo acima disso, ou fora do schema: 400 corpo_invalido com o campo no detail.
Tempo
Cada chamada é uma invocação serverless. As que falam com a fonte ou com a IA podem levar alguns segundos; traduzir para em ~40 s e devolve parcial (202) — chame de novo. Nenhuma rota espera a pesquisa terminar: POST /v1/pesquisas responde em segundos com running, e o GET avança o estado.
Versão
/api/v1. Toda resposta traz Pico-Version: 2026-09-11 (a data do contrato). Campo novo opcional não quebra; mudança que quebra vira /api/v2 convivendo. Registro em Changelog.