# API v2 overview

> The modern Bookbag REST surface: AI-SDK-style chat and streaming, cursor pagination, rate-limit headers, request ids, and machine-readable error codes.

API v2 is the recommended surface for new integrations. It is a clean REST API rooted at `https://app.bookbag.ai/api/v2`, authenticated with the same `Bearer oc_...` keys, and shaped for the modern streaming chat clients (AI SDK style).

## What's different from v1

- **Envelopes** — successful reads return `{ data }` or `{ data, pagination }`; errors return `{ error: { code, message } }`.
- **Cursor pagination** — list endpoints take `limit` (1–100, default 20) and an opaque `cursor`, and return `pagination: { cursor, hasMore, total }`.
- **Rate-limit headers** — every response carries `X-RateLimit-*` headers; 100 requests / 10s per key.
- **Request ids** — every response includes `x-request-id`.
- **Machine error codes** — stable `code` values like `RESOURCE_NOT_FOUND` and `VALIDATION_INVALID_BODY`.
- **End-user identity** — pass your own `userId` on chat to group a person's conversations.

## Resources

| Method | Path | Purpose |
| --- | --- | --- |
| GET | /api/v2/health | Liveness check (no auth). |
| POST | /api/v2/agents/:agentId/chat | Send a message; stream or JSON reply. |
| GET | /api/v2/agents/:agentId/conversations | List conversations (paged). |
| GET | /api/v2/agents/:agentId/conversations/:conversationId | Get a conversation + messages (paged). |
| GET | /api/v2/agents/:agentId/conversations/:conversationId/messages | List messages in a conversation. |
| GET | /api/v2/agents/:agentId/users/:userId/conversations | List one end-user's conversations. |
| GET | /api/v2/agents/:agentId/conversations/export | Export all conversations with messages. |
| POST | /api/v2/agents/:agentId/conversations/:conversationId/retry | Re-run the last user turn. |
| POST | /api/v2/agents/:agentId/conversations/:conversationId/tool-result | Submit a client-side tool result. |
| PATCH | /api/v2/agents/:agentId/conversations/:conversationId/messages/:messageId/feedback | Set thumbs up/down feedback. |

## Identifiers

Message ids are returned as strings prefixed with `msg_` (e.g. `msg_789`). Conversation ids are numeric strings. Conversation `status` is mapped to `ongoing` (bot), `taken_over` (escalated), or `ended` (resolved). Timestamps are Unix seconds.

## Health check

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

- [Streaming format](/docs/api/v2/streaming) — The text-delta / [DONE] SSE protocol and how to parse it.
- [Chat with an agent](/docs/api/v2/chat) — Send messages, continue conversations, identify users.
- [List conversations](/docs/api/v2/conversations) — Cursor pagination, messages, exports, feedback, retry.