Skip to main content

Chatbase API: Integration Guide for Developers

· 22 min read
Achraf Bizyane
Software Engineer

The Chatbase API lets your own backend work with a Chatbase AI agent: send messages and stream replies, read and search conversations, manage knowledge sources, create and answer Helpdesk tickets, and start real-time voice sessions. It requires the Standard plan or above: $150/month billed monthly, or $120/month billed annually ($1,440/year), with 4,000 message credits per month that API calls share with the chat widget. Free and Hobby workspaces get a 403. Prices verified on chatbase.co/pricing on 2026-10-04.

Prerequisite: a Standard (or higher) workspace. Compare Chatbase plans with API access, or read our Chatbase pricing breakdown first. Each reply costs credits based on the AI model the agent uses (see Best Practices).

Chatbase ships two REST API versions. API v1 is the original integration path; API v2 is a redesign with structured error codes, cursor-based pagination, Server-Sent Events (SSE) streaming, a cleaner response contract, and endpoints for agents, knowledge sources, the Helpdesk, and voice. This guide covers v2 only, since it is the forward path for new integrations in 2026. The agent you call is the same one you configure in the dashboard, with its knowledge, instructions, actions, and procedures.

Chatbase API at a glance​

ItemDetail
Current versionv2 (v1 is the original integration path)
Base URLhttps://www.chatbase.co/api/v2 (file uploads: https://files.chatbase.co/api/v2)
AuthenticationAuthorization: Bearer YOUR_API_KEY, one key grants access to one workspace
Plan requiredStandard or above ($150/month, or $120/month billed annually)
Cost per reply1 to 6 message credits depending on the model; actions can multiply it
Rate limit100 requests per 10-second sliding window, per API key and IP address
StreamingServer-Sent Events, on by default
PaginationOpaque cursors, limit 1 to 100 (default 20)
No-code alternativeMCP connector for Claude and ChatGPT (details below)

Available Endpoints​

The core chat and conversation endpoints (prefix each path with https://www.chatbase.co):

MethodEndpointDescription
GET/api/v2/healthHealth check (no auth required)
POST/api/v2/agents/{agentId}/chatSend a message, receive a response
POST/api/v2/agents/{agentId}/conversations/{conversationId}/retryRetry the last message in a conversation
GET/api/v2/agents/{agentId}/conversationsList API-created conversations (paginated)
GET/api/v2/agents/{agentId}/conversations/exportExport conversations from all sources (widget, WhatsApp, API) with full message history
GET/api/v2/agents/{agentId}/conversations/searchSearch conversations across all sources
GET/api/v2/agents/{agentId}/conversations/{conversationId}Get a single conversation
GET/api/v2/agents/{agentId}/conversations/{conversationId}/messagesList messages in a conversation
GET/api/v2/agents/{agentId}/users/{userId}/conversationsList conversations for a user
POST/api/v2/agents/{agentId}/conversations/{conversationId}/tool-resultSubmit a client action result
PATCH/api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedbackSubmit message feedback

Beyond chat, v2 also exposes:

AreaEndpointsWhat it does
Agents/api/v2/agents, /api/v2/agents/{agentId} (plus /styles, /auto-retrain, /clone)Create, list, update, clone, and delete AI agents
Sources/api/v2/agents/{agentId}/sources, /api/v2/agents/{agentId}/sources/{sourceId}Manage knowledge sources (text, Q&A, links, files)
Helpdesk/api/v2/agents/{agentId}/helpdesk/tickets and sub-pathsCreate, search, triage, and reply to support tickets
Voice/api/v2/agents/{agentId}/voice/sessionsStart a real-time voice session for your own app
WhatsApp/api/v2/agents/{agentId}/whatsapp/templates, /whatsapp/messages/templateList and send approved WhatsApp templates

Most conversation endpoints only see conversations created through the API. To read widget or WhatsApp conversations, use the export or search endpoints.

Getting your Agent ID​

In the Chatbase dashboard, select your AI agent, go to Settings → General, and copy the Agent ID field.

Getting Your API Key​

  1. Log into the Chatbase dashboard.
  2. Navigate to Workspace Settings → API Keys.
  3. Click Create API Key and copy the generated key.
  4. Store the key in a secrets manager or environment variable. Never commit it to a repository or expose it in client-side code.

Every API key grants full access to its workspace. Treat it with the same care as a database password.

Authentication​

All v2 endpoints (except GET /api/v2/health) require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

The base URL for all v2 requests is:

https://www.chatbase.co/api/v2

File uploads for knowledge sources are the one exception: they go to https://files.chatbase.co/api/v2.

Quick auth test​

The health endpoint does not check your key, so use an authenticated call such as listing your agents:

curl -X GET 'https://www.chatbase.co/api/v2/agents?limit=1' \
-H 'Authorization: Bearer YOUR_API_KEY'

A 200 OK response confirms your key and plan are valid. A 401 means the key is missing or wrong; a 403 with SUBSCRIPTION_API_RESTRICTED_PLAN means the workspace is not on Standard or above.

Sending Your First Chat Message​

The simplest non-streaming request:

curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"message": "What is your return policy?",
"stream": false
}'

Successful response:

{
"data": {
"id": "msg_abc123",
"role": "assistant",
"parts": [
{
"type": "text",
"text": "Our return policy allows returns within 30 days of purchase..."
}
],
"metadata": {
"userMessageId": "msg_xyz789",
"conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"userId": null,
"finishReason": "stop",
"usage": { "credits": 2 }
}
}
}

The conversationId in the response metadata is the key to multi-turn conversations. Pass it back in subsequent requests to maintain context. The usage.credits field tells you what this reply cost, which varies with the model the agent uses and with any actions it ran.

Multi-turn conversation​

curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"message": "What if the item is damaged?",
"conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"stream": false
}'

Omit conversationId to start a new conversation thread. You can also pass a userId on a new conversation to tie it to one of your users; once set, it cannot be changed.

Streaming Responses with SSE​

For production UIs, streaming delivers a far better perceived response time: text arrives as the model generates it rather than after the full response is ready. Chatbase v2 streaming uses Server-Sent Events over a regular HTTP response with Content-Type: text/event-stream. Each event is a data: line carrying a JSON object with a type field.

Set "stream": true (this is the default) in the request body:

// Node.js streaming example
const response = await fetch(
`https://www.chatbase.co/api/v2/agents/${agentId}/chat`,
{
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
message: "Summarize your product features",
stream: true,
conversationId: existingConversationId, // omit for new conversation
}),
}
);

const reader = response.body.getReader();
const decoder = new TextDecoder();
let conversationId = null;

while (true) {
const { done, value } = await reader.read();
if (done) break;

const lines = decoder.decode(value, { stream: true }).split("\n");
for (const line of lines) {
if (!line.startsWith("data: ")) continue;
const data = line.slice("data: ".length);
if (data === "[DONE]") continue;

const event = JSON.parse(data);
switch (event.type) {
case "text-delta":
// Stream text to your UI
process.stdout.write(event.delta);
break;
case "finish":
conversationId = event.messageMetadata.conversationId;
console.log(`\nCredits used: ${event.messageMetadata.usage.credits}`);
break;
case "error":
console.error("Stream error:", event.errorText);
break;
}
}
}

SSE event types​

Event typeDescription
startSignals the start of a new message; includes messageId
text-start / text-endOpen and close a text block
text-deltaA text chunk from the model; concatenate event.delta to build the full response
tool-input-availableA client action has been invoked with full input object
tool-output-availableResult of a tool call with full output object
start-step / finish-stepStep lifecycle markers for multi-step reasoning
finishStream complete; carries finishReason (stop, tool-calls, or error) and messageMetadata with conversationId, userId, and usage.credits
message-metadataOptional mid-stream metadata under a messageMetadata key; expect the final values on finish
errorError from the model or API; check errorText

The stream terminates with data: [DONE].

Cursor-Based Pagination​

List endpoints (conversations, messages, sources, tickets) use cursor-based pagination. Cursors are opaque, base64-encoded strings. Treat them as tokens; do not parse them.

Parameters​

ParameterTypeDefaultDescription
cursorstring—Cursor from a previous response; omit to start from the beginning
limitinteger20Items per page. Range: 1–100

Response shape​

{
"data": [...],
"pagination": {
"cursor": "eyJpZCI6Im1zZ19hYmMxMjMifQ==",
"hasMore": true,
"total": 347
}
}

pagination.cursor is null and hasMore is false when you have reached the last page.

Paginating through all conversations​

import requests

def fetch_all_conversations(agent_id: str, api_key: str) -> list:
conversations = []
cursor = None
base_url = f"https://www.chatbase.co/api/v2/agents/{agent_id}/conversations"
headers = {"Authorization": f"Bearer {api_key}"}

while True:
params = {"limit": 100}
if cursor:
params["cursor"] = cursor

response = requests.get(base_url, headers=headers, params=params)
response.raise_for_status()
payload = response.json()

conversations.extend(payload["data"])
pagination = payload["pagination"]

if not pagination["hasMore"]:
break
cursor = pagination["cursor"]

return conversations

Note on message pagination: The messages endpoint paginates backward from the newest message. The first page contains the most recent messages; passing cursor fetches the next older page. Within each page, messages are returned in chronological (oldest → newest) order.

Rate Limiting​

The API enforces 100 requests per 10-second sliding window, scoped per API key and IP address.

Every response includes these rate limit headers:

HeaderDescription
X-RateLimit-LimitMaximum requests in the window (100)
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp (ms) when the window resets
Retry-AfterSeconds to wait before retrying (only on 429 responses)

Handling 429 responses​

import time
import requests
from requests.exceptions import HTTPError

def chat_with_backoff(agent_id, api_key, message, max_retries=5):
url = f"https://www.chatbase.co/api/v2/agents/{agent_id}/chat"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
payload = {"message": message, "stream": False}

for attempt in range(max_retries):
response = requests.post(url, json=payload, headers=headers)

if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
print(f"Rate limited. Retrying in {retry_after}s...")
time.sleep(retry_after)
continue

response.raise_for_status()
return response.json()

raise Exception("Max retries exceeded")

Always log the x-request-id header from failed requests. Chatbase support asks for it when you report an error.

Helpdesk API: Tickets and Human Handoff​

Chatbase includes a built-in Helpdesk (Standard plan and up): a shared ticket inbox across the chat bubble, email, WhatsApp, and the API, with assignment, triage, internal notes, and the ability for a human to take over an AI conversation. On the agent side, the Chatbase live chat action hands a conversation to a human in real time (the AI stops, the customer stays in the widget, and a teammate replies live), while the Escalations action opens a ticket for follow-up.

The Helpdesk API is the same ticketing system, exposed under /api/v2/agents/{agentId}/helpdesk/. You can create tickets on behalf of customers, list and search them, change status, assignee, team, or priority, and post replies. Tickets are numbered per agent, and tickets created through the API carry channel: "api".

Create a ticket from your own app or backend:

curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/helpdesk/tickets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"subject": "Export failing with 500",
"description": "Customer cannot export orders since this morning.",
"customer": { "email": "jane@example.com", "name": "Jane Doe" },
"priority": "high"
}'

If you omit an assignee and team, the agent's routing rules pick both. Then triage with PATCH /helpdesk/tickets/{ticketNumber} (for example {"statusCategory": "on_customer", "priority": "urgent"}) and reply with POST /helpdesk/tickets/{ticketNumber}/messages:

curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/helpdesk/tickets/42/messages' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"type": "reply",
"content": "Thanks for reaching out. This is **fixed** now.",
"authorEmail": "sam@example.com"
}'

Replies are Markdown, attributed to a team member, and delivered over the ticket's original channel. A 201 means the reply was recorded; delivery is asynchronous. If the ticket is linked to a live conversation the AI is still handling, you get 409 CONVERSATION_NOT_TAKEN_OVER until someone takes it over in the dashboard.

Voice Sessions API​

Chatbase agents can also hold real-time voice conversations (Standard plan and up), on the website widget, over the phone through Twilio or your own SIP trunk, and inside your own app through the Voice Sessions API. The voice agent uses the same training data and actions as chat, and a "Transfer to phone number" action can forward a live call to a human.

To embed voice in your app, your backend creates a session and passes the result to the client:

curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/voice/sessions' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"userId": "user_abc123",
"timezone": "Europe/Paris"
}'

The response data contains a short-lived participantToken, a sessionId, maxDurationSeconds, and the conversationId. Hand that object to the browser and join with the Chatbase Voice SDK (npm install @chatbase-co/voice-sdk):

import { ChatbaseVoice } from "@chatbase-co/voice-sdk";

// Your backend proxies the create call and returns the session `data`
const { data } = await fetch("/your-backend/voice-session").then((r) => r.json());

const voice = new ChatbaseVoice();
voice.on("agentState", (state) => console.log("agent is", state));
voice.on("transcript", ({ segmentId, speaker, text }) => console.log(`[${speaker}] ${text}`));

await voice.connect(data); // microphone goes live; the agent greets and listens

Keep the API key on the server: the endpoint sends no CORS headers, so browser calls are rejected by design. Never cache the session response, because each token is valid for one session only. Voice minutes consume message credits, the same as widget voice sessions, and session limits (concurrency, per user, hourly, daily) come from the agent's voice settings.

Can Claude or ChatGPT use Chatbase through MCP?​

Yes. Chatbase's changelog entry of September 23 added an MCP connector for Claude and ChatGPT. It is a remote MCP server, not a REST endpoint, so you add it as a connector in the AI client instead of writing integration code:

https://mcp.chatbase.co/api/mcp

What the changelog confirms:

  • Access granted to the connector expires after 90 days, so plan to reconnect.
  • Delete and export capabilities are off by default.

The changelog does not state a plan requirement or a full tool list, so confirm both in your account before building a workflow around it. MCP suits ad-hoc work from a chat assistant; the REST API remains the path when your own product needs to send messages, sync sources, or handle tickets.

Piping Apify-Scraped Content into Chatbase​

One of the most powerful developer workflows is combining Apify's web scraping infrastructure with Chatbase's knowledge base to keep your AI agent current with live website content. This is the foundation of any solid data-for-AI RAG pipeline. If your knowledge lives in videos rather than web pages, the same Sources API pattern lets you sync a YouTube channel into Chatbase with a timestamped link for every section.

The workflow​

  1. Scrape your documentation, product pages, or help center using Apify's Website Content Crawler
  2. Clean the output: strip navigation, footers, and boilerplate
  3. Format as plain text or Markdown
  4. Upload to Chatbase via the Sources API

Step 1: Run the Apify scraper​

Using the Apify API to trigger a crawl:

import requests

APIFY_API_TOKEN = "your_apify_token"
actor_id = "apify~website-content-crawler"

run_input = {
"startUrls": [{"url": "https://docs.yoursite.com"}],
"maxCrawlDepth": 3,
"maxCrawlPages": 100,
"outputFormats": ["markdown"],
}

response = requests.post(
f"https://api.apify.com/v2/acts/{actor_id}/runs",
json=run_input,
params={"token": APIFY_API_TOKEN},
)
run = response.json()
run_id = run["data"]["id"]
print(f"Crawl started: {run_id}")

See the full scrape website content guide for crawler configuration options.

Step 2: Retrieve the scraped content​

import time

def wait_for_run(run_id: str, token: str) -> list:
while True:
status_resp = requests.get(
f"https://api.apify.com/v2/actor-runs/{run_id}",
params={"token": token},
)
status = status_resp.json()["data"]["status"]
if status == "SUCCEEDED":
break
time.sleep(5)

dataset_resp = requests.get(
f"https://api.apify.com/v2/actor-runs/{run_id}/dataset/items",
params={"token": token, "format": "json"},
)
return dataset_resp.json()

Step 3: Upload to Chatbase​

The v2 Sources API (Standard plan and up) lets you add and update text, Q&A, and link sources on your agent's knowledge base. A text source takes a name (up to 100 characters) and content (up to 1 MB of text). Concatenate the cleaned page content and create the source the first time, then update the same source on later runs so you do not pile up duplicates:

CHATBASE_BASE = "https://www.chatbase.co/api/v2"

def upsert_text_source(agent_id: str, api_key: str, text_content: str, source_name: str):
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}

# Look for an existing text source with this name
existing = requests.get(
f"{CHATBASE_BASE}/agents/{agent_id}/sources",
headers=headers,
params={"type": "text", "name": source_name, "limit": 100},
)
existing.raise_for_status()
match = next((s for s in existing.json()["data"] if s["name"] == source_name), None)

if match:
response = requests.put(
f"{CHATBASE_BASE}/agents/{agent_id}/sources/{match['id']}",
json={"content": text_content},
headers=headers,
)
else:
response = requests.post(
f"{CHATBASE_BASE}/agents/{agent_id}/sources",
json={"type": "text", "name": source_name, "content": text_content},
headers=headers,
)
response.raise_for_status()
return response.json() # includes the source id and its training status

# Build the corpus from Apify output
pages = wait_for_run(run_id, APIFY_API_TOKEN)
corpus = "\n\n---\n\n".join(
page.get("markdown", page.get("text", ""))
for page in pages
if page.get("markdown") or page.get("text")
)

# A text source holds up to 1 MB; split into several named sources if you exceed it
upsert_text_source(agent_id=CHATBASE_AGENT_ID, api_key=CHATBASE_API_KEY, text_content=corpus, source_name="docs-crawl")

Sources train on write in v2: creating or updating a source starts training immediately, and there is no separate retrain call to make. Poll GET /agents/{agentId}/sources/{sourceId} until status reads trained (or failed). An update to a source that is still training returns 409 SOURCE_IS_TRAINING, so wait and retry. Run the crawler weekly (or on every deployment) and push the updated corpus, and your agent stays synchronized with your latest documentation. If your content is already public and you only need Chatbase to re-crawl it, a link source with auto-retrain enabled is the simpler route; the Apify pipeline earns its keep when you need to clean, filter, or merge content before it reaches the agent.

Best Practices​

Scope credit consumption. Every reply costs message credits, and the cost depends on the model. Chatbase's Auto model and economical models such as GPT-5 Mini, Claude 4.5 Haiku, and Gemini 3 Flash cost 1 credit per reply; mid-tier models cost 2 to 4; Claude Opus models cost 5 to 6. When an agent runs actions, one user message can trigger several model requests, so it can cost two or more times the base rate. In practice, Standard's 4,000 monthly credits cover about 4,000 replies on a 1-credit model but only about 2,000 on a 2-credit model, and fewer with actions. Use a 1-credit model for straightforward FAQ lookups, reserve premium models for queries that need deeper reasoning, and track the usage.credits value returned on every response to catch unexpected consumption. Subscription credits reset on the 1st of each calendar month and do not roll over; auto-recharge credits ($40 per 1,000) do not expire. Compare Chatbase plans and credit allowances to size the plan to your traffic.

Persist conversation IDs. Store the conversationId from the first API response in your session layer. Passing it on follow-up messages gives the agent context from the entire session, dramatically improving multi-turn accuracy.

Stream in production. Non-streaming requests return nothing until the whole answer is generated, which is noticeable on long answers. SSE streaming shows the first words as soon as the model produces them.

Separate API keys per environment. Create distinct API keys for development, staging, and production workspaces. This isolates credit consumption and prevents test traffic from polluting production analytics.

Log x-request-id headers. Every response includes a unique request ID. Capture it in your application logs. When something goes wrong, this ID is the fastest path to resolution with Chatbase support.

Start building with the Chatbase API​

Build your first Chatbase agent free, then upgrade to Standard when you need an API key. Chatbase fits best when you want a managed AI agent with knowledge, actions, Helpdesk, and voice already wired together. If you would rather own the conversation logic in code, a developer-first framework like Botpress is the better fit; see Chatbase vs Botpress. For the wider picture, read our Chatbase review and verdict, compare Chatbase vs Voiceflow for visual flow building, or browse Chatbase alternatives.

How we researched this: endpoints, error codes, and limits were checked against Chatbase's API v2 reference (chatbase.co/docs), plan prices and credits against chatbase.co/pricing, and the MCP connector against chatbase.co/changelog, on 2026-10-04. We did not run load or latency tests.

Frequently Asked Questions

API access starts on the Standard plan: $150/month billed monthly, or $120/month billed annually ($1,440/year). Standard includes 4,000 message credits per month, and API calls draw from the same pool. Free and Hobby accounts receive a 403 Forbidden error (SUBSCRIPTION_API_RESTRICTED_PLAN) even with a valid API key.

API v1 is Chatbase's original integration path. API v2 is a redesign with structured error codes, cursor-based pagination, Server-Sent Events streaming, and a cleaner response contract, and it adds endpoints for agents, knowledge sources, Helpdesk tickets, and voice sessions. All v2 requests go to https://www.chatbase.co/api/v2 with a Bearer API key. Use v2 for any new integration.

It depends on the model. Chatbase's Auto model and economical models such as GPT-5 Mini or Claude 4.5 Haiku cost 1 credit per reply, mid-tier models cost 2 to 4, and Claude Opus models cost 5 to 6. Agents that run actions can make several model requests per message, which multiplies the cost. Every API response reports the exact figure in usage.credits.

The API enforces 100 requests per 10-second sliding window, scoped per API key and IP address. When you hit the limit, you receive a 429 status code with a Retry-After header indicating how many seconds to wait before retrying.

Most v2 conversation endpoints, including the list endpoint, only return conversations created through the API. Chats from the website widget, WhatsApp, and other channels are not in that list. To read them, call GET /api/v2/agents/{agentId}/conversations/export, which exports conversations from all sources with full message history, or the conversations search endpoint, which searches across all sources.

Yes. A September 23 changelog entry added an MCP connector for Claude and ChatGPT at https://mcp.chatbase.co/api/mcp. Access expires after 90 days, and delete and export capabilities are off by default. The changelog does not state a plan requirement, so confirm availability in your account. For integrations inside your own product, the REST API v2 remains the main path.

Capture the conversationId from the first API response's metadata object and pass it in the conversationId field of all subsequent requests to the same conversation thread. Omitting conversationId starts a fresh conversation with no prior context.

Yes. Set stream: true in the request body (it is the default) to receive responses as Server-Sent Events. Each event is a data: line carrying a JSON object with a type field, and the stream ends with data: [DONE]. The text-delta event carries text chunks; the finish event carries the finish reason plus messageMetadata with the conversationId and credit usage.

Yes. The v2 Sources API (Standard plan and up) creates, updates, and deletes text, Q&A, link, and file sources on an agent's knowledge base. Sources start training as soon as you write them, with no separate retrain call. This is the foundation for automated pipelines that pull fresh content from Apify crawls and push it into Chatbase without manual dashboard updates.

Yes, on the Standard plan and up. Agents can hold real-time voice conversations on the widget, over the phone, or in your own app via the Voice Sessions API (POST /api/v2/agents/{agentId}/voice/sessions plus the Chatbase Voice SDK). For handoff, the built-in Helpdesk lets a human take over a conversation live through the Chatbase live chat action, and the Helpdesk API lets you create, triage, and reply to tickets programmatically.

List endpoints return a pagination object with cursor, hasMore, and total fields. Pass the cursor value from one response as the cursor parameter in the next request to fetch the next page. When hasMore is false, you have reached the end of the list. Cursors are opaque tokens, so do not decode or construct them manually.

Common mistakes and fixes

Getting 401 Unauthorized on every API request.

Verify your Authorization header uses the format 'Bearer YOUR_API_KEY' with a capital B. API keys are scoped to the workspace, so make sure you are using the key from the correct workspace.

Receiving 403 Forbidden when calling API v2 endpoints.

API access requires the Standard plan or above ($150/month, or $120/month billed annually). Free and Hobby accounts are rejected with a 403 and the error code SUBSCRIPTION_API_RESTRICTED_PLAN, even with a valid key. Voice session calls can also return 403 VOICE_NOT_AVAILABLE or INSUFFICIENT_CREDITS.

Rate limit 429 errors during high-volume requests.

The API enforces 100 requests per 10-second sliding window per API key and IP address. Read the Retry-After header on 429 responses and implement exponential backoff. For bulk operations, batch your requests and space them out.

Streaming SSE response is not arriving as expected.

Read the response as a stream (fetch with a ReadableStream, or requests with stream=True). Each event is a line that starts with 'data: ' followed by a JSON object with a 'type' field. Strip the 'data: ' prefix before parsing, skip the final 'data: [DONE]' line, and read conversationId and credit usage from the 'finish' event's messageMetadata.

Advertise on this page