API Documentation

Overview API provides developers with the capability to create and manage telephony applications using AI technology. This API focuses on three main resources: Call, Text, and Agent.



The Call resource allows for managing voice calls.


  • POST /calls - Initiate a new call.
  • PUT /calls/{callId}/hangup - End an active call.
  • POST /calls/{callId}/respond - Send a response to an active call.
  • PUT /calls/{callId}/audio - Inject audio into an active call.
  • PUT /calls/{callId}/route - Route an ongoing call to a different endpoint.


The Text resource facilitates handling SMS messages.


  • Webhooks - [Specify webhook endpoint format] - Receive and respond to texts.


The Agent resource deals with the creation and management of AI agents for voice cloning.


  • POST /agents - Create a new voice agent.
  • PUT /agents/{agentId} - Update an existing agent.
  • POST /agents/{agentId}/persona - Create or update an agent's persona.


To authenticate with the API, you must use a Bearer Authentication token. This token should be included in the Authorization header of your HTTP requests.

Obtaining Access Tokens

To obtain an access token, send an email request to Include your application details and the reason for your token request. Upon approval, you will receive a token that you can use in your API requests.

Using the Token in Requests

Include the obtained Bearer token in the Authorization header of your HTTP requests. Here's an example using the curl command:

curl -X POST '' \
	-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
	-H 'Content-Type: application/json' \
	-d '{ "data": "your_request_data" }'

Error Handling

Understanding and properly handling errors is crucial for a robust integration with the API. The API uses standard HTTP response codes to indicate the success or failure of a request.

Common HTTP Status Codes

  • 200 OK: The request was successful.
  • 400 Bad Request: The request was invalid or cannot be served. Check the message for details.
  • 401 Unauthorized: Authentication failed or user does not have permissions for the requested operation.
  • 403 Forbidden: The request is understood, but it has been refused or access is not allowed.
  • 500 Internal Server Error: An error occurred on the server side.

Handling a 403 Forbidden Error in Python

Below is an example of how to handle a 403 Forbidden error in Python. This code checks the status code of the response and prints a message if a 403 error occurs:

import requests

url = ''
headers = {'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}

response = requests.get(url, headers=headers)

if response.status_code == 403:
	print("Access denied. Check your permissions and token.")
	# Handle other statuses or successful response

Rate Limits

The API enforces rate limits to ensure fair usage and maintain the stability and reliability of the service. These limits are in place to prevent abuse and overload of the system.

Understanding Rate Limits

Rate limits are applied based on the number of requests made within a certain time frame. If you exceed these limits, your requests will be temporarily throttled, and you will receive a 429 Too Many Requests response.

Rate Limit Guidelines

  • Standard Limit: 100 requests per minute per user.
  • Exceeding Limits: If you exceed the rate limit, you must wait until the limit resets before making additional requests.

Monitoring Your Usage

Your current rate limit and remaining requests are communicated via the X-RateLimit-Limit and X-RateLimit-Remaining headers in each API response. It's important to monitor these headers to avoid hitting the rate limit.

Best Practices

To avoid hitting rate limits, consider implementing efficient request strategies such as caching responses where appropriate, staggering requests, and using bulk data endpoints if available.