The Callario API, as it actually is.

Every request goes to https://api.callario.com/papi/v1 over HTTPS, sends and receives JSON, and is authenticated with an API key. The API uses the same services as the Callario console, so the same validation, workspace isolation and audit trail apply to an API request as to a click.

A workspace owner or admin creates keys in Settings → Integrations. A key looks like ck_<prefix>_<secret> and is shown once, when it’s created: Callario stores only a hash of the secret, so a lost key is replaced, not recovered. Revoking a key stops it immediately; to rotate, create the new key, switch over, then revoke the old one. Each key records when it was last used.

Send the key in either header. A key carries one or more scopes, and each endpoint needs exactly one of them.

curl https://api.callario.com/papi/v1/tickets \  -H "Authorization: Bearer ck_9f2c41e07a3b5d10_<secret>"# or, equivalentlycurl https://api.callario.com/papi/v1/tickets \  -H "X-Api-Key: ck_9f2c41e07a3b5d10_<secret>"

Returns a page of tickets, newest activity first unless you sort otherwise. All parameters are optional query-string values.

curl "https://api.callario.com/papi/v1/tickets?status=open&priority=urgent&sort=sla_due&pageSize=10" \  -H "Authorization: Bearer $CALLARIO_API_KEY"

{  "data": [    {      "id": "3c0b8a6e-2f4d-4e7a-9a51-6d2f0c1b7e42",      "number": 1042,      "subject": "Can't sign in after changing my email",      "status": "open",      "priority": "urgent",      "type": "question",      "channel": "web",      "requester": { "id": "8d1e…", "name": "Maya Rivera", "email": "maya@northwind.example" },      "assignee": null,      "team": null,      "tags": [],      "messageCount": 3,      "createdAt": "2026-10-04T09:12:44.000Z",      "updatedAt": "2026-10-04T09:20:03.000Z"    }  ],  "total": 1,  "page": 1,  "pageSize": 10}

Returns one ticket with its messages, events, links, participants, side conversations, custom-field values and SLA clocks. The id must be a UUID — any other value is a 400 — and an unknown id is a 404 with the code TICKET_NOT_FOUND. The ticket’s version increases with each change.

curl https://api.callario.com/papi/v1/tickets/3c0b8a6e-2f4d-4e7a-9a51-6d2f0c1b7e42 \  -H "Authorization: Bearer $CALLARIO_API_KEY"

{  "ticket": {    "id": "3c0b8a6e-2f4d-4e7a-9a51-6d2f0c1b7e42",    "number": 1042,    "subject": "Can't sign in after changing my email",    "status": "open",    "description": null,    "version": 4,    "solvedAt": null    // … the list fields above, plus parent, children, mergedInto, closedAt  },  "messages": [ /* the thread, oldest first */ ],  "events": [ /* status changes, assignments, … */ ],  "links": [],  "participants": [],  "sideConversations": [],  "customFields": [],  "sla": null}

Creates a ticket and answers 201 with it. Tickets created this way are marked origin: "api", so your team can tell them apart from ones a customer or a teammate opened. Name the customer by email, or by the id of an existing customer record.

curl -X POST https://api.callario.com/papi/v1/tickets \  -H "Authorization: Bearer $CALLARIO_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "subject": "Order arrived damaged",    "description": "Filed from our returns portal.",    "priority": "high",    "type": "incident",    "requesterEmail": "omar@northwind.example",    "requesterName": "Omar Haddad"  }'

HTTP/1.1 201 Created{  "id": "b7f3…",  "number": 1043,  "subject": "Order arrived damaged",  "status": "open",  "priority": "high",  "type": "incident",  "origin": "api",  "version": 0  // … the remaining ticket fields}

Returns a page of customer records from your CRM. Custom-field values are not included — some may hold personal data — and the API cannot create or edit contacts yet.

curl "https://api.callario.com/papi/v1/contacts?q=northwind&hasOpenTickets=true&sort=last_seen" \  -H "Authorization: Bearer $CALLARIO_API_KEY"

{  "data": [    {      "id": "8d1e…",      "displayName": "Maya Rivera",      "primaryEmail": "maya@northwind.example",      "primaryPhone": null,      "avatarUrl": null,      "vip": false,      "lifecycleStatus": "active",      "organization": { "id": "…", "name": "Northwind" },      "tags": ["beta"],      "ticketCount": 4,      "openTicketCount": 1,      "lastSeenAt": "2026-10-04T09:11:58.000Z",      "createdAt": "2026-08-21T14:03:10.000Z",      "updatedAt": "2026-10-04T09:12:44.000Z"    }  ],  "total": 1,  "page": 1,  "pageSize": 25}

Every error is a application/problem+json document (RFC 9457) with a stable code to branch on, a human-readable title and detail, and a traceId to quote when you ask us about it. Validation errors add an errors array naming each field and what was wrong with it.

HTTP/1.1 403 ForbiddenContent-Type: application/problem+json{  "type": "about:blank",  "title": "Insufficient API-key scope",  "status": 403,  "detail": "This key lacks the \"tickets:write\" scope.",  "code": "INSUFFICIENT_SCOPE",  "instance": "/papi/v1/tickets",  "traceId": "c41f…"}

The public API allows 600 requests per 60-second window per client IP address, counted across all four endpoints and on top of key authentication. Past that, requests answer 429 with the code RATE_LIMITED and a detail that says how many seconds remain in the window. Back off until then; the window resets on its own.

Add an endpoint in Settings → Integrations and choose its events: exact names, a prefix such as customer.*, or * for everything. Endpoint URLs must use HTTPS and resolve to a public address. Callario generates a signing secret (or takes yours) and shows it once; you can rotate it at any time, and deliveries still waiting to be retried are signed with the new one.

Each delivery is a POST with a JSON envelope — id, type, tenantId, data and occurredAt — and these headers:

POST /webhooks/callario HTTP/1.1Content-Type: application/jsonUser-Agent: Callario-Webhooks/1X-Callario-Signature: t=1759571564,v1=5d1f…a07c,v0=91be…X-Callario-Timestamp: 1759571564X-Callario-Event-Id: 6a0f2d1c-…X-Callario-Delivery-Id: e93b7c55-…{  "id": "6a0f2d1c-…",  "type": "conversation.ticket.status_changed",  "tenantId": "…",  "data": { "ticketId": "3c0b8a6e-…", "from": "open", "to": "solved" },  "occurredAt": "2026-10-04T09:32:44.120Z"}

Recompute the HMAC over the timestamp, a full stop and the raw request body, compare it with v1 in constant time, and reject anything more than five minutes old. Because the timestamp is inside the signature, a captured delivery can’t be replayed later with a new one.

import crypto from 'node:crypto';import express from 'express';const app = express();const SECRET = process.env.CALLARIO_WEBHOOK_SECRET;const TOLERANCE_SECONDS = 300;// Verify against the RAW body: re-serialising parsed JSON changes the bytes.app.post('/webhooks/callario', express.raw({ type: 'application/json' }), (req, res) => {  const header = req.get('x-callario-signature') ?? '';  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));  const t = Number(parts.t);  const raw = req.body.toString('utf8');  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.${raw}`).digest();  const given = Buffer.from(parts.v1 ?? '', 'hex');  const fresh = Math.abs(Date.now() / 1000 - t) <= TOLERANCE_SECONDS;  if (!fresh || given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {    return res.status(400).send('invalid signature');  }  const event = JSON.parse(raw);  // Deliveries are at-least-once: skip an event.id you have already processed.  res.sendStatus(200);});

Answer with any 2xx within 8 seconds and the delivery is done. Anything else — another status, a timeout, a refused connection — is retried with exponential backoff: about 1, 2, 4, 8 and 16 minutes after each failed attempt, up to six attempts in all. After the sixth it is marked dead.

The delivery log for each endpoint shows every delivery with its status, HTTP code, duration and the start of your server’s response. From there an admin can replay any delivery — failed, dead or even delivered — and it is sent again, freshly signed. Delivery is at-least-once, so de-duplicate on the event id.

The names below are checked against what the code emits. Two high-volume events are only sent to endpoints that name them — * and customer.* do not include them.

The other direction. Register one HTTPS endpoint of your own in Settings → Integrations, and the AI agent can ask it for a record — an order, a shipment, a return or an account — but only for a customer whose identity your website has verified. Requests are signed exactly like webhooks, time out after 5 seconds, and read at most 32 KB of your response. The lookup is read-only: the agent can tell a customer where their order is, not change it.

POST https://your-company.example/callario/contextContent-Type: application/jsonUser-Agent: Callario-Context/1X-Callario-Signature: t=1759571702,v1=0c9e…{ "type": "order", "ref": "A-10023", "contactRef": "email:maya@northwind.example" }

“Send test” in the console makes three fixed requests, including a badly signed one and a stale one, so an endpoint that skips verification fails the test instead of passing it.

So nobody builds against something that isn’t there: the public API does not yet update tickets, post replies, read conversations or chats, create or edit contacts, or return reports. If one of these matters to you, tell us — it shapes what we open next. The product side is on API & Webhooks.