REST API basics
The REST API lets your own code do what your team does in the panel: keep contacts in step, send WhatsApp templates, work the inbox and manage webhooks.
- Who can use this
- Developer
The REST API lets your own code do what your team does in the panel: keep contacts in step, send WhatsApp templates, work the inbox and manage webhooks.
The REST API lets your own code do what your team does in the panel: keep contacts in step, send WhatsApp templates, work the inbox and manage webhooks. This page summarizes the rules every call follows. The full reference, with every operation and a playground, is in the developer portal.
Settings → Developers → Developer portal. The API's own description is also published as /v1/openapi.json on your API address; the portal shows the address for your brand.
All checks run and you get a preview, but nothing changes.
Authorization header. Keys are for servers; the API does not accept keys from arbitrary web pages.401. A key without the needed scope gets 403 insufficient_scope.application/problem+json with type, title, status, detail, code, errors[] and request_id.code, never on title or detail, which may be reworded.errors[] points at each bad field with a JSON pointer.request_id when you contact support.What to retry:
| Code | Retry? |
|---|---|
rate_limited | Yes, after Retry-After seconds |
upstream_unavailable, timeout | Yes, with backoff and the same Idempotency-Key |
| Anything else | No. Fix the request first |
RateLimit-Policy and RateLimit headers. In RateLimit, r is what is left and t is seconds until the window resets.429 rate_limited with Retry-After.Idempotency-Key: <unique string> on changes, for example your order id plus the step.Idempotent-Replayed: true, and nothing runs again.invalid_input).409 conflict.Deletes, secret rotation, event replays, sends, and stopping or cancelling a broadcast need an Api-Confirm header naming the operation's verb (for example Api-Confirm: delete). Without it you get 428 confirm_required.
{ "data": [...], "next_cursor": "..." }. Pass next_cursor back as cursor. Stop when it is null.limit is 1 to 100 (default 25).Api-Version: <date>. Without it, your key's pinned version is used.POST /v1/ops/{tool}, which takes the same fields as a JSON body. Use the resource paths when you can./v1/openapi.json before you write a call. Do not guess routes from MCP tool names: they do not map one to one.The Copilot uses its own tools, not your key. To test an idea before coding it, ask, for example: "Count contacts tagged VIP" or "Dry-run sending the order_update template to +1 555 0123."
| What you see | Why | What to do |
|---|---|---|
401 | Key missing, revoked, expired, or called from outside its IP allowlist | Check the key in API keys |
403 insufficient_scope | The key lacks the scope | Create a key with the scope |
428 confirm_required | An irreversible call without Api-Confirm | Add Api-Confirm: <verb> |
409 conflict | The first request with this Idempotency-Key is still running | Wait, then retry |
429 rate_limited | Over a limit | Wait Retry-After seconds |
| Changes "work" but nothing happens | You are using a test key | Use a live key |