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": "Reception Bot", "status": "active",
  "voice": "aria", "language": "en-AU",
  "voice_engine": "deepgram", "deepgram_voice": "aura-2-hyperion-en",
  "humour_level": 10, "empathy_level": 80,
  "created_at": "2026-06-25T10:30:00.000000Z",
  "updated_at": "2026-06-25T10:30:00.000000Z"
}

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 at least one month's wholesale cost 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.