# Append to a streaming message

`POST /chat.appendStream`

## Description

Append a chunk of text to an open stream (see
[`/chat.startStream`](/docs/api/chat-start-stream)). Each chunk is broadcast
to recipients as a delta, so the message appears to fill in live. Call as
many times as needed before [`/chat.stopStream`](/docs/api/chat-stop-stream).

**Required scope:** `chat:send_message` or `chat:write`

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `streamId` | string | Yes | The stream ID returned by chat.startStream. |
| `text` | string | Yes | Text chunk to append. Required and non-empty. |
| `snapshot` | boolean | No | If `true`, **replace** the accumulated text with `text` (and broadcast it as a full snapshot) instead of appending. Useful when the client holds the canonical current state — for example after rewriti |

### Example Request

```json
{
  "streamId": "018f5c8e-7d2a-7c4e-8f9a-1a2b3c4d5e6f",
  "text": " The answer is 42."
}
```

## Responses

### 200 - Chunk appended.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `streamId` | string | No |  |
| `chatId` | string | No |  |
| `threadTimestamp` | integer | No | Thread timestamp if the stream is a thread reply. |


#### Example Response

```json
{
  "streamId": "018f5c8e-7d2a-7c4e-8f9a-1a2b3c4d5e6f",
  "chatId": "757dfe66-37b4-4772-baa5-8c86ec68c176"
}
```

### 400 - Bad request. Common causes:
- `streamId` missing or not a valid UUID
- `text` missing or empty


### 401 - Presented invalid authentication credentials.

### 403 - The token lacks the required scope (`chat:send_message` or `chat:write`).

### 404 - No active stream with that `streamId` for this app.

### 405 - An unsupported method was requested.

### 413 - Accumulated stream text exceeds the maximum allowed size.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/chat-append-stream*