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

# Chat API

> Call a deployed agent over A2A, keep chat history, attach files, and transcribe speech.

These routes power the dashboard's **Chat** screen and `nasiko chat`. They cover three jobs:

* **Calling a deployed agent.** Send A2A JSON-RPC to `/api/agents/{id}`, and Nasiko forwards it to the agent.
* **Chat history.** Chat sessions and their messages, which Nasiko records as you chat.
* **Attachments and speech.** Upload files to a chat, download files an agent produced, and transcribe audio.

They aren't in the generated OpenAPI spec. To let Nasiko pick the agent, or to run the orchestrator, use `POST /api/orchestrator/a2a` instead. It's in the generated spec under the **orchestrator** tag. Guides: [Chat in the dashboard](https://docs.nasiko.com/dashboard/chat.md), [A2A](https://docs.nasiko.com/build/a2a.md). CLI: [Chat commands](https://docs.nasiko.com/reference/cli/chat.md).

## Authentication

Every route takes a session JWT in `Authorization: Bearer <token>` (from `POST /api/auth/login`) or the dashboard cookie. A missing or expired token returns `401` with `{ "data": null, "status_code": 401, "message": "..." }`.

Chat sessions, messages, and files belong to the user who created them. Another user's session or file reads as `404`, so its existence isn't revealed. Errors on these routes are plain-text or empty bodies.

## Call a deployed agent

`POST /api/agents/{id}`
`<any method> /api/agents/{id}/{path}`

Forwards an A2A request to a deployed agent and returns the agent's answer. `nasiko chat -a <agent>` and direct chat in the dashboard use it. The bare path goes to the agent's A2A endpoint, wherever the agent mounts it. A sub-path is forwarded as-is, so `GET /api/agents/{id}/.well-known/agent-card.json` reads the agent's card.

| Path parameter | Description |
| - | - |
| `id` | The agent's UUID |
| `path` | Optional sub-path forwarded to the agent |

**Request:** an A2A JSON-RPC body, up to 10 MB. The agent decides whether the payload is valid A2A. Nasiko adds chat-session handling to `message/send`, `message/stream`, `SendMessage`, and `SendStreamingMessage`:

* **No `contextId`.** Nasiko generates one (`ses_<hex>`), puts it in the forwarded message, and opens a chat session titled from your first text part.
* **A `contextId` you own.** The message joins that session. Earlier messages in the session can be added to the agent's context.
* **A `contextId` owned by another user.** The request returns `403`.

Your text message and the agent's reply are both saved to the session's history. Read them back with [`GET /api/chat/sessions/{session_id}/messages`](#list-messages).

```bash theme={null}
curl -X POST https://nasiko.example.com/api/agents/8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "messageId": "b7e4c1f0-0a2b-4c3d-8e9f-001122334455",
        "contextId": "ses_4f1d2a9b8c7e6f5a4b3c2d1e0f9a8b7c",
        "parts": [{ "kind": "text", "text": "How do I reset my password?" }]
      }
    }
  }'
```

**Response:** the agent's own response: status, headers, and body. For `message/stream`, the agent's `text/event-stream` is relayed event by event.

When an agent pauses in a stream to ask for approval or input, Nasiko adds one more event after the pause. Its message carries a data part with the request to answer:

```json theme={null}
{ "type": "hitl", "id": "e1f2a3b4-...", "kind": "tool_approval", "task_id": "t-123", "context_id": "ses_4f1d...", "question": "Allow the agent to send this email?" }
```

Answer it with `POST /api/hitl/{id}/resolve`. See [Approvals API](https://docs.nasiko.com/api-reference/approvals.md).

**What the agent receives.** Only `Content-Type`, `Accept`, `Accept-Encoding`, `Accept-Language`, and `A2A-Version` are copied from your request. Your `Authorization` header and cookies are never forwarded. Nasiko adds `traceparent`, `X-User-ID`, `X-Username`, and `X-Is-Superuser`, so the agent knows who is calling.

**Errors**

| Status | When |
| - | - |
| `400` | `id` isn't a UUID, or the body is over 10 MB |
| `403` | The `contextId` belongs to another user, or the request's `traceparent` names another user's flow |
| `404` | The agent doesn't exist, or you can't reach it. A private agent you have no grant for reads as `404` |
| `502` | The agent has no reachable endpoint, or the call to it failed |
| `503` | The agent isn't running. A parked agent is woken first, so `503` means it couldn't be. A `Retry-After` header is set when a retry will succeed |
| `508` | The call would exceed the flow's cascade limits. See [Flow limits](https://docs.nasiko.com/governance/flow-limits.md) |

Agent calls are bounded by the server's agent-call timeout, `AGENT_CALL_TIMEOUT_SECS` (default `600`).

> [!NOTE]
>
> A deployed agent can call another agent at this same path, using its own Nasiko gateway credential and the `traceparent` of the flow it's working in. Those calls run as the user who started the flow, honor the calling agent's [agent grants](https://docs.nasiko.com/api-reference/agent-access.md#allow-calls-to-an-agent), and are rate-limited per calling agent (`AGENT_PEER_CALL_RATE_LIMIT_PER_MINUTE`, default `300`). Over the limit returns `429` with `Retry-After`.

## Chat sessions

A chat session is one conversation, with one agent or with the orchestrator. Sessions are created for you when you message an agent without a `contextId`. You can also create one first.

### The session list item

```json theme={null}
{
  "session_id": "ses_4f1d2a9b8c7e6f5a4b3c2d1e0f9a8b7c",
  "user_id": "3f2a9c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b",
  "agent_id": "8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f",
  "agent_url": "/api/agents/8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f",
  "title": "Resetting a password",
  "session_type": "direct_chat",
  "created_at": "2026-11-14T09:12:03.412Z",
  "updated_at": "2026-11-14T09:13:40.020Z",
  "agent_name": "support-bot",
  "is_coding_agent": false,
  "last_message": "Open Settings, then choose Reset password.",
  "message_count": 4,
  "trace_count": 2,
  "total_tokens": 1830,
  "latency_p50_ms": 1240.5
}
```

| Field | Description |
| - | - |
| `agent_url` | The proxy path to message the session's agent at. `null` for an orchestrator session |
| `session_type` | `direct_chat` (one agent) or `orchestrator` |
| `is_coding_agent` | `true` for a session reported from a coding agent such as Claude Code |
| `last_message` | Text of the newest message that isn't a failed turn |
| `message_count`, `trace_count` | Messages in the session, and distinct traces they belong to |
| `total_tokens` | Tokens across messages that recorded usage, or `null` when none did |
| `latency_p50_ms` | Median reply time across messages that recorded it |

### List chat sessions

`GET /api/chat/sessions`

Your chat sessions, most recently updated first. Includes sessions reported by coding agents. Matches `nasiko sessions`.

| Query parameter | Type | Default | Description |
| - | - | - | - |
| `limit` | integer | `50` | Page size. Values outside `1` to `100` are clamped |
| `cursor` | string | | `next_cursor` from the previous page |
| `agent_id` | UUID | | Only sessions with this agent |
| `surface` | string | | Only sessions belonging to this embedded surface, a lowercase slug of `a-z`, `0-9`, and `-` up to 32 characters. Omit for the general list |

```bash theme={null}
curl "https://nasiko.example.com/api/chat/sessions?limit=20" \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{
  "data": [ { "session_id": "ses_4f1d...", "title": "Resetting a password", "...": "..." } ],
  "has_more": true,
  "next_cursor": "MTczMTU3NTYyMDAyMDAwMDAwMDpzZXNfNGYxZA",
  "prev_cursor": null
}
```

Pass `next_cursor` back as `cursor` until `has_more` is `false`. Paging is forward only. A malformed `surface` returns `400`.

### Create a chat session

`POST /api/chat/sessions`

Creates an empty session, so you can show it before the first reply. Matches `nasiko create-session`.

| Field | Type | Required | Description |
| - | - | - | - |
| `agent_id` | string | No | The agent's UUID or name. Omit it for an orchestrator session. You must be able to reach the agent |
| `first_prompt` | string | No | Your first message. A model writes the session's title from it. Without it, the title is `New chat` |
| `session_id` | string | No | Your own session ID. If you already have a session with this ID, it's returned unchanged with `200` |

```bash theme={null}
curl -X POST https://nasiko.example.com/api/chat/sessions \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "support-bot", "first_prompt": "How do I reset my password?"}'
```

**Response** `201 Created`, or `200 OK` for an existing `session_id` of yours.

```json theme={null}
{
  "data": {
    "session_id": "ses_4f1d2a9b8c7e6f5a4b3c2d1e0f9a8b7c",
    "created_at": "2026-11-14T09:12:03.412Z",
    "title": "Resetting a password",
    "agent_id": "8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f",
    "agent_url": "/api/agents/8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f"
  },
  "status_code": 201,
  "message": ""
}
```

Use `data.session_id` as the A2A `contextId` when you message the agent.

**Errors**

| Status | When |
| - | - |
| `400` | `agent not found` |
| `403` | You can't reach the agent |
| `409` | `session_id already in use` by another user |
| `401` | Your account no longer exists on this server. Sign out and sign in again |

### Get a chat session's messages

`GET /api/chat/sessions/{session_id}`

The session's first messages, oldest first. To page through a long session, use [List messages](#list-messages) instead.

| Query parameter | Type | Default | Description |
| - | - | - | - |
| `limit` | integer | `100` | Messages to return. Values outside `1` to `500` are clamped |

**Response** `200 OK`: `{ "data": [ <message>, ... ] }`. `404` when the session isn't yours.

### Rename a chat session

`PUT /api/chat/sessions/{session_id}`

| Field | Type | Required | Description |
| - | - | - | - |
| `title` | string | No | New title. Omit it to keep the current title |

```bash theme={null}
curl -X PUT https://nasiko.example.com/api/chat/sessions/ses_4f1d2a9b8c7e6f5a4b3c2d1e0f9a8b7c \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Password reset help"}'
```

**Response** `200 OK`

```json theme={null}
{
  "session_id": "ses_4f1d2a9b8c7e6f5a4b3c2d1e0f9a8b7c",
  "user_id": "3f2a9c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b",
  "agent_id": "8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f",
  "agent_url": "/api/agents/8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f",
  "title": "Password reset help",
  "session_type": "direct_chat",
  "created_at": "2026-11-14T09:12:03.412Z",
  "updated_at": "2026-11-14T09:20:11.774Z"
}
```

`404` when the session isn't yours.

### Delete a chat session

`DELETE /api/chat/sessions/{session_id}`

Deletes the session, its messages, and its uploaded files. If it's a [harness session](https://docs.nasiko.com/api-reference/sessions.md), its sandbox is released and the sandbox's credentials are revoked. A turn still running on it ends with an error. A superuser can delete any user's session. Matches `nasiko delete-session`.

**Response** `204 No Content`. `404` when the session doesn't exist or isn't yours.

## Messages

### The message object

```json theme={null}
{
  "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
  "session_id": "ses_4f1d2a9b8c7e6f5a4b3c2d1e0f9a8b7c",
  "external_turn_id": null,
  "role": "assistant",
  "content": "Open Settings, then choose Reset password.",
  "file_parts": null,
  "has_file_parts": false,
  "timestamp": "2026-11-14T09:13:40.020Z",
  "input_tokens": 912,
  "output_tokens": 64,
  "cache_read_tokens": 0,
  "cache_creation_tokens": 0,
  "model": "gpt-4o-mini",
  "duration_ms": 1240,
  "cost_usd": "0.00018",
  "usage_estimated": false,
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "metadata": null
}
```

| Field | Description |
| - | - |
| `role` | `user` or `assistant` |
| `file_parts` | Files attached to the message, or produced by the agent in this turn |
| `has_file_parts` | Whether the message has files |
| Usage fields | Recorded when the message reported usage, otherwise `null` |
| `trace_id` | The trace for this turn. Open it in [Sessions and traces](https://docs.nasiko.com/dashboard/sessions-and-traces.md) |
| `metadata` | Extra data. A failed turn carries `{ "turn_error": { "message", "source" } }` |

### List messages

`GET /api/chat/sessions/{session_id}/messages`

A page of the session's messages, always in chronological order. With no cursor, it returns the newest page. Matches `nasiko history`.

| Query parameter | Type | Default | Description |
| - | - | - | - |
| `limit` | integer | `100` | Page size. Values outside `1` to `500` are clamped |
| `prev_cursor` | string | | Return messages older than this cursor |
| `next_cursor` | string | | Return messages newer than this cursor |
| `before` | RFC 3339 timestamp | | Return messages older than this time. Ignored when `prev_cursor` is set |
| `after` | RFC 3339 timestamp | | Return messages newer than this time. Ignored when `next_cursor` is set |

```bash theme={null}
curl "https://nasiko.example.com/api/chat/sessions/ses_4f1d2a9b8c7e6f5a4b3c2d1e0f9a8b7c/messages?limit=50" \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{
  "data": [ { "id": "6a5b4c3d-...", "role": "user", "content": "How do I reset my password?", "...": "..." } ],
  "has_more": true,
  "next_cursor": "MTczMTU3NTYyMDAyMDAwMDAwMDo2YTViNGMzZC0uLi4",
  "prev_cursor": "MTczMTU3NTUyMzQxMjAwMDAwMDpjMWQyZTNmNC0uLi4",
  "hitl": []
}
```

| Field | Description |
| - | - |
| `has_more` | More messages exist in the direction you're reading. From the newest page, that's older messages |
| `prev_cursor` | Pass back as `prev_cursor` to read the page before this one |
| `next_cursor` | Pass back as `next_cursor` to read forward. Set only when `has_more` is `true` |
| `hitl` | Every approval or input request raised in this session, pending or resolved, in the shape `GET /api/hitl/{id}` returns. Empty if they can't be read |

`404` when the session isn't yours.

### Record a message

`POST /api/chat/sessions/{session_id}/messages`

Adds a message to the session's history. It doesn't call the agent: send A2A to [`/api/agents/{id}`](#call-a-deployed-agent) for that. Use this route when your client talks to an agent some other way and you want the exchange in Nasiko's history, or to attach uploaded files to a message.

| Field | Type | Required | Description |
| - | - | - | - |
| `role` | string | Yes | `user` or `assistant` |
| `content` | string | Yes | Message text |
| `file_ids` | UUID\[] | No | Files uploaded to this session with [Upload files](#upload-files) and not yet attached to a message. Each can be attached once |
| `file_parts` | any JSON | No | Inline file parts to store on the message |
| `usage` | object | No | Usage for an assistant message. Fields: `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens`, `model`, `duration_ms`, `cost_usd`, `estimated`, `trace_id` |
| `error` | object | No | Assistant messages only. `{ "message": "..." }` records the turn as failed. The message is kept up to 4,000 characters |

```bash theme={null}
curl -X POST https://nasiko.example.com/api/chat/sessions/ses_4f1d2a9b8c7e6f5a4b3c2d1e0f9a8b7c/messages \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "Here is the screenshot.",
    "file_ids": ["d4c3b2a1-0f9e-4d8c-b7a6-5f4e3d2c1b0a"]
  }'
```

**Response** `201 Created`: the message object.

For a successful assistant message, Nasiko looks for files the agent wrote to its workspace that the reply refers to, and attaches them as `file_parts`. This is best effort and gives up after 15 seconds. The message is saved either way.

**Errors**

| Status | When |
| - | - |
| `400` | `role` isn't `user` or `assistant`; `error` is set on a user message; or a `file_ids` entry doesn't exist in this session or is already attached |
| `404` | The session isn't yours |

## Files

### Upload files

`POST /api/chat/sessions/{session_id}/files`

Uploads files to a session as `multipart/form-data`. Up to 10 files per request, any field name. Then attach them to a message with `file_ids`.

| File type | Size limit |
| - | - |
| Images and PDFs | 25 MB |
| Text | 1 MB |
| Anything else | 10 MB |

The type is detected from the file's content, not only from its declared type.

```bash theme={null}
curl -X POST https://nasiko.example.com/api/chat/sessions/ses_4f1d2a9b8c7e6f5a4b3c2d1e0f9a8b7c/files \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -F "file=@screenshot.png"
```

**Response** `201 Created`

```json theme={null}
[
  {
    "id": "d4c3b2a1-0f9e-4d8c-b7a6-5f4e3d2c1b0a",
    "message_id": null,
    "session_id": "ses_4f1d2a9b8c7e6f5a4b3c2d1e0f9a8b7c",
    "filename": "screenshot.png",
    "mime_type": "image/png",
    "size_bytes": 184320,
    "storage_uri": "…",
    "created_at": "2026-11-14T09:15:22.001Z"
  }
]
```

`message_id` stays `null` until the file is attached. Don't rely on the format of `storage_uri`.

A failed request uploads nothing: files already stored by that request are removed.

**Errors**

| Status | When |
| - | - |
| `400` | More than 10 files, or a malformed upload |
| `404` | The session isn't yours |
| `413` | A file is over its type's limit. The body names the file and the limit |
| `503` | File storage is unavailable. Try again |

### Download a file

`GET /api/chat/files/{file_id}/download`

Returns a file from one of your sessions: an upload, or a file an agent produced. A superuser can download any user's file.

```bash theme={null}
curl -L -o screenshot.png \
  https://nasiko.example.com/api/chat/files/d4c3b2a1-0f9e-4d8c-b7a6-5f4e3d2c1b0a/download \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `200 OK` with the file's bytes and `Content-Type`. PNG, JPEG, GIF, and WebP images are sent `inline`, and everything else as an `attachment`. The response can also be a `302` redirect to a short-lived download URL, so follow redirects.

**Errors**

| Status | When |
| - | - |
| `404` | No such file, or it isn't in one of your sessions |
| `410` | The file record exists, but its content is gone |
| `503` | File storage is unavailable |

## Transcribe speech

`POST /api/transcribe`

Turns recorded audio into text. The dashboard's dictation button uses it.

Send `multipart/form-data` with the audio in a field named `file`, up to 14 MB. The field's `Content-Type` should be an `audio/*` type. Anything else is treated as `audio/webm`.

If you saved an OpenAI API key in Nasiko, the transcription uses it. Otherwise it's routed through Nasiko's LLM router and attributed to you.

```bash theme={null}
curl -X POST https://nasiko.example.com/api/transcribe \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -F "file=@note.webm;type=audio/webm"
```

**Response** `200 OK`

```json theme={null}
{ "text": "Remind me to reset the staging password tomorrow." }
```

**Errors**

| Status | When |
| - | - |
| `400` | No `file` field, an empty file, or a malformed upload |
| `413` | The audio is over 14 MB |
| `502` | The transcription provider failed or rejected the API key |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.