Scopes and endpoints: calls, webhooks, events, exports

Last updated: 11 November 2026 · 8 min read

Steps

1. 1

   How to read this article

   • Paths follow https://api.clomni.ai/v1: GET /v1/agents means https://api.clomni.ai/v1/agents. Paths have no workspace ID, because a token belongs to one workspace.
   • Every request carries the Authorization: Bearer clomni_pat_xxx header. How to get a token: Tokens and authentication in the Developer API.
   • Risk: low (no personal data), medium (reads customer data or changes internal data), high (sends to customers, deletes, bulk exports, changes live settings).
   • Every scope goes through review, in public apps too. More: Review: checking scopes and rejection reasons.
   • "Also grants": write and manage grant the read of the same resource. send, delete, publish, assign and run grant nothing.
   • When an endpoint lists several scopes, any one of them is enough. Without the scope the API answers 403 insufficient_scope with required_scopes in the body.
   • Every POST takes an Idempotency-Key header, so a repeated request is not run twice.
2. 2

   Read calls (calls:read)

   Reads the call log: phone calls and WhatsApp calls (direction, status, length, conversation, the agent who answered). According to the catalogue recordings and transcripts belong to this scope too, which is why it is high risk.

   • Risk: high.
   • Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days.
   • Also grants: nothing else.

   Endpoints:

   • GET /v1/voice_calls: List phone calls
   • GET /v1/whatsapp_calls: List WhatsApp calls
   • GET /v1/whatsapp_calls/{call_id}: Get a WhatsApp call

   Example:

   curl "https://api.clomni.ai/v1/whatsapp_calls" \
     -H "Authorization: Bearer clomni_pat_xxx"

   curl "https://api.clomni.ai/v1/voice_calls" \
     -H "Authorization: Bearer clomni_pat_xxx"

3. 3

   Read webhooks (webhooks:read)

   Meant for seeing the app's webhook subscription and delivery log. The webhook is set up on the developer portal, in the app's "Webhooks" section, and the log is shown there.

   • Risk: low.
   • Review: goes through review; low risk scopes are looked at quickly.
   • Also grants: nothing else.

   This scope has no endpoint of its own in the /v1 API.

4. 4

   Manage webhooks (webhooks:write)

   Meant for managing the webhook subscription. The URL and topics are chosen on the developer portal. Each topic needs its own read scope: conversations:read for conversation.*, messages:read for message.*, contacts:read for contact.*.

   • Risk: medium.
   • Review: goes through review. Say exactly which data you use with it, when and why.
   • Also grants: webhooks:read.

   This scope has no endpoint of its own in the /v1 API.

5. 5

   Read the event feed (events:read)

   Reads the event feed of the last 30 days: to recover missed webhooks or to poll instead of receiving webhooks. Each topic's read scope is needed as well; events:read alone returns an empty list. Events are written only while the workspace has an active developer token or installation.

   • Risk: medium.
   • Review: goes through review. Say exactly which data you use with it, when and why.
   • Also grants: nothing else.

   Endpoints:

   • GET /v1/events: List events

   Example:

   curl "https://api.clomni.ai/v1/events?types=message.created,contact.updated&limit=100" \
     -H "Authorization: Bearer clomni_pat_xxx"

6. 6

   Run bulk exports (exports:run)

   Bulk exports conversations, messages and contacts into one file (gzip JSONL). One job at a time and 6 per 24 hours per workspace. The file link works for 1 hour. In the review describe the purpose, the target system, how often you export and how long you keep the file.

   • Risk: high.
   • Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days.
   • Also grants: nothing else.

   Endpoints:

   • POST /v1/exports: Start an export
   • GET /v1/exports/{export_id}: Get an export

   Example:

   curl -X POST "https://api.clomni.ai/v1/exports" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"resources": ["conversations", "messages", "contacts"], "since": "2026-01-01T00:00:00Z", "until": "2026-11-01T00:00:00Z"}'

   curl "https://api.clomni.ai/v1/exports/15" \
     -H "Authorization: Bearer clomni_pat_xxx"

7. 7

   Call events in real time

   To get call data the moment a call starts, ends or its recording is ready, the workspace has call webhooks: an administrator sets them up in the dashboard, no developer app is needed. See Call webhooks: send your calls to your own system.

8. 8

   Related articles

   • Which scopes you need: scopes and endpoints by what you want to do
   • Recipe: export your history and keep it in sync
   • Recipe: sync contacts with your CRM
   • Using Developer API endpoints: examples, pagination, idempotency