Chats
Chats are conversations between a user and an agent. Messages stream in real time via WebSocket — see WebSocket for the streaming protocol.
List chats
GET /api/chats
Authorization: Bearer nxr_...Query params:
| Param | Type | Description |
|---|---|---|
page | int | Page number (default: 1) |
page_size | int | Results per page (default: 20) |
search | string | Full-text search across chat titles |
Get chat
GET /api/chats/{chat_id}
Authorization: Bearer nxr_...Create chat
POST /api/chats
Authorization: Bearer nxr_...
Content-Type: application/json
{
"title": "Deploy review",
"agent_id": "uuid",
"project_id": "uuid-optional"
}agent_id is required. title defaults to "New Chat" if omitted.
Update chat
PATCH /api/chats/{chat_id}
Authorization: Bearer nxr_...
Content-Type: application/json
{ "title": "New title" }Archive chat
POST /api/chats/{chat_id}/archive
Authorization: Bearer nxr_...Delete chat
DELETE /api/chats/{chat_id}
Authorization: Bearer nxr_...Messages
List messages
GET /api/chats/{chat_id}/messages
Authorization: Bearer nxr_...Query params:
| Param | Type | Description |
|---|---|---|
before_id | uuid | Cursor — messages before this ID |
limit | int | Max to return (default: 50) |
Send message
Triggers agent response generation. The reply streams via WebSocket.
POST /api/chats/{chat_id}/messages
Authorization: Bearer nxr_...
Content-Type: application/json
{
"content": "Explain this codebase",
"client_message_id": "unique-client-id"
}client_message_id is used for deduplication — safe to retry on network error.
Returns 202 Accepted. Response arrives via WebSocket.
Exclude message from context
Toggle whether a message is included in the agent’s context window:
PATCH /api/chats/{chat_id}/messages/{message_id}/excluded
Authorization: Bearer nxr_...
Content-Type: application/json
{ "excluded": true }Message schema
{
"id": "uuid",
"chat_id": "uuid",
"role": "user | assistant | tool",
"content": "Message text",
"tool_calls": [],
"tool_results": [],
"excluded": false,
"client_message_id": "dedup-key",
"created_at": "2026-01-01T00:00:00Z"
}Files
Attach files to a chat for the agent to reference.
Upload file
POST /api/chats/{chat_id}/files
Authorization: Bearer nxr_...
Content-Type: multipart/form-data
file=@/path/to/file.pdfList files
GET /api/chats/{chat_id}/files
Authorization: Bearer nxr_...Download file
GET /api/chats/{chat_id}/files/{file_id}/content
Authorization: Bearer nxr_...Delete file
DELETE /api/chats/{chat_id}/files/{file_id}
Authorization: Bearer nxr_...Search
Full-text search across chats and messages:
GET /api/search?q=deployment+error
Authorization: Bearer nxr_...Query params:
| Param | Type | Description |
|---|---|---|
q | string | Search query |
chat_id | uuid? | Scope to a specific chat |
For streaming responses you have two options. Connect to the WebSocket endpoint, or use the WebSocket-free SSE streaming endpoint POST /api/chats/{chat_id}/stream, which returns a text/event-stream response. The SSE stream emits stream_start, chunk, tool_call, and error events as the agent generates its reply. The REST send-message endpoint triggers generation but the response arrives over WebSocket only.