In this area
API reference
The Cognizy public API, REST and JSON. Every route with parameters, body, responses and copy-ready examples.
Cognizy Public API · v1.0.0 · Generated from the Cognizy API. Updates on its own every hour.
Essentials
- Base URL
https://api.cognizy.ai/api- Authentication
Send the key on every call in the Authorization header. The key already tells which company the data belongs to: you never send the organization id.
httpAuthorization: Bearer $COGNIZY_API_KEY- Keys
- cgz_live_ for production and cgz_test_ for the sandbox. Create and delete them in Settings › Integrations › API and webhooks.
Topics
- AgentsRead information about the organization's AI agent.1 operation
- ConversationsCreate and manage conversations, including tags and assignment.8 operations
- MessagesSend and read messages, including SSE streaming.3 operations
- ContactsList contacts and manage their tags.4 operations
- Knowledge BaseManage knowledge bases and documents; run semantic search (RAG).10 operations
- TasksManage task boards, tasks, checklists, labels and assignees.16 operations
- CampaignsRead campaigns and their analytics.3 operations
- SchedulingRead booking pages and appointments.3 operations
- AnalyticsAggregated tenant metrics.1 operation
- WebhooksManage webhook endpoints, deliveries and replays.9 operations
- WhatsAppSend WhatsApp messages directly, without creating an inbox conversation. Meta bills these to your own WABA account.3 operations
- 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 operations
- Approval queue5 operations
- Marketing Funnels19 operations
- Operations3 operations
- Pending actions2 operations
- SMS2 operations
- Sales pipeline13 operations
Limits, pagination, idempotency, streaming, webhooks and errors
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.