API Reference

Complete reference documentation for all API endpoints.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: YOUR-API-KEY-HERE

Base URL

All API requests should be made to:

https://api.example.com/v1

Endpoints

Create Batch

Create a new batch of phone calls.

Endpoint: POST /batches

Request Body:

{
	"base_prompt": "string",
	"call_data": [
		{
			"phone_number": "string",
			"business": "string"
		}
	],
	"label": "string",
	"voice_id": 0,
	"max_duration": 10
}

Response:

{
	"message": "success",
	"batch_id": "string"
}

Get Batch Status

Retrieve the status of a batch.

Endpoint: GET /batches/{batch_id}

Response:

{
	"batch_id": "string",
	"status": "completed",
	"total_calls": 100,
	"completed_calls": 95,
	"failed_calls": 5
}

List Batches

List all batches for your account.

Endpoint: GET /batches

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Results per page (default: 20)

Response:

{
	"batches": [
		{
			"batch_id": "string",
			"label": "string",
			"status": "completed",
			"created_at": "2024-01-01T00:00:00Z"
		}
	],
	"total": 100,
	"page": 1,
	"limit": 20
}

Error Responses

All errors follow this format:

{
	"error": {
		"code": "ERROR_CODE",
		"message": "Human-readable error message"
	}
}

Common Error Codes

• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Missing or invalid API key
• 404 Not Found: Resource not found
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Rate Limits

API requests are rate-limited to 100 requests per minute per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response.

Webhooks

You can configure webhooks to receive real-time notifications about your batch calls. See the Webhooks documentation for more information.