> ## 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.

# API v2 Overview

> Introduction to the Chatbase API v2 — a structured, modern REST API for chatting with AI agents and managing conversations.

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

> [!TIP]
>
> Prefer the terminal? Use the [Chatbase CLI](https://chatbase.co/docs/cli/overview.md) for the same API v2 surface from your shell or CI.

> [!WARNING]
>
> 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 exceptions are [Export conversations](https://chatbase.co/docs/api-reference/v2/conversations/export-conversations.md), which returns conversations from **all sources**, including a single conversation when you pass `conversationId`, and [Search conversations](https://chatbase.co/docs/api-reference/v2/conversation-search.md), which searches 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

**1. Get your API key**

1. Go to the [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. Never expose it in client-side code.

**2. Get your Agent ID**

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

**3. Send your first message**

```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?"
  }'
```

**Response:**

```json theme={null}
{
  "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 | Notes |
| - | - | - |
| `GET` | `/api/v2/health` | |
| `GET` | `/api/v2/agents` | |
| `POST` | `/api/v2/agents` | |
| `GET` | `/api/v2/agents/{agentId}` | |
| `PUT` | `/api/v2/agents/{agentId}` | |
| `DELETE` | `/api/v2/agents/{agentId}` | |
| `PUT` | `/api/v2/agents/{agentId}/styles` | |
| `PUT` | `/api/v2/agents/{agentId}/auto-retrain` | (auto-resync schedule) |
| `POST` | `/api/v2/agents/{agentId}/clone` | |
| `POST` | `/api/v2/agents/{agentId}/train` | (deprecated, no-op) |
| `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/search` | |
| `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` | (deprecated, no-op) |

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

| Method | Endpoint | Notes |
| - | - | - |
| `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 (seconds) when the rate limit window resets. |

## Next Steps

> **[Authentication](https://chatbase.co/docs/api-reference/v2/authentication.md)**
>
> API keys, Bearer tokens, and rate limiting

> **[Streaming](https://chatbase.co/docs/api-reference/v2/streaming.md)**
>
> Real-time SSE streaming responses

> **[Error Handling](https://chatbase.co/docs/api-reference/v2/error-handling.md)**
>
> Structured error codes and troubleshooting

> **[Pagination](https://chatbase.co/docs/api-reference/v2/pagination.md)**
>
> Cursor-based pagination for list endpoints


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