DocumentaçãoReferência
Referência da API
Todas as rotas públicas da API da Holdy: autenticação, tipos de chave e escopos, limites, paginação, erros e a referência interativa com a especificação OpenAPI.
A API da Holdy é REST sobre HTTPS, com JSON na ida e na volta. Por ela o seu produto envia eventos, diz quem é cada conta e quanto ela paga, e lê de volta o que a Holdy encontrou.
Abrir a referência interativa, com o corpo e a resposta de cada rota e um console pra testar com a sua chave. A mesma especificação está em OpenAPI 3.1, pra gerar cliente ou entregar a um agente de código.
Endereço
https://holdy.chat/api/v1
Autenticação
Toda chamada leva a chave no cabeçalho Authorization. A organização vem sempre da chave, nunca de um parâmetro.
Authorization: Bearer hol_live_...
As chaves são criadas em Configurações › Integrações. Existem dois tipos:
| Tipo | Onde vive | Escopos |
|---|---|---|
| Pública | No código do browser e do app. Envia, não lê dado de conta. | events:write, accounts:write |
| Secreta | Só no servidor. Lê o que a Holdy encontrou e apaga dados de pessoa. | events:write, behavior:read, people:delete, e accounts:write quando marcado |
A chave pública pode ser travada nos domínios do seu produto: outro site com a mesma chave recebe 403.
Rotas
| Rota | O que faz | Escopo | Chave | Chamadas por minuto |
|---|---|---|---|---|
POST /api/v1/events | Envia um evento | events:write | Pública ou secreta | 100 |
POST /api/v1/events/bulk | Envia até 500 eventos de uma vez | events:write | Pública ou secreta | 100 |
POST /api/v1/accounts/upsert | Cria ou atualiza a conta: plano, MRR, trial, conversão e cancelamento | accounts:write | Pública ou secreta | 30 |
POST /api/v1/accounts/state | Grava o estado da conta: uso contra a cota, assentos, assinatura | accounts:write | Secreta | 30 |
GET /api/v1/opportunities | Lista as oportunidades | behavior:read | Secreta | 60 |
GET /api/v1/opportunities/{id} | Lê uma oportunidade pelo id | behavior:read | Secreta | 60 |
GET /api/v1/signals | Lista os sinais ativos | behavior:read | Secreta | 60 |
GET /api/v1/evidence/{kind}/{id} | Abre a evidência de um sinal, de uma leitura ou de uma oportunidade | behavior:read | Secreta | 60 |
GET /api/v1/consumption | Consumo do plano, ingestão e IA, no agregado ou por conta | behavior:read | Secreta | 60 |
POST /api/v1/people/erase | Apaga os dados de uma pessoa | people:delete | Secreta | 30 |
O formato de cada corpo está na referência interativa. Os guias explicam quando usar cada uma: envio de eventos e leitura, conta e estado.
Paginação
As listas aceitam limit (padrão 50, até 200), since (ISO 8601) e cursor. Enquanto houver página seguinte, a resposta traz next_cursor; passe o valor em cursor na próxima chamada. Nenhuma linha se perde entre páginas, mesmo com registros criados no mesmo instante.
Limites
O limite vale por chave, por minuto, e está na tabela acima. Toda resposta diz quanto resta:
RateLimit-Limit: 60
RateLimit-Remaining: 41
RateLimit-Reset: 47
Passou do limite, a resposta é 429 com Retry-After em segundos. Os SDKs já esperam esse tempo sozinhos. Com a chave pública no browser, a contagem é por navegador (120 por minuto), com um teto de 30.000 por minuto pra chave inteira.
Erros
Erro responde no formato da RFC 7807 (application/problem+json):
{
"type": "https://api.holdy.com/errors/validation",
"title": "Validation failed",
"status": 400,
"code": "invalid_request_error",
"detail": "Request body or params failed schema validation",
"issues": [{ "path": "event", "message": "Required", "code": "invalid_type" }]
}
| Status | Quando | O que fazer |
|---|---|---|
400 | Corpo ou parâmetro fora do formato. issues aponta o campo. | Corrigir e reenviar. |
401 | Chave ausente, inválida ou revogada. | Conferir a chave. |
403 | Chave sem o escopo da rota (insufficient_scope) ou origem não permitida (origin_not_allowed). | Usar a chave certa ou liberar o domínio. |
404 | Rota ou registro que não existe nesta organização. | Conferir o caminho e o id. |
429 | Limite por minuto atingido. | Esperar o Retry-After. |
500 | Erro do lado da Holdy. O detail traz um request_id. | Reenviar; o envio de evento com external_id e occurred_at nunca duplica. |