API Documentation

Build voice agent workflows programmatically with the AllBots REST API.

Authentication

All API requests require a Bearer token in the Authorization header. Generate an API key from your dashboard under Settings > API Keys.

Request Header

Authorization: Bearer your_api_key_here
Content-Type: application/json

Base URL

https://api.allbots.io/v1

All endpoints are relative to this base URL. HTTPS is required for all requests.

Rate Limits

1,000

Requests per hour

100

Concurrent calls

10 MB

Max request body

Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response. Enterprise plans support custom limits.

Endpoints

Method	Endpoint	Description
GET	/agents	List all voice agents in your account
POST	/agents	Create a new voice agent
GET	/agents/:id	Retrieve a specific agent by ID
PATCH	/agents/:id	Update an existing agent
DELETE	/agents/:id	Delete an agent permanently
POST	/calls	Initiate an outbound call
GET	/calls/:id	Get status and details of a call
GET	/calls	List all calls with optional filters

Examples

Create an Agent

POST /agents — Request

{
  "name": "Front Desk Receptionist",
  "industry": "healthcare",
  "voice": "nova",
  "language": "en-US",
  "greeting": "Thank you for calling. How can I help you today?",
  "instructions": "Handle appointment scheduling, insurance verification, and general inquiries.",
  "transfer_number": "+18015551234",
  "operating_hours": {
    "timezone": "America/Denver",
    "schedule": {
      "mon-fri": "08:00-17:00"
    }
  }
}

201 Created — Response

{
  "id": "agt_8xk2m9f4j1",
  "name": "Front Desk Receptionist",
  "industry": "healthcare",
  "status": "active",
  "phone_number": "+18015559876",
  "created_at": "2026-03-24T14:30:00Z",
  "updated_at": "2026-03-24T14:30:00Z"
}

Initiate an Outbound Call

POST /calls — Request

{
  "agent_id": "agt_8xk2m9f4j1",
  "to": "+18015554321",
  "metadata": {
    "patient_name": "Jane Doe",
    "appointment_type": "follow-up"
  }
}

201 Created — Response

{
  "id": "call_3nq7v2x8p0",
  "agent_id": "agt_8xk2m9f4j1",
  "status": "ringing",
  "to": "+18015554321",
  "direction": "outbound",
  "started_at": "2026-03-24T14:35:00Z",
  "duration": null,
  "recording_url": null,
  "transcript_url": null
}

List Calls

GET /calls?agent_id=agt_8xk2m9f4j1&limit=2 — Response

{
  "data": [
    {
      "id": "call_3nq7v2x8p0",
      "agent_id": "agt_8xk2m9f4j1",
      "status": "completed",
      "to": "+18015554321",
      "direction": "outbound",
      "started_at": "2026-03-24T14:35:00Z",
      "duration": 142,
      "recording_url": "https://api.allbots.io/v1/calls/call_3nq7v2x8p0/recording",
      "transcript_url": "https://api.allbots.io/v1/calls/call_3nq7v2x8p0/transcript"
    }
  ],
  "has_more": false,
  "total": 1
}

Error Codes

Code	Name	Description
400	Bad Request	The request body is missing required fields or contains invalid values.
401	Unauthorized	The API key is missing, expired, or invalid.
403	Forbidden	The API key does not have permission for this operation.
404	Not Found	The requested resource does not exist.
409	Conflict	The resource already exists or a conflicting operation is in progress.
429	Too Many Requests	Rate limit exceeded. Wait and retry with exponential backoff.
500	Internal Server Error	An unexpected error occurred. Contact support if it persists.

Error Response Format

{
  "error": {
    "code": 401,
    "message": "Invalid API key. Check your key at dashboard.allbots.io/settings/api-keys",
    "type": "authentication_error",
    "request_id": "req_a1b2c3d4e5"
  }
}

SDKs

Official client libraries wrap the REST API with idiomatic methods, automatic retries, and type safety.

JavaScript / TypeScript

npm install @allbots/sdk

Python

pip install allbots

Node.js

npm install @allbots/node

Ready to build?

Explore quickstart guides, webhook events, and code samples on the developer page.

Developer Hub