DocsOverview

Oxumi API · v1

Put an agent on the phone from your own code.

Ask for a phone call and one of your agents places it, follows its flow and collects the answers. When the call ends, the outcome, the validated fields and the transcript are posted to your webhook.

At a glance

Base URL

http://localhost:4000/v1
JSON in, JSON out. Ids are UUIDs; times are ISO 8601, UTC.

Auth header

Authorization: Bearer ox_live_…
A project key, created in the app. More

Rate limit

120 requests / minute
Per key. Headers say what is left. More

Webhook signature

Oxumi-Signature: t=…,v1=…
HMAC-SHA256 of the raw body. More

First call in five minutes

A phone call is one request from you and one webhook back. In between, the call moves through three statuses.

  1. POST /v1/calls

    You ask for a call

  2. ringing

    202 returned

  3. in_progress

    The agent runs the flow

  4. ended

    Outcome and fields stored

  5. call.completed

    Posted to your webhook

  1. Connect what a call needsIn the app, under Integrations: a telephony provider (Twilio or Exotel), a speech provider (ElevenLabs or Sarvam) and a language-model provider.
  2. Create a key and a webhookBoth on the project's API page. See Authentication.
  3. Find a ready agentGET /v1/agents lists them. Take the id of one with ready: true.
  4. Place the callSend the agent, the number and the flow's variables, as on the right. The response is 202 as soon as the phone rings. Place a call
  5. Receive and verify the resultA signed call.completed event arrives at your webhook when the call ends. Receive the result
POST /v1/callscURL
curl --fail-with-body "http://localhost:4000/v1/calls" \  -X POST \  -H "Authorization: Bearer $OXUMI_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "agentId": "81ee2426-7abe-444b-96f8-b8e195ddde49",    "to": "+919876543210",    "variables": {      "driver_name": "Ramesh",      "company": "Shakti Logistics",      "route": "Nagpur to Hyderabad",      "planned_eta": "tonight at 9 pm"    },    "metadata": {      "trip_id": "TRIP-2291"    }  }'
202ResponseExample
{  "id": "0b9f6c1e-52a7-4d1c-9b6e-3f2a8d4c7e10",  "projectId": "bf98c165-b0d8-4006-91b9-0c97df86ba15",  "agentId": "81ee2426-7abe-444b-96f8-b8e195ddde49",  "channel": "phone",  "model": "anthropic:claude-haiku-5-5",  "variables": {    "driver_name": "Ramesh",    "company": "Shakti Logistics",    "route": "Nagpur to Hyderabad",    "planned_eta": "tonight at 9 pm"  },  "fields": {},  "outcome": null,  "status": "ringing",  "error": null,  "to": "+919876543210",  "metadata": {    "trip_id": "TRIP-2291"  },  "telephony": "twilio",  "providerCallId": "CA5f0c2b6d1e9a4c7f8b3d2e1a0c9f8e7d",  "startedAt": "2026-10-12T14:02:11.412Z",  "endedAt": null}

Where to go next

Authentication Keys, the bearer header, rotation.Place a call Variables, metadata, what happens when nobody answers.Receive the result The payload, signatures, retries.Text conversations The same flow over typed messages.Errors Every status the API returns.Rate limits The limit, its headers, 429.API reference Nine endpoints and five objects.Versioning What v1 means today.

What to know first

Phone calls need connected providersWithout telephony, speech and a model provider, placing a call returns 400 and nothing is dialled.
API conversations are textConversations exchange typed messages. Voice over the API is the phone call.
Hanging up works with Twilio onlyExotel calls end at the flow's time limit.
Some state lives in one server's memoryRate-limit counters and conversations in progress are per server instance; a restart loses them.
Call it from your serverThe API does not allow cross-origin browser requests, and a key in a browser is a leaked key.
No SDKs, and an early buildSamples use each language's standard HTTP client. v1 may still change.