API reference
Every endpoint on the Callens integration API, generated from the OpenAPI spec.
Eight operations across seven URLs, in three groups. Each page carries the full request and response schema and a console for trying the call against your own key.
Everything here is generated from openapi.yaml, which is the same document the API is tested
against — so a page that disagrees with the API is a bug in the API, not a stale doc.
Calls
| Endpoint | What it does |
|---|---|
POST /uploads | Ask for somewhere to write the recording. Returns a PUT URL and a ticket. |
POST /calls | Submit a call for analysis, using the ticket from the upload. |
Customer events
| Endpoint | What it does |
|---|---|
POST /customer-events | Send one thing that happened with a customer outside a call — a message, an order, a note. |
Webhooks
| Endpoint | What it does |
|---|---|
POST /webhooks | Register an endpoint. Returns the signing secret once. |
GET /webhooks | List the endpoints registered for your organization. |
PATCH /webhooks/{webhook} | Change an endpoint's description, or enable and disable it. The URL is deliberately not editable — register a new endpoint and disable the old one. |
POST /webhooks/{webhook}/secret | Rotate the signing secret. |
POST /webhooks/{webhook}/test | Send a real webhook.test delivery and report what happened. |
Before you start
Read authentication for how to present a key, and errors for the codes every one of these can return.
Checklist
What to confirm before pointing production traffic at Callens.
Request somewhere to upload a recording POST
Returns a short-lived presigned `PUT` URL and an opaque `ticket`. Send the audio bytes straight to `upload.url` — they never pass through Callens — then submit the call with `POST /calls`, `mode: "upload"` and the ticket. The `upload.headers` map must be applied to the `PUT` verbatim; it is empty against some storage backends and required by others, so a client that ignores it will fail with a signature mismatch in production only.