# Chat with an agent (v1)

> POST /api/v1/chat — the public, SSE-streamed chat runtime. Send a message to an agent and stream back tokens, citations, and a done frame.

## POST /api/v1/chat

The public chat runtime. This is the endpoint the deployed website widget uses. It accepts a single message for an agent and **streams the reply over Server-Sent Events (SSE)**. For new server-to-server integrations prefer [API v2 chat](/docs/api/v2/chat), which has a richer streaming format, rate-limit headers, and machine error codes.

> **AUTH:** This endpoint is keyed by `agentId` in the body and is reachable by the public widget runtime. When calling it server-side, send your `Authorization: Bearer oc_...` key as well.

### Request body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| agentId | integer | Yes | Positive integer. The agent to chat with. |
| message | string | Yes | 1–8000 characters. |
| conversationId | integer | No | Continue an existing conversation. Omit to start a new one. |
| model | string | No | Per-request model override (max 120 chars). Falls back to the agent's saved model. |

### SSE response

On success the response is `text/event-stream`. Each frame is a named SSE `event` with a JSON `data` payload. Expect `token` frames as the answer streams, optional `citations`, a terminal `done`, and `error` if something fails mid-stream.

```bash
curl -N https://app.bookbag.ai/api/v1/chat \
  -H "Authorization: Bearer $BOOKBAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": 123, "message": "Where is my order?" }'
```

### Status codes

| Status | Meaning |
| --- | --- |
| 200 | Stream opened. Frames follow as `text/event-stream`. |
| 400 | Validation failed (e.g. missing `message`). Body: `{ success:false, error:{ code:"validation_error", message, details } }`. |
| 404 | Agent not found or archived. Body: `{ success:false, error:{ code:"agent_not_found", message } }`. |

Errors before the stream opens are JSON. After the stream opens, a failure arrives as an `event: error` frame. See [Errors](/docs/api/errors).