> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threetone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API reference for ThreeTone Voice AI Platform

The ThreeTone API provides a simple, RESTful interface to state-of-the-art voice AI capabilities. Build intelligent voice agents, manage conversations, integrate knowledge bases, and handle phone interactions with our comprehensive API.

## Quick Start

Get started with a simple API call to create your first voice agent:

```bash cURL theme={null}
curl --request POST \
  --url https://api.threetone.in/v1/convai/agents/create \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My First Agent",
    "system_prompt": "You are a helpful assistant."
  }'
```

## Core Concepts

### Voice Agents

Create and manage AI-powered voice agents that can handle conversations, access knowledge bases, and integrate with phone systems.

### Conversations

Track and analyze voice interactions with detailed conversation management, including transcripts, sentiment analysis, and performance metrics.

### Knowledge Base

Provide context and intelligence to your agents by uploading documents, adding URLs, or creating custom content repositories.

### Phone Integration

Connect your voice agents to phone systems for inbound and outbound call handling with advanced routing and queue management.

## Base URL

All API requests should be made to:

```
https://api.threetone.in
```

## Authentication

All requests must include your API key in the `x-api-key` header:

```bash theme={null}
x-api-key: YOUR_API_KEY
```

Get your API key from the [ThreeTone Dashboard](https://threetone.in/app/voice-ai).

## Request Format

### Headers

All requests must include:

* **Content-Type**: `application/json`
* **x-api-key**: `YOUR_API_KEY`

### Request Body

Request bodies should be valid JSON:

```json theme={null}
{
  "name": "Example Agent",
  "agent_type": "business",
  "system_prompt": "You are a helpful assistant."
}
```

## Response Format

All responses are returned in JSON format with appropriate HTTP status codes.

### Success Response

```json theme={null}
{
  "id": "agent_abc123xyz",
  "name": "Example Agent",
  "created_at_unix": 1713528000
}
```

### Error Response

```json theme={null}
{
  "detail": "Error message describing what went wrong",
  "error_code": "VALIDATION_ERROR",
  "field_errors": {
    "name": ["This field is required"]
  }
}
```

## HTTP Status Codes

| Code | Description                                      |
| ---- | ------------------------------------------------ |
| 200  | Success - Request completed successfully         |
| 201  | Created - Resource created successfully          |
| 400  | Bad Request - Invalid input or malformed request |
| 401  | Unauthorized - Invalid or missing API key        |
| 403  | Forbidden - Insufficient permissions             |
| 404  | Not Found - Resource doesn't exist               |
| 422  | Unprocessable Entity - Validation error          |
| 429  | Too Many Requests - Rate limit exceeded          |
| 500  | Internal Server Error - Server error             |

## Pagination

List endpoints support cursor-based pagination for efficient data retrieval:

### Paginated Response

```json theme={null}
{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "base64_encoded_cursor",
    "total_count": 150
  }
}
```

### Using Pagination

Use the `cursor` and `limit` query parameters:

```bash theme={null}
GET /v1/convai/agents/list?cursor=base64_encoded_cursor&limit=20
```

## Rate Limits

The API implements rate limiting to ensure fair usage:

* **Standard**: 100 requests per minute
* **Burst**: 1000 requests per hour
* **Headers**: Rate limit information is included in response headers

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

## Webhooks

Receive real-time notifications about events in your ThreeTone account:

* **Call Events**: call\_started, call\_ended, call\_transferred
* **Agent Events**: agent\_available, agent\_busy, agent\_offline
* **System Events**: system\_error, maintenance\_scheduled

See the [Webhooks Guide](/guides/phone-integration/webhooks) for detailed setup instructions.

## SDKs and Libraries

Use the REST-first guides today:

* **[Python](/sdks/python)** - Production-ready Python examples with `requests`
* **[JavaScript](/sdks/javascript)** - Fetch-based Node.js integrations
* **[TypeScript](/sdks/typescript)** - Typed API wrappers and examples

## Need Help?

* **Developer Guides**: [Step-by-step integration guides](/guides/authentication)
* **Support**: [Contact our support team](mailto:support@threetone.com)
* **Community**: [Join our developer community](https://github.com/ThreeToneAI)