InuL Voice API

Stable versioned HTTP API (v1) for external systems. Authenticate with a tenant API key from Settings → API.

Authentication

Send Authorization: Bearer inul_live_… on every request. Keys are shown once at creation and stored as SHA-256 hashes.

Response envelope

// Success
{ "ok": true, "data": { … }, "meta": { "request_id": "req_…", "version": "v1" } }

// Error
{ "ok": false, "error": { "code": "unauthorized", "message": "…" }, "meta": { "request_id": "req_…", "version": "v1" } }

Rate limiting

100 requests per minute per API key. Exceeding the limit returns 429 with error.code = rate_limited and a Retry-After header.

Endpoints

GET/api/v1/calls

List calls for the authenticated tenant.

Permission: read_calls · Query: status, from, to, limit

Example request

curl -s -H "Authorization: Bearer inul_live_…" \
  "https://YOUR_HOST/api/v1/calls?status=completed&limit=20"

Example response

{
  "ok": true,
  "data": {
    "calls": [
      {
        "sid": "CAxxxx",
        "status": "completed",
        "from": "+9198…",
        "to": "+1650…",
        "duration_seconds": 95,
        "summary": "Caller asked about pricing."
      }
    ],
    "count": 1
  },
  "meta": { "request_id": "req_…", "version": "v1" }
}

GET/api/v1/calls/{sid}

Call detail including transcript turns.

Permission: read_calls

Example request

curl -s -H "Authorization: Bearer inul_live_…" \
  "https://YOUR_HOST/api/v1/calls/CAxxxx"

Example response

{
  "ok": true,
  "data": {
    "call": {
      "sid": "CAxxxx",
      "status": "completed",
      "transcript": [{ "role": "user", "text": "Hello" }],
      "script": "Customer: Hello\nAssistant: …",
      "summary": "…"
    }
  },
  "meta": { "request_id": "req_…", "version": "v1" }
}

POST/api/v1/calls/outbound

Place an outbound Twilio call.

Permission: place_calls · Body: { "to": "+919876543210", "caller_name": "optional" }

Example request

curl -s -X POST -H "Authorization: Bearer inul_live_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"+919876543210"}' \
  "https://YOUR_HOST/api/v1/calls/outbound"

Example response

{
  "ok": true,
  "data": {
    "call": { "sid": "CAxxxx", "status": "queued", "to": "+919876543210", "from": "+1650…" }
  },
  "meta": { "request_id": "req_…", "version": "v1" }
}

GET/api/v1/documents

List knowledge-base documents.

Permission: read_documents

Example request

curl -s -H "Authorization: Bearer inul_live_…" \
  "https://YOUR_HOST/api/v1/documents"

Example response

{
  "ok": true,
  "data": { "documents": [{ "id": "…", "filename": "faq.pdf", "status": "ready" }], "count": 1 },
  "meta": { "request_id": "req_…", "version": "v1" }
}

POST/api/v1/documents

Upload a document (multipart file or JSON text).

Permission: manage_documents · Body: multipart field "file" — or JSON { "filename", "content"|"text", "language?" }

Example request

curl -s -X POST -H "Authorization: Bearer inul_live_…" \
  -F "file=@faq.pdf" \
  "https://YOUR_HOST/api/v1/documents"

Example response

{
  "ok": true,
  "data": { "document": { "id": "…", "filename": "faq.pdf", "status": "ready" } },
  "meta": { "request_id": "req_…", "version": "v1" }
}

DELETE/api/v1/documents/{id}

Delete a document and its vectors.

Permission: manage_documents

Example request

curl -s -X DELETE -H "Authorization: Bearer inul_live_…" \
  "https://YOUR_HOST/api/v1/documents/DOC_ID"

Example response

{
  "ok": true,
  "data": { "deleted": true, "id": "DOC_ID" },
  "meta": { "request_id": "req_…", "version": "v1" }
}

GET/api/v1/usage

Usage summary (calls, minutes, estimated cost).

Permission: read_usage · Query: from, to (YYYY-MM-DD)

Example request

curl -s -H "Authorization: Bearer inul_live_…" \
  "https://YOUR_HOST/api/v1/usage?from=2026-07-01&to=2026-07-31"

Example response

{
  "ok": true,
  "data": {
    "from": "2026-07-01",
    "to": "2026-07-31",
    "total_calls": 42,
    "total_minutes": 118.5,
    "estimated_cost_usd": 7.29
  },
  "meta": { "request_id": "req_…", "version": "v1" }
}

POST/api/v1/campaigns

Create an outbound campaign (optional contacts).

Permission: manage_campaigns · Body: { "name", "contacts": [{ "phone", "name?" }], "status?": "draft"|"running" }

Example request

curl -s -X POST -H "Authorization: Bearer inul_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"July outreach","contacts":[{"phone":"+9198…","name":"Asha"}]}' \
  "https://YOUR_HOST/api/v1/campaigns"

Example response

{
  "ok": true,
  "data": {
    "campaign": { "id": "…", "name": "July outreach", "status": "draft", "contact_count": 1 }
  },
  "meta": { "request_id": "req_…", "version": "v1" }
}

GET/api/v1/campaigns/{id}

Campaign status and contact progress.

Permission: read_campaigns

Example request

curl -s -H "Authorization: Bearer inul_live_…" \
  "https://YOUR_HOST/api/v1/campaigns/CAMPAIGN_ID"

Example response

{
  "ok": true,
  "data": {
    "campaign": { "id": "…", "status": "running", "dialed": 3, "connected": 2 },
    "contacts": [{ "phone": "+91…", "status": "connected", "attempts": 1 }]
  },
  "meta": { "request_id": "req_…", "version": "v1" }
}