> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Integration

> Complete guide to integrating Chatbase AI Agents using the Chatbase API v2 for custom integrations and applications.

> [!NOTE]
>
> **Basic Plan required.** The Chatbase API v2 is available starting from the Basic Plan. [View pricing →](https://www.chatbase.co/pricing)

## Overview

The Chatbase REST API enables you to integrate AI-powered conversations into any application or workflow. Build custom chat experiences, automate customer interactions, and manage your AI agents programmatically.

API v2 features structured error codes, cursor-based pagination, and real-time streaming via Server-Sent Events (SSE).

**Base URL:**

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

> **Send Messages**
>
> Chat with your AI agents and handle real-time streaming responses

> **Manage AI Agents**
>
> Create, configure, and update AI agents and their training sources

> **Access Data**
>
> Retrieve conversations and messages from your AI interactions

## Quick Start

**1. Get Your API Key**

![Creating API key in Chatbase dashboard](https://mintcdn.com/chatbase/-HHbinxDlwZUQ3Jt/developer-guides/images/api-integration/create-api-key.png?fit=max\&auto=format\&n=-HHbinxDlwZUQ3Jt\&q=85\&s=b612070a227667e9fd54a4047bcf2f9e)

1. Visit your [Chatbase Dashboard](https://www.chatbase.co/dashboard)
2. Go to **Workspace settings** → **API keys**
3. Click **Create API Key** and copy the generated key

> [!WARNING]
>
> Store your API key securely and never expose it in client-side code.

**2. Get Your Agent ID**

![Finding Agent ID in Chatbase settings](https://mintcdn.com/chatbase/-HHbinxDlwZUQ3Jt/developer-guides/images/api-integration/get-agent-id.png?fit=max\&auto=format\&n=-HHbinxDlwZUQ3Jt\&q=85\&s=8c6dd8d9516be295e68c89746b973c8a)

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

**3. Send Your First Message**

Test your integration with a simple chat request:

```bash theme={null}
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?",
    "stream": false
  }'
```

**Expected Response:**

```json theme={null}
{
  "data": {
    "id": "msg_abc123",
    "role": "assistant",
    "parts": [
      { "type": "text", "text": "Hello! I'm here to help answer your questions and assist with any information you need. What can I help you with today?" }
    ],
    "metadata": {
      "userMessageId": "msg_xyz789",
      "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "userId": null,
      "finishReason": "stop",
      "usage": { "credits": 2 }
    }
  }
}
```

> [!NOTE]
>
> `stream` defaults to `true` in API v2. Set it to `false` to receive the complete message as a single JSON response.

**4. Continue the Conversation**

Conversation history is stored by Chatbase — you don't need to resend previous messages. Pass the `conversationId` from the previous response to send a follow-up:

```bash theme={null}
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": "Tell me more about your pricing.",
    "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "stream": false
  }'
```

To associate a new conversation with one of your users, pass a `userId` on the first message. See [User Conversations](https://chatbase.co/docs/api-reference/v2/user-conversations.md) for details.

### Chat API Streaming

The [chat API](https://chatbase.co/docs/api-reference/v2/agents/chat-with-an-agent.md) streams responses in real time using Server-Sent Events. Each event is a `data:` line containing a JSON object with a `type` field, and the stream ends with `data: [DONE]`. Concatenate the `text-delta` events to build the full reply, and read the `conversationId` from the `finish` event to continue the conversation.

```javascript Node.js theme={null}
// streamer.js (Node.js 18+)

const apiKey = '<Your-Secret-Key>'
const agentId = '<Your Agent ID>'
const apiUrl = `https://www.chatbase.co/api/v2/agents/${agentId}/chat`

async function readAgentReply() {
  const response = await fetch(apiUrl, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      message: '<Your query here>',
      stream: true,
      // conversationId: '<Conversation ID>', // omit to start a new conversation
    }),
  })

  if (!response.ok) {
    const { error } = await response.json()
    throw new Error(`${error.code}: ${error.message}`)
  }

  const reader = response.body.getReader()
  const decoder = new TextDecoder()
  let buffer = ''
  let conversationId

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

    buffer += decoder.decode(value, { stream: true })
    const lines = buffer.split('\n')
    buffer = lines.pop() // keep any incomplete line for the next chunk

    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':
          process.stdout.write(event.delta)
          break
        case 'finish':
          conversationId = event.messageMetadata.conversationId
          break
        case 'error':
          console.error('\nStream error:', event.errorText)
          break
      }
    }
  }

  console.log('\nConversation ID:', conversationId)
}

readAgentReply().catch((error) => console.log('Error:', error.message))
```

```python Python theme={null}
## streamer.py

import json
import requests

api_key = '<Your-Secret-Key>'
agent_id = '<Your Agent ID>'
api_url = f'https://www.chatbase.co/api/v2/agents/{agent_id}/chat'

def read_agent_reply():
    try:
        headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

        data = {
            'message': '<Your query here>',
            'stream': True,
            # 'conversationId': '<Conversation ID>',  # omit to start a new conversation
        }

        response = requests.post(api_url, json=data, headers=headers, stream=True)
        response.raise_for_status()

        conversation_id = None
        for line in response.iter_lines(decode_unicode=True):
            if not line or not line.startswith('data: '):
                continue
            payload = line[len('data: '):]
            if payload == '[DONE]':
                continue

            event = json.loads(payload)
            if event['type'] == 'text-delta':
                print(event['delta'], end='', flush=True)
            elif event['type'] == 'finish':
                conversation_id = event['messageMetadata']['conversationId']
            elif event['type'] == 'error':
                print(f"\nStream error: {event['errorText']}")

        print(f'\nConversation ID: {conversation_id}')

    except requests.exceptions.RequestException as error:
        print('Error:', error)

read_agent_reply()
```

> [!TIP]
>
> For the full list of stream events — including client action (tool call) events — see the [Streaming guide](https://chatbase.co/docs/api-reference/v2/streaming.md).

## Error Handling

API v2 returns structured errors with a machine-readable `code`:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_TOO_MANY_REQUESTS",
    "message": "Too many requests, please try again later"
  }
}
```

Every response includes an `x-request-id` header — include it when contacting support. See [Error Handling](https://chatbase.co/docs/api-reference/v2/error-handling.md) for all error codes and [Rate Limiting](https://chatbase.co/docs/api-reference/v2/authentication.md#rate-limiting) for limits and retry guidance.

## Performance Best Practices

> [!TIP]
>
> **Optimization Strategies:**
>
> * Use streaming for chat responses to improve perceived performance
> * Reuse `conversationId` for follow-ups instead of starting new conversations
> * Cache AI agent responses when appropriate
> * Respect the `Retry-After` header when you receive a `429` response
> * Use cursor-based [pagination](https://chatbase.co/docs/api-reference/v2/pagination.md) when listing conversations, messages, or sources

## 🚀 Try It Live!

Ready to see the magic in action? Dive straight into our interactive playground where you can test every API endpoint, experiment with real responses, and build your integration in real-time.

> **[🎮 Launch Interactive Playground](https://chatbase.co/docs/api-reference/v2/agents/chat-with-an-agent.md)**
>
> Test APIs instantly • No setup required • Real-time responses • Copy working code snippets

### Key API Endpoints

> **[Chat API](https://chatbase.co/docs/api-reference/v2/agents/chat-with-an-agent.md)**
>
> Send messages and receive AI responses with streaming support

> **[AI Agent Management](https://chatbase.co/docs/api-reference/v2/agents/create-agent.md)**
>
> Create, update, and configure AI agents programmatically

> **[Conversations](https://chatbase.co/docs/api-reference/v2/conversations/list-conversations.md)**
>
> Access chat history and conversation messages

> **[Sources](https://chatbase.co/docs/api-reference/v2/sources/create-source.md)**
>
> Add and manage the training sources for your AI agents

> **[API v2 Overview](https://chatbase.co/docs/api-reference/v2/overview.md)**
>
> Explore the full API v2 reference — authentication, streaming, client actions, pagination, and more


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.