---
title: "Chat"
description: "Send messages and receive streamed agent responses."
---

## Connect to event stream

Open a persistent SSE connection to receive all events for a session.

```bash
curl -N http://localhost:6877/chat/events/{session_id} \
  -H "Authorization: Bearer $API_KEY"
```

Returns a `text/event-stream` response. See [Streaming](/api-reference/streaming) for event types. The connection stays open with keepalive pings every 5 seconds.

## Send message

Fire-and-forget message send. If an agent is already running, the message is queued for safe injection at the next turn boundary.

<ParamField body="message" type="string" required>
  The user message to send.
</ParamField>

<ParamField body="images" type="array">
  Optional array of image objects to include with the message. Each image has `media_type` (e.g. `image/jpeg`, `image/png`) and `data` (base64-encoded content).
</ParamField>

<ParamField body="session_id" type="string" required>
  Target session ID.
</ParamField>

<ParamField body="skip_approvals" type="boolean" default="false">
  Auto-approve all tool calls.
</ParamField>

```bash
curl -X POST http://localhost:6877/chat/message \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What meetings do I have today?", "session_id": "abc-123"}'
```

With an image:

```bash
curl -X POST http://localhost:6877/chat/message \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is in this image?",
    "session_id": "abc-123",
    "images": [{"media_type": "image/jpeg", "data": "<base64>"}]
  }'
```

```json
{"run_id": "run_abc", "session_id": "abc-123"}
```

The agent response arrives on the SSE event stream.

## Submit tool result

Approve or reject a pending tool call.

```bash
curl -X POST http://localhost:6877/tools/result \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "run_abc",
    "tool_id": "tc_abc123",
    "result": "Approved",
    "approved": true
  }'
```

## Background a run

Move an active agent run into background mode. The UI is unblocked immediately and results are delivered via SSE when complete.

```bash
curl -X POST http://localhost:6877/chat/background \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"run_id": "run_abc"}'
```

## Cancel

Cancel a running agent loop.

```bash
curl -X POST http://localhost:6877/cancel \
  -H "Authorization: Bearer $API_KEY"
```

## Context usage

Get current token usage for the session.

```bash
curl http://localhost:6877/context \
  -H "Authorization: Bearer $API_KEY"
```

```json
{
  "total_tokens": 12500,
  "model_limit": 200000,
  "message_count": 15,
  "tool_count": 8
}
```

## Compact context

Compress conversation history to free token space.

```bash
curl -X POST http://localhost:6877/compact \
  -H "Authorization: Bearer $API_KEY"
```
