API v2 Overview - Chatbase

Standard Plan required. The Chatbase API v2 is available starting from the Standard Plan. View pricing →

Most conversation endpoints apply exclusively to conversations created programmatically via the Chatbase API. Conversations generated through the bubble or external integrations cannot be accessed using these endpoints. The exception is the Export conversations endpoint, which returns conversations from all sources.

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

Get your API key

Go to the Chatbase Dashboard
Go to Workspace settings → API keys
Click Create API Key and copy the generated key

Store your API key securely. Never expose it in client-side code.

Get your Agent ID

Select your AI Agent in the dashboard
Go to the agent’s Settings → General
Copy the Agent ID from the Agent details card

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

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

Method	Endpoint
`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/export`
`GET`	`/api/v2/agents/{agentId}/conversations/{conversationId}`
`GET`	`/api/v2/agents/{agentId}/conversations/{conversationId}/messages`
`GET`	`/api/v2/agents/{agentId}/users/{userId}/conversations`
`POST`	`/api/v2/agents/{agentId}/conversations/{conversationId}/tool-result`
`PATCH`	`/api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback`
`GET`	`/api/v2/agents/{agentId}/sources/summary`
`GET`	`/api/v2/agents/{agentId}/sources`
`POST`	`/api/v2/agents/{agentId}/sources`
`GET`	`/api/v2/agents/{agentId}/sources/{sourceId}`
`PUT`	`/api/v2/agents/{agentId}/sources/{sourceId}`
`DELETE`	`/api/v2/agents/{agentId}/sources/{sourceId}`
`POST`	`/api/v2/agents/{agentId}/sources/{sourceId}/restore`

File upload base URL: https://files.chatbase.co/api/v2

Method	Endpoint
`POST`	`/api/v2/agents/{agentId}/sources`
`PUT`	`/api/v2/agents/{agentId}/sources/{sourceId}`

Response Headers

Every response includes these headers:

Header	Description
`x-request-id`	Unique request identifier. Include this when contacting support.
`X-RateLimit-Limit`	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix 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

​What is the Chatbase API v2?

​Quick Start

​Endpoints

​Response Headers

​Next Steps

Authentication

Streaming

Error Handling

Pagination

What is the Chatbase API v2?

Quick Start

Endpoints

Response Headers

Next Steps