Skip to main content
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.com/v1/voiceai/agents \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My First Agent",
    "agent_type": "business",
    "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.com/v1

​
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",
  "agent_type": "business",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

​
Error Response

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

​
HTTP Status Codes

CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid input or malformed request
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
422Unprocessable Entity - Validation error
429Too Many Requests - Rate limit exceeded
500Internal 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/voiceai/agents?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

Official SDKs are coming soon:
  • Python SDK - Full-featured Python library
  • JavaScript SDK - Node.js and browser support
  • TypeScript SDK - Type-safe development

​
Need Help?