Your first API call

The Cognizy public API is REST with JSON. Your system can read and change conversations, contacts, deals, tasks, the knowledge base and everything else the key allows. The full reference, route by route, is in the API reference.

1. Create a key

In Cognizy, open Settings › Integrations › API and webhooks and click New key. Choose:

• Environment: sandbox (cgz_test_…) to test, production (cgz_live_…) for real.
• Permissions: tick only the modules and actions the integration needs. A key without permissions authenticates but can't call anything.

The key is shown once. Keep it in a secrets vault or an environment variable, never in code or in the browser.

2. Make the first call

Every call carries the key in the Authorization header. The key already tells which company the data belongs to: you never send the organization id.

export COGNIZY_API_KEY="paste-your-key-here"

curl https://api.cognizy.ai/api/v1/public/agents \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

The answer lists the company's AI agents. This route needs the agents:read permission.

3. Or use the SDK (JavaScript and TypeScript)

npm install @cognizy/sdk

import { Cognizy } from '@cognizy/sdk'

const cognizy = new Cognizy({ apiKey: process.env.COGNIZY_API_KEY! })

// Opens a conversation tied to a customer in your system (externalId)
const conversation = await cognizy.conversations.create({
  contact: { externalId: 'customer-42', name: 'Maria Souza', email: 'maria@example.com' },
})

// Sends a message and gets the AI reply
const { reply } = await cognizy.messages.send({
  conversationId: conversation.id,
  message: 'What are your opening hours?',
})
console.log(reply?.body)

The SDK covers agents, conversations, messages (with streaming), direct email and WhatsApp, and webhook verification. Call the rest of the API with fetch, using the same header. See the SDK guide.

Limits

• Each key makes up to 60 calls per minute and 1,000 per hour.
• The company has a monthly call quota that depends on the plan.
• Every response carries X-RateLimit-Remaining-Minute, X-RateLimit-Remaining-Hour and X-Quota-Remaining-Month.
• Over the limit: 429 with code: "RATE_LIMITED" and a Retry-After header (seconds). Over the monthly quota: 429 with code: "QUOTA_EXCEEDED".

Pagination

• Page-based (conversations, contacts, tasks, campaigns, knowledge bases): ?page=1&limit=25. The response has data, page, limit and total.
• Cursor-based (messages and other time-ordered lists): ?cursor=…&limit=50. The response has data, nextCursor and hasMore.

limit goes from 1 to 100.

Retrying without duplicates

On POST and PATCH, send an Idempotency-Key header with a value of your own (a UUID, for example). If the network drops and you retry with the same key within 24 h, the API returns the same response without running again.

curl -X POST https://api.cognizy.ai/api/v1/public/conversations \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"contact":{"externalId":"customer-42","name":"Maria Souza"}}'

Errors

Errors always have the same shape:

{ "statusCode": 404, "code": "not_found", "message": "Conversation not found" }

Actions that need approval

Some writes that reach the customer (booking, cancelling, sending a message, launching a campaign) don't run right away: they answer 202 with the request. An owner or admin approves it in To review or in the AI Approvals tab of API and webhooks. In the reference, these routes carry the "Needs approval" badge.