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

Failed requests return a structured JSON body with `error`, `message`, and optional `details`.

A `403` means the API key is valid but missing the required scope for that route.

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 docs frontend owns `/api` and `/api/reference`. The old `/api/v1/docs` path now returns `404 not_found`. `/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.