Audelo API

Returns your agents, paginated (50/page), ordered by name. Each row: id, name, status, voice, language, voice_engine, deepgram_voice, created_at, updated_at. voice_engine is "xai" or "deepgram" — which TTS engine actually renders this agent's calls (computed from its assigned phone number). voice is the legacy xAI voice id and is not consulted when voice_engine is "deepgram" — check deepgram_voice instead.

curl https://audelo.ai/api/v1/agents \
  -H "Authorization: Bearer cgk_..."

Returns one agent, or 404 if it isn't in your account.

{
  "id": 12, "name": "Sally", "status": "active",
  "voice": "eve", "language": "en-AU",
  "voice_engine": "deepgram", "deepgram_voice": "aura-2-hyperion-en",
  "brand_name": "McGrath Parramatta",
  "greeting_owner_name": "Joe Wehbe",
  "welcome_greeting_mode": "agent_script",
  "outbound_ai_disclosure": true,
  "outbound_recording_notice": true,
  "humour_level": 10, "empathy_level": 80,
  "formality_level": 50, "energy_level": 60, "directness_level": 60,
  "system_prompt": "You answer calls for a real estate office.",
  "created_at": "2026-06-25T10:30:00.000000Z",
  "updated_at": "2026-06-25T10:30:00.000000Z"
}

brand_name is the business the agent names on a call — it overrides your account name, so one account can run agents presenting different businesses. greeting_owner_name is whose assistant it says it is: an outbound call opens “Hi, this is {name}, {owner}’s AI assistant, calling from {brand_name}.” Put the person’s name in greeting_owner_name, not in name.

name and voice are required; everything else takes a default. Returns 201 with the same shape as the GET above.

curl -X POST https://audelo.ai/api/v1/agents \
  -H "Authorization: Bearer cgk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Sally","voice":"eve","brand_name":"McGrath Parramatta",
       "greeting_owner_name":"Joe Wehbe","humour_level":10}'

Partial — only the fields in your body change. Returns the full agent.

Writable: name, brand_name, greeting_owner_name, outbound_identity_question, inbound_recording_notice, outbound_recording_notice, welcome_greeting_mode, welcome_greeting_custom_text, the five personality sliders, system_prompt, business_context, outbound_instructions, website_url, voice, deepgram_voice, language, voice_runtime, gpt_live_voice.

call_scripts is read-only. The agent's named call scripts as {key, name, default}, empty for most agents.

humour_level is 0–30. The other four sliders are 0–100; a higher value is a 422.

inbound_recording_notice and outbound_recording_notice drop only the spoken sentence on that direction. Off does not stop recording. They default on. outbound_ai_disclosure is readable but not writable and stays on.

Every change snapshots a version you can roll back to from the dashboard. Consecutive edits from the same key within two minutes coalesce into one version, so an autosaving editor does not fill the history with a row per keystroke. That is version history, not request volume — your key’s hourly rate limit still counts every PATCH (1,000/hour by default), so debounce for that.

curl -X PATCH https://audelo.ai/api/v1/agents/12 \
  -H "Authorization: Bearer cgk_..." \
  -H "Content-Type: application/json" \
  -d '{"greeting_owner_name":"Joe Wehbe","empathy_level":85}'

Every legal value for the voice-shaped fields above. Read this before creating an agent — voice is required and is validated against it. Returns voices, deepgram_voices, voice_runtimes, gpt_live_voices and languages.

languages lists only what we can actually serve — a voice AND speech-to-text. A language we can speak but not hear is worse than one we decline: the agent replies fluently and mishears every answer. The list is therefore narrower than the set of codes the API will accept, and it widens as speech models are added. Pick from here.

Legacy regional codes (en-AU, fr-FR…) still save, so agents created before 2026-05-19 keep working, but they are not listed — use the base code for anything new.

curl https://audelo.ai/api/v1/voices \
  -H "Authorization: Bearer cgk_..."

Creates a client business underneath your account and returns an API key scoped to it. Call this once when your customer signs up and store the key against them — they never log into Audelo. Only name is required.

The parent is taken from your API key and cannot be set in the body. There is no parent_tenant_id field; sending one is ignored.

A key cannot grant what it does not hold. Omit scopes and the new key inherits yours; name them and each must already be on your key. tenants:write is never passed on, so a business you provision cannot provision businesses of its own.

Their minutes are billed to you. The response carries parent_billed: true — the business can take calls from its first minute with no balance and no card, because its usage is invoiced to you rather than charged to it. Every minute is still metered against it, and that is what the invoice is built from.

By default the business gets no login. Pass owner_email for a real dashboard login; the address must not already exist on any account. api_key.key is returned once. Rate limit: 60 calls/hour, separate from your general key limit.

curl -X POST https://audelo.ai/api/v1/partner/tenants \
  -H "Authorization: Bearer cgk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Barton Dental",
       "scopes":["agents:read","agents:write","calls:read","calls:write"]}'

Paginated call records, newest first. Row fields: id, agent_id, from_e164, to_e164, direction, status, duration_sec, created_at. Filters: agent_id, status, from (date), to (date).

curl "https://audelo.ai/api/v1/calls?status=completed&agent_id=12" \
  -H "Authorization: Bearer cgk_..."

One call, including the AI summary and recording link.

{
  "id": 456, "agent": { "id": 12, "name": "Reception Bot" },
  "from_e164": "+61412345678", "to_e164": "+61253009003",
  "direction": "inbound", "status": "completed", "duration_sec": 92,
  "summary": "Caller booked a consultation for Tuesday...",
  "recording_url": "https://...", "created_at": "2026-06-25T10:30:00.000000Z"
}

Ordered turns. timestamp is the offset in milliseconds from call start; speaker is caller or agent.

{
  "call_id": 456,
  "transcript": [
    { "timestamp": 0,    "speaker": "agent",  "text": "Hi, thanks for calling..." },
    { "timestamp": 3200, "speaker": "caller", "text": "I'd like to book an appointment" }
  ]
}

Returns the recording link, or 404 if the call has no recording.

{ "call_id": 456, "recording_url": "https://...", "duration_sec": 92 }

Places an outbound call. The call runs through your DNC list, calling-hours, and max-concurrent caps. Returns 202 Accepted.

Two ways to get real-world data into the call: push it now via custom_data below (needs dial_pipeline: "livekit"), or let the agent pull it live mid-call via Customer lookup — works on any call, inbound or outbound.

curl -X POST https://audelo.ai/api/v1/calls/initiate \
  -H "Authorization: Bearer cgk_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id":12,"phone_number":"+61412345678","caller_name":"Jane","dial_pipeline":"livekit","custom_data":{"amount_owing":"$412.50","invoice_number":"INV-2231"}}'

{ "call_id": "cgt_789", "agent_id": 12, "status": "queued",
  "created_at": "2026-06-25T10:30:00+00:00" }

Note: call_id is a cgt_... placeholder for the queued call — it hasn't been dialed yet. Use it with /end, or poll GET /calls for the materialized record once it connects.

Note: the agent treats custom_data as data to relay, not instructions to follow — it will ignore anything in there that reads like a command, and won't invent values that aren't present.

Note: once the call actually connects and its webhooks start firing, they carry the internal numeric call_id, not this cgt_... token. Match a webhook back to this call via its data.outbound_target_id field (equal to this cgt_... value) instead of polling GET /calls/{id} in a race with delivery.

Hangs up an in-progress call. id may be a numeric call id or a cgt_... placeholder. Idempotent for already-ended calls. The final status is set by the carrier callback — poll GET /calls/{id} to confirm.

{ "call_id": "cgt_789", "status": "in-progress",
  "hangup_requested_at": "2026-06-25T10:31:00+00:00" }

Mints a short-lived, room-scoped, listen-only LiveKit token for an in-progress call, so your own UI can play the live audio in-page (connect with livekit-client, subscribe to the audio tracks). The token cannot publish audio and expires after expires_in seconds — request a fresh one on the same endpoint when it does.

{ "call_id": 1850, "url": "wss://…livekit.cloud", "token": "eyJ…",
  "room": "outbound-…", "identity": "api-7-1850", "expires_in": 600 }

Errors: 409 call_not_active (call already ended) · 409 unsupported_pipeline (classic-pipeline call — live listening is available for LiveKit-pipeline calls only) · 404 (not found / not yours).

Note: anyone your app hands this token to can hear the live call — your application's own authentication is the real gate on who gets to press Listen. Treat the token like a secret and never log it.

Silences the AI agent on an in-progress outbound call — it stops speaking and stops responding to the caller for the remainder of the call — and mints a short-lived, room-scoped LiveKit token that can publish microphone audio, so a human supervisor speaks to the caller directly. Optional body {"handover_text": "…"} (≤200 chars): one sentence the agent speaks verbatim before going silent, e.g. a handover line — it also covers the connection gap while your microphone comes up.

{ "call_id": 1850, "url": "wss://…livekit.cloud", "token": "eyJ…",
  "room": "outbound-…", "identity": "api-takeover-7-1850", "expires_in": 600 }

The token also subscribes, so you keep hearing the call on this connection — disconnect any listen connection once this one is up, or every track plays twice. If the supervisor disconnects, the agent stays silent and the call continues until it is hung up or ended via End call; re-POST for a fresh token to rejoin (the handover line is never replayed). There is no agent-resume in this build.

Errors: 409 call_not_active (call already ended) · 409 unsupported_pipeline (classic-pipeline call) · 409 takeover_unavailable (inbound call — take-over is outbound-only in this build) · 502 takeover_unavailable (could not start — the agent was not silenced) · 404 (not found / not yours).

Note: anyone holding this token can speak to your caller as your business. Gate the button behind your own admin authentication, treat the token like a secret, and use headphones — echo cancellation is on by default in browsers, but speakers + open mic risk feeding the caller's own voice back to them.

Body: value (any JSON, required), ttl_seconds (optional). TTL defaults to 86400 (24h), max 2592000 (30 days). Returns 201.

{ "key": "customer:42", "expires_at": "2026-06-26T10:30:00+00:00", "ttl_seconds": 86400 }

Returns key, value, expires_at. Expired or missing keys return 404.

Idempotent — returns 204 No Content whether or not the key existed.

resolved_url / resolved_source ("agent", "tenant", or null) reflect what will actually be called on the next customer_lookup invocation — accounting for the tenant-level fallback, not just this agent's own raw columns.

{
  "agent_id": 12, "customer_lookup_enabled": true,
  "customer_lookup_url": null, "has_secret": false,
  "resolved_url": "https://api.yourcompany.com/lookup", "resolved_source": "tenant"
}

Partial update — body: { customer_lookup_url?, customer_lookup_enabled? }. Omit a field to leave it unchanged; setting the URL alone does not touch enabled. The URL must resolve to a public address — loopback, private-network, link-local, and cloud-metadata hosts are rejected with 422, re-checked on every call, not just here.

curl -X PUT https://audelo.ai/api/v1/agents/12/integrations \
  -H "Authorization: Bearer cgk_..." -H "Content-Type: application/json" \
  -d '{"customer_lookup_url": "https://api.yourcompany.com/sales-lookup"}'

Rotates this agent's own signing secret. Returns { agent_id, secret, message } — secret is shown exactly once; store it immediately.

The business-wide default. { tenant_id, customer_lookup_url, has_secret } — any agent with customer_lookup_enabled and no URL of its own uses this URL/secret.

Body: { customer_lookup_url } (required key; null clears it). Configure once and every agent with customer_lookup_enabled inherits this URL unless it has its own — the recommended setup for a single lookup endpoint shared across many agents.

curl -X PUT https://audelo.ai/api/v1/integrations \
  -H "Authorization: Bearer cgk_..." -H "Content-Type: application/json" \
  -d '{"customer_lookup_url": "https://api.yourcompany.com/lookup"}'

Rotates the tenant-wide secret. Returns { tenant_id, secret, message, affected_agents } — affected_agents ([{id, name}]) lists every agent currently inheriting this tenant-level URL (enabled, no URL of its own) — exactly the agents whose requests you need to re-verify against the new secret. An agent with its own URL/secret is unaffected and not listed.

Aggregate call stats for a window (from, to dates; default last 30 days).

{
  "period": { "from": "2026-05-26", "to": "2026-06-25" },
  "calls": { "total_calls": 412, "total_duration_sec": 38400,
             "avg_duration_sec": 93, "completed": 388 }
}

Per-agent breakdown for the window (from, to; default last 30 days).

{
  "period": { "from": "2026-05-26", "to": "2026-06-25" },
  "agents": [ { "id": 12, "name": "Reception Bot",
               "total_calls": 250, "avg_duration_sec": 88 } ]
}

Countries currently purchasable (Phase 1 markets). Cheap, no auth-sensitive data.

Search Twilio's inventory for numbers to buy. Query params: country_code (2-letter, default AU), type (local/mobile/toll_free), contains, locality, limit (max 50).

GET /api/v1/numbers/available?country_code=AU&type=local&locality=Sydney

If no inventory exists for that country/type, returns 200 with { numbers: [], warning } rather than an error.

Body {"e164": "+61491570156", "country_code": "AU", "number_type": "local", "agent_id": 42} — e164 is the exact number from an available-number search; agent_id is optional and assigns the number immediately on purchase. Same wallet-credit gate as the dashboard (must have enough credit to cover the first month's rental before Twilio is charged) and the same regulatory-bundle/address handling — never reimplemented here, only wrapped.

{ "id": 17, "e164": "+61491570156", "country_code": "AU",
  "capabilities": { "voice": true, "sms": true },
  "agent_id": 42, "agent_name": "Rebecca",
  "created_at": "2026-05-07T18:42:11Z" }

Errors: 402 insufficient_credit (wallet balance can't cover it — required_cents/available_cents included) · 422 agent_tenant_mismatch · 422 purchase_failed (a required regulatory bundle isn't set up — the message explains) · 502 carrier_error (transient — retry).

Paginated (50/page), this business's numbers only. Never includes the internal Twilio SID — that's an implementation detail, not something you need.

{ "data": [ { "id": 17, "e164": "+61491570156", "country_code": "AU",
    "capabilities": { "voice": true, "sms": true },
    "agent_id": 42, "agent_name": "Rebecca",
    "created_at": "2026-05-07T18:42:11Z" } ] }

Same shape as one row of the list above. 404 if the id isn't in your account.

Body {"agent_id": 42}. Inbound calls to this number now route to that agent. Re-assigning to the same agent it's already on is a harmless no-op.

{ "id": 17, "e164": "+61491570156", "country_code": "AU",
  "capabilities": { "voice": true, "sms": true },
  "agent_id": 42, "agent_name": "Rebecca",
  "created_at": "2026-05-07T18:42:11Z" }

Errors: 404 (number not yours) · 422 agent_tenant_mismatch (agent_id isn't an agent in your account) · 409 number_already_assigned (already on a different agent — unassign it first) · 502 twilio_number_missing (the carrier record is gone — remove the number and add a new one) · 502 carrier_error (transient — retry).

Clears inbound routing for this number — it stops routing to any agent until reassigned. No body required. A no-op if it wasn't assigned to begin with.

Full CRUD for webhook subscriptions (max 20 per account):

Create — body: url (required, public HTTPS), description (optional), events (required array). Returns 201 including the signing secret (whsec_...) — shown once.

{ "id": 5, "url": "https://example.com/hooks/audelo",
  "events": ["call.ended"], "secret": "whsec_...",
  "is_active": true, "created_at": "..." }

When a subscribed event fires, Audelo sends an HTTP POST to your URL. Available events:

Payload

{
  "id": "wh_a1b2c3d4e5f6a7b8",
  "event": "call.ended",
  "timestamp": "2026-06-25T10:31:32.000000Z",
  "data": { "call_id": 456, "agent_id": 12, "status": "completed",
            "duration_sec": 92, "ended_at": "2026-06-25T10:31:32.000000Z",
            "outbound_target_id": "cgt_789" }
}

outbound_target_id is the same cgt_... token Initiate call returned when you queued this call — match it against your own records instead of polling GET /calls/{id} to correlate a webhook back to the call you placed. It's null for inbound calls and any call not placed via /calls/initiate.

Headers

Verify the signature — recompute HMAC-SHA256 over the raw request body with your whsec_ secret and compare (constant-time):

import hmac, hashlib

def verify(raw_body, header, secret):
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Delivery: a 2xx marks success. Failures retry up to 5 times (backoff 5s, 30s, 5m, 30m, 2h). An endpoint auto-disables after 10 consecutive failures. The same event may arrive more than once — dedupe on X-Audelo-Delivery.