API Reference — Samwad Docs

Authentication

Authenticate requests with a Bearer token using an API key from Settings → API Keys. Keys are scoped to your account — keep them server-side and never expose them in client-side code.

Authorization header

Authorization: Bearer sk_live_••••••••••••••••

Rotate a key immediately from the dashboard if you suspect it has leaked. Revoking a key takes effect within seconds.

Base URL & versioning

https://api.samwad.ai/v1

The API is versioned via the URL path (/v1). Breaking changes ship under a new version; additive changes (new optional fields, new endpoints) can land in the current version without notice.

Rate limits

Plan	Requests / minute	Burst
Starter	60	100
Growth	300	500
Enterprise	Custom	Custom

Rate-limited requests return a 429 with a Retry-After header in seconds.

Agents

List agents

GET /v1/agents

curl https://api.samwad.ai/v1/agents \
  -H "Authorization: Bearer $SAMWAD_API_KEY"

Response

{
  "data": [
    {
      "id": "agt_123",
      "name": "Sales Qualifier",
      "status": "live",
      "language": "hi-en",
      "created_at": "2026-06-02T09:12:00Z"
    }
  ],
  "has_more": false
}

Create an agent

POST /v1/agents

curl -X POST https://api.samwad.ai/v1/agents \
  -H "Authorization: Bearer $SAMWAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Qualifier",
    "language": "hi-en",
    "voice_id": "voice_priya"
  }'

Body parameters

namestringrequired

A display name for the agent, shown in the dashboard.

languagestringrequired

Language code the agent speaks by default — hi, en, or hi-en for code-mixed.

voice_idstringoptional

Voice to use. Defaults to the account's default voice if omitted — see available voices in the dashboard.

Calls

Start an outbound call

POST /v1/calls

curl -X POST https://api.samwad.ai/v1/calls \
  -H "Authorization: Bearer $SAMWAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_123",
    "to": "+919876543210"
  }'

Body parameters

agent_idstringrequired

ID of the agent that should place the call.

tostringrequired

Recipient phone number in E.164 format (e.g. +919876543210).

testbooleanoptional

When true, places a test call that doesn't count against your billed minutes.

Retrieve a call

GET /v1/calls/{id}

curl https://api.samwad.ai/v1/calls/call_8f2a1c \
  -H "Authorization: Bearer $SAMWAD_API_KEY"

Response

{
  "id": "call_8f2a1c",
  "agent_id": "agt_123",
  "direction": "outbound",
  "status": "completed",
  "duration_seconds": 142,
  "transcript_url": "https://api.samwad.ai/v1/calls/call_8f2a1c/transcript",
  "recording_url": "https://api.samwad.ai/v1/calls/call_8f2a1c/recording"
}

Webhook events

Event	Fires when
`call.started`	A call connects.
`call.completed`	A call ends normally.
`call.transferred`	The agent hands off to a human.
`call.failed`	A call fails to connect.

See Integrations → Webhooks for a full payload example and setup steps.

Errors

Status	Meaning
400	Malformed request — check required fields.
401	Missing or invalid API key.
403	Key doesn't have access to this resource.
404	Resource not found.
429	Rate limit exceeded.
500	Something failed on our end — safe to retry.