API REST

Toda entrada de dados na Holdy converge em um endpoint HTTP. Se o SDK não cobre a sua stack, fale direto com ele.

Endpoint

POST https://holdy.chat/api/v1/events
Authorization: Bearer hol_live_...
Content-Type: application/json

Sucesso responde 202 com { ok, event_id, ingested_at }. Erros seguem RFC 7807 (problem+json) com status 400, 401 ou 500.

Envelope

Campo	Tipo	Obrigatório	Semântica
event	string	sim	Nome do evento, sem canonicalização ("invite_sent", "workflow.blocked").
occurred_at	ISO 8601	—	Quando ocorreu no seu produto. Default: horário do servidor.
user_id	string ≤200	—	ID do usuário final no seu produto.
anonymous_id	string ≤200	—	ID persistido no browser antes do login.
properties	object	—	Propriedades livres do evento. Default {}.
context	object	—	Metadata (página, device). Use context.account_external_id para associar a conta pela chave do seu produto.
external_id	string ≤200	—	ID do evento na origem, para deduplicação idempotente.

Exemplo

curl -X POST https://holdy.chat/api/v1/events \
  -H "Authorization: Bearer hol_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "invite_sent",
    "user_id": "user_42",
    "properties": { "plan": "pro" },
    "context": { "account_external_id": "acme-inc" }
  }'

Envio em lote

POST /api/v1/events/bulk aceita um array de até 500 envelopes. A aceitação é parcial: eventos inválidos voltam em rejected com o índice, os demais entram. Reenviar o batch inteiro após uma falha é seguro.

Deduplicação

Se você enviar external_id, o mesmo evento reenviado responde 202 com deduped: true em vez de duplicar — idempotência sem esforço, ideal para retries e backfills. Eventos sem external_id nunca colidem entre si.

Identidade

Envie os IDs que você tem (user_id, anonymous_id, properties.email, context.account_external_id) e a Holdy resolve usuário e conta do lado dela. Você nunca precisa conhecer IDs internos da Holdy.