Skip to main content
Paid plan required. The Chatbase API v2 is available on paid plans only. View pricing →

​
What is the Chatbase API v2?

The Chatbase API v2 is a redesigned REST API that provides a clean, consistent interface for interacting with your AI agents. It features structured error codes, cursor-based pagination, streaming support via Server-Sent Events, and a predictable response format. Base URL: 
https://www.chatbase.co/api/v2

​
Quick Start

1

Get your API key

  1. Go to the Chatbase Dashboard
  2. Navigate to Workspace Settings → API Keys
  3. Click Create API Key and copy the generated key
Store your API key securely. Never expose it in client-side code.
2

Get your Agent ID

  1. Select your AI Agent in the dashboard
  2. Go to Settings → General
  3. Copy the Agent ID
3

Send your first message

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": "Hello! How can you help me?"
  }'
Response:
{
  "data": {
    "id": "msg_abc123",
    "role": "assistant",
    "parts": [
      { "type": "text", "text": "Hello! I'm here to help. What can I assist you with today?" }
    ],
    "metadata": {
      "userMessageId": "msg_xyz789",
      "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "userId": null,
      "finishReason": "stop",
      "usage": { "credits": 2 }
    }
  }
}

​
Endpoints

MethodEndpoint
GET/api/v2/health
POST/api/v2/agents/{agentId}/chat
POST/api/v2/agents/{agentId}/conversations/{conversationId}/retry
GET/api/v2/agents/{agentId}/conversations
GET/api/v2/agents/{agentId}/conversations/{conversationId}
GET/api/v2/agents/{agentId}/conversations/{conversationId}/messages
GET/api/v2/agents/{agentId}/users/{userId}/conversations
PATCH/api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

​
Response Headers

Every response includes these headers:
HeaderDescription
x-request-idUnique request identifier. Include this when contacting support.
X-RateLimit-LimitMaximum requests allowed in the current window.
X-RateLimit-RemainingRequests remaining in the current window.
X-RateLimit-ResetUnix timestamp (ms) when the rate limit window resets.

​
Next Steps

Authentication

API keys, Bearer tokens, and rate limiting

Streaming

Real-time SSE streaming responses

Error Handling

Structured error codes and troubleshooting

Pagination

Cursor-based pagination for list endpoints