> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuralcleave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat API

> Send messages to NeuralCleave and receive LLM replies.

## POST /chat

Send a message and receive a synchronous reply.

```bash theme={null}
curl -X POST http://localhost:7432/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the capital of France?",
    "session_id": "default"
  }'
```

**Request body**

| Field           | Type    | Required | Description                                     |
| --------------- | ------- | -------- | ----------------------------------------------- |
| `message`       | string  | Yes      | The user message                                |
| `session_id`    | string  | No       | Session identifier (default: `"default"`)       |
| `system_prompt` | string  | No       | Override the system prompt for this request     |
| `stream`        | boolean | No       | Stream the reply via WebSocket (default: false) |

**Response**

```json theme={null}
{
  "reply": "Paris.",
  "session_id": "default",
  "tokens_in": 12,
  "tokens_out": 3,
  "provider": "openai",
  "model": "gpt-4o-mini"
}
```

## GET /sessions

List active sessions.

```bash theme={null}
curl http://localhost:7432/api/v1/sessions
```

```json theme={null}
{
  "sessions": [
    { "id": "default", "message_count": 42, "last_active": "2026-08-08T14:22:00Z" }
  ]
}
```

## DELETE /sessions/{session_id}

Clear a session's conversation history.

```bash theme={null}
curl -X DELETE http://localhost:7432/api/v1/sessions/default
# { "cleared": true }
```

## WebSocket streaming

Connect to `ws://localhost:7432/ws` and send:

```json theme={null}
{ "type": "chat", "message": "Hello", "session_id": "default" }
```

Receive frames:

```json theme={null}
{ "type": "message_chunk", "text": "Hello" }
{ "type": "message_chunk", "text": " there" }
{ "type": "message_done", "text": "Hello there!" }
```

## POST /chat/canvas

Send a message and request a structured output (canvas render).

```bash theme={null}
curl -X POST http://localhost:7432/api/v1/chat/canvas \
  -H "Content-Type: application/json" \
  -d '{ "message": "Show me a bar chart of monthly sales", "session_id": "default" }'
```

The response includes `canvas_data` when the LLM produces chart-compatible output:

```json theme={null}
{
  "reply": "Here is your bar chart.",
  "canvas_data": {
    "type": "bar",
    "labels": ["Jan", "Feb", "Mar"],
    "values": [100, 150, 120]
  }
}
```