API Reference

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:

cURL

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:

x-api-key: YOUR_API_KEY

Get your API key from the ThreeTone Dashboard.

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:

{
  "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

{
  "id": "agent_abc123xyz",
  "name": "Example Agent",
  "created_at_unix": 1713528000
}

Error Response

{
  "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

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "base64_encoded_cursor",
    "total_count": 150
  }
}

Using Pagination

Use the cursor and limit query parameters:

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 for detailed setup instructions.

SDKs and Libraries

Use the REST-first guides today:

Python - Production-ready Python examples with requests
JavaScript - Fetch-based Node.js integrations
TypeScript - Typed API wrappers and examples

Need Help?

Developer Guides: Step-by-step integration guides
Support: Contact our support team
Community: Join our developer community

Agents Platform

Widget

Tools

Conversations

Batch Calling

Outbound Calls

Knowledge Base

Voices

Phone Numbers

Quick Start

Core Concepts

Voice Agents

Conversations

Knowledge Base

Phone Integration

Base URL

Authentication

Request Format

Headers

Request Body

Response Format

Success Response

Error Response

HTTP Status Codes

Paginated Response

Rate Limits

Webhooks

SDKs and Libraries

Need Help?

​Quick Start

​Core Concepts

​Voice Agents

​Conversations

​Knowledge Base

​Phone Integration

​Base URL

​Authentication

​Request Format

​Headers

​Request Body

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Pagination

​Paginated Response

​Using Pagination

​Rate Limits

​Webhooks

​SDKs and Libraries

​Need Help?

Quick Start

Core Concepts

Voice Agents

Conversations

Knowledge Base

Phone Integration

Base URL

Authentication

Request Format

Headers

Request Body

Response Format

Success Response

Error Response

HTTP Status Codes

Pagination

Paginated Response

Using Pagination

Rate Limits

Webhooks

SDKs and Libraries

Need Help?