BESS AI API

The BESS AI REST API lets you build agents, place and analyze phone calls, run chat sessions, manage phone numbers and widgets, launch batch campaigns, and automate post-conversation workflows — everything the console does, programmatically.

Base URL: https://api.bess-ai.com

Authentication

Create an API key in the console under Settings → API Keys, and send it as a bearer token on every request:

curl https://api.bess-ai.com/v1/calls \
  -H "Authorization: Bearer bess_sk_live_..."

The key is shown only once at creation — store it securely, never in client-side code. Keys are scoped (for example calls:read, calls:write, chat:write, agents:read): a request beyond the key's scopes returns 403.

Prefer a typed client? pip install bessai / npm install bessai — see the SDKs. Every endpoint page in this reference includes a Python (bessai) tab where the SDK covers it, alongside curl and raw HTTP samples.

Errors

Errors are standard HTTP status codes with a JSON body describing the problem:

Status	Meaning
401	Missing, invalid, or expired API key.
403	The key's scopes don't allow this operation.
404	Resource doesn't exist (or belongs to another organization).
409	Conflict with the resource's current state.
422	Validation error — the body lists the offending fields.
429	Rate limit hit — retry after the Retry-After header.
5xx	Server-side error — safe to retry with backoff.

Rate limits

Limits apply per API key, per minute and per day, by plan tier. Successful responses include X-RateLimit-* headers; 429 responses include Retry-After. The official SDKs retry 429 and transient 5xx automatically with exponential backoff.

Webhooks

Subscribe to conversation lifecycle events (call started/ended, analysis ready) from the console. Webhook payloads are signed with HMAC — verify the signature header before trusting the body.