Developer API docs

Authentication

Use dashboard-generated bearer API keys for almost every external integration endpoint.

Key management routes under `/api/v1/keys` are a compatibility surface that still require a signed HelloAlex dashboard session cookie.

Request format

Send JSON request bodies with `Content-Type: application/json` unless the endpoint says otherwise.

Path parameters stay in `{braces}` in the route list. Follow each operation's required marker for `Idempotency-Key`: Webhook and Session Export management mutations require `Idempotency-Key`, while other mutation routes may expose it as an optional retry header.

Response format

Single-resource endpoints return one JSON object.

List endpoints return a paginated envelope with `data`, `total`, `limit`, `offset`, and `has_more`.

Errors

Every failed `/api/v1` request returns only `{ "error_id": "<UUID>" }`. The HTTP status still identifies the error class; the body contains no error message or internal details.

Server-Sent Event error frames also contain only an `error_id` UUID. If call audio ends unexpectedly, report the `X-Error-Id` response header.

Send the `error_id` UUID to HelloAlex support so we can trace the matching internal log entry.

A `429` response, and a `503` from a busy call-history read, still carries a `Retry-After` header with the number of seconds to wait before retrying.

A `403` means the request was forbidden. Check the endpoint's required permission in the API reference.

API key permissions

Grant only the scopes your integration needs.

Keys are intended to be least-privilege, so route-level scopes matter for both reads and writes.

Webhooks

Register HTTPS endpoints to receive normalized live events, billing alerts, integration outcomes, and webhook delivery health changes.

Verify each delivery with the signing secret returned when the webhook is created.

v1.1.0 changelog and migration

Version 1.1.0 is an additive dashboard-parity release across Overview, Calls, SMS, SIP Trunks, Contacts, Contact Lists and imports, Tasks, Agents, Voices, Characters, Campaigns, CRM, Memory Stores, Knowledge Bases, Web Chat Widgets, Billing, Phone Numbers and telephony, AI Intelligence, Support, Webhooks, Session Exports, Integration Logs, Account, Users, and Locations. Existing documented v1.0 reads remain under `/api/v1`; use the live OpenAPI document for the exact operations and fields included in the deployed release.

Existing integrations do not need a base-path change. Regenerate typed clients from `/api/v1/openapi.json`, review newly available read and write scopes, and create or rotate a least-privilege dashboard API key when adopting a new capability. Existing keys do not automatically receive newly introduced scopes.

The current v1 error contract returns only an `error_id` UUID. Update clients to send that value to HelloAlex support when reporting a failed request.

The docs frontend owns `/api` and `/api/reference`. The old `/api/v1/docs` path now returns `404`. `/api/v1/keys` remains a session-only internal compatibility surface and is excluded from public OpenAPI and root discovery; manage keys in the signed-in dashboard and use `/api/v1/me` for bearer introspection.

Send `Idempotency-Key` only on mutations that document it. Request schemas reject undocumented fields, and public resource identifiers are opaque and tenant-scoped where provider or internal identifiers would cross a security boundary. Undocumented provider payloads, raw errors, secrets, internal cost data, and dashboard callback transports are not compatibility fields.

Pathway behavior is unchanged: the public contract retains exactly two Pathway GET operations and adds no Pathway mutation. Grandfathered local Pathway references on other resources remain tenant-ownership checked and do not expose provider Pathway identifiers or management behavior.