Nesta área
Referência da API
A API pública do Cognizy em REST e JSON. Cada rota com parâmetros, corpo, respostas e exemplos prontos para copiar.
Cognizy Public API · v1.0.0 · Gerado da API do Cognizy. Atualiza sozinho a cada hora.
O essencial
- Endereço base
https://api.cognizy.ai/api- Autenticação
Mande a chave em toda chamada no cabeçalho Authorization. A chave já diz de qual empresa são os dados: você nunca envia o id da organização.
httpAuthorization: Bearer $COGNIZY_API_KEY- Chaves
- cgz_live_ para produção e cgz_test_ para o sandbox. Crie e apague em Configurações › Integrações › API e webhooks.
Assuntos
- AgentsRead information about the organization's AI agent.1 operação
- ConversationsCreate and manage conversations, including tags and assignment.8 operações
- MessagesSend and read messages, including SSE streaming.3 operações
- ContactsList contacts and manage their tags.4 operações
- Knowledge BaseManage knowledge bases and documents; run semantic search (RAG).10 operações
- TasksManage task boards, tasks, checklists, labels and assignees.16 operações
- CampaignsRead campaigns and their analytics.3 operações
- SchedulingRead booking pages and appointments.3 operações
- AnalyticsAggregated tenant metrics.1 operação
- WebhooksManage webhook endpoints, deliveries and replays.9 operações
- WhatsAppSend WhatsApp messages directly, without creating an inbox conversation. Meta bills these to your own WABA account.3 operações
- EmailSend transactional email directly, without creating an inbox conversation. Uses a Cognizy template or a body you supply; draws on the plan allowance and then the wallet.3 operações
- Approval queue5 operações
- Marketing Funnels19 operações
- Operations3 operações
- Pending actions2 operações
- SMS2 operações
- Sales pipeline13 operações
Limites, listas por página, idempotência, streaming, webhooks e erros
Texto da API, em inglês.
Rate limits
Each API key may send 60 requests per minute and 1,000 per hour (fixed windows). Every response carries:
X-RateLimit-Limit-Minute/X-RateLimit-Remaining-MinuteX-RateLimit-Limit-Hour/X-RateLimit-Remaining-HourX-Quota-Limit-Month/X-Quota-Remaining-Month— the organization's monthly quota (unlimitedon Enterprise)
Going over a window returns 429 with code: "RATE_LIMITED" and a Retry-After header (seconds). Going over the monthly quota returns 429 with code: "QUOTA_EXCEEDED".
Pagination
List endpoints use one of two styles:
- Page-based (
?page=1&limit=25) — for conversations, contacts, tasks, campaigns, KBs. - Cursor-based (
?cursor=<opaque>&limit=50&order=asc|desc) — for messages and other time-ordered streams.
limit is clamped to 1–100. Responses include data plus either { page, limit, total } or { nextCursor, hasMore }.
Idempotency
Write endpoints (POST/PATCH) accept the Idempotency-Key header (any UUID / opaque string you choose). The first response is cached for 24h; replaying the same key returns the same response without re-executing. Use it for safe retries on network failure.
Streaming (SSE)
POST /v1/public/conversations/{id}/messages/stream opens a Server-Sent Events connection. Each event is a delta of the agent's reply:
event: delta
data: {"content":"Hello"}
event: done
data: {"messageId":"msg_..."}Concurrent streams per key are capped (StreamingConcurrencyService); excess connections return 429.
Webhooks
Subscribe to events by registering a webhook (POST /v1/public/webhooks). Each delivery is a JSON body { id, event, timestamp, data }, signed with HMAC-SHA256 using the webhook's secret:
X-Cognizy-Signature: t=<unix-seconds>,v1=<hex>
X-Cognizy-Event: deal.won
X-Cognizy-Delivery: <delivery-id>
X-Cognizy-Webhook-Id: <webhook-id>Verify by recomputing HMAC_SHA256(secret, t + "." + raw_body), comparing in constant time with any v1 value, and rejecting timestamps older than 5 minutes (verifyWebhookSignature in @cognizy/sdk does all of it). During a secret rotation the header carries two v1 values for 24h. Rotate the secret with POST /v1/public/webhooks/{id}/rotate-secret. A delivery that does not get a 2xx within 15s is tried up to 5 times in all (retries after 10s, 1min, 5min and 30min); replay it via POST /v1/public/webhooks/deliveries/{deliveryId}/replay.
Errors
Errors follow a consistent shape:
{ "statusCode": 404, "code": "not_found", "message": "Conversation not found" }Common statuses: 400 validation, 401 missing/invalid key, 403 plan feature not enabled, 404 not found, 409 conflict (e.g. tag already attached), 422 business rule, 429 rate limit / quota, 5xx server error.