Welcome to the Butter AI API reference. Our API is designed to be intuitive, allowing you to manage AI agents, telephony, and business knowledge with simple HTTP requests.
Base URL
All API requests should be made to:
Core Concepts
The API is organized around several key resources:
- Agents: The brain of your application. Configure LLMs, voices, and personalities.
- Phone Numbers: Buy or import numbers from Twilio or SIP providers to route calls.
- Calls: Initiate outbound calls or track inbound call lifecycle events.
- Knowledge Base: Manage the documents (RAG) that your agents reference during calls.
- Tools: Define custom API endpoints that agents can call to perform actions.
All responses are returned in standard JSON format using a three-tier envelope system:
Single Entity (GET by ID)
{
"success": true,
"data": {
"id": "agent_a1b2c3d4e5f6",
"agent_name": "Sales Rep"
}
}
Paginated List (GET list)
{
"success": true,
"data": [
{ "id": "agent_a1b2c3d4e5f6", "agent_name": "Sales Rep" },
{ "id": "agent_b2c3d4e5f6a7", "agent_name": "Support Agent" }
],
"pagination": {
"next_cursor": "eyJpZ...",
"has_more": true,
"page_size": 20,
"total_count": 100
}
}
Action Result (POST/PUT/DELETE)
{
"success": true,
"message": "Agent created successfully",
"data": {
"id": "agent_a1b2c3d4e5f6",
"agent_name": "Sales Rep"
}
}
| Resource | Prefix | Example |
|---|
| Agent | agent_ | agent_a1b2c3d4e5f6 |
| Call | call_ | call_b2c3d4e5f6a7 |
| Phone Number | phon_ | phon_c3d4e5f6a7b8 |
| Tool | tool_ | tool_d4e5f6a7b8c9 |
| Document | doc_ | doc_e5f6a7b8c9d0 |
| Integration | intg_ | intg_f6a7b8c9d0e1 |
Rate Limiting
The Butter AI API enforces rate limits based on your subscription tier. If you exceed these limits, the API will return a 429 Too Many Requests status code.
| Tier | Rate Limit |
|---|
| Starter | 10 requests per second |
| Pro | 50 requests per second |
| Enterprise | Custom |
If you are planning a high-volume outbound campaign, please contact our support team to ensure your rate limits are increased accordingly.
