Introduction

Developer-first API for Human-Like Voice AI

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:

https://api.getbutter.ai

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.

Response Format

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

ID Format

All resource IDs follow a consistent format with a prefix and 12+ hexadecimal characters:

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.