# API reference overview

> The Bookbag HTTP API: a Chatbase-compatible v1 surface (chat, conversations, leads, contacts) and a modern AI-SDK-style v2. Base URL, versions, conventions, and where to start.

The Bookbag API lets you build directly on the same engine that powers your agents — send messages, read conversations, manage contacts, and capture leads from your own backend. Everything is plain JSON over HTTPS and authenticated with an API key.

> **BASE URL:** All endpoints are served under `https://app.bookbag.ai`. For example, the v2 chat endpoint is `https://app.bookbag.ai/api/v2/agents/{agentId}/chat`.

## Two API surfaces

Bookbag exposes two versioned surfaces. They share the same API keys and the same agents — pick the one that fits your integration.

| Surface | Use it for | Style |
| --- | --- | --- |
| **API v1** | Chatbase-compatible integrations: contacts, custom attributes, the legacy chat stream, conversations, and leads. | Chatbase-shaped envelopes: `{ message, data, pages }`. |
| **API v2** | New integrations. Modern REST with an AI-SDK-style streaming format, cursor pagination, rate-limit headers, and machine-readable error codes. | Envelopes: `{ data }` / `{ data, pagination }` / `{ error }`. |

In every endpoint the **chatbot / agent id is the same thing** — your agent's numeric id. v1 paths call it `chatbotId` (Chatbase parity); v2 paths call it `agentId`.

## Conventions

- All requests use TLS. Send `Authorization: Bearer oc_...` on every authenticated call.
- Request and response bodies are JSON. Send `Content-Type: application/json` on `POST`, `PATCH`, and `PUT`.
- Timestamps in v1 contacts and all of v2 are **Unix seconds**. Internal dashboard reads use millisecond strings — the documented public fields use seconds.
- Every v2 response includes an `x-request-id` header. Include it when contacting support about a specific call.

## A first request

The health check needs no authentication and is the quickest way to confirm connectivity:

```bash
curl https://app.bookbag.ai/api/v2/health
```

## Where to go next

- [Authentication](/docs/api/authentication) — Create an API key and authenticate your requests.
- [Errors](/docs/api/errors) — The shared error envelope and the common codes.
- [API v2 overview](/docs/api/v2/overview) — The modern surface — chat, streaming, conversations.
- [REST API integration guide](/docs/developers/api-integration) — A narrative walkthrough of building on the API.