Skip to main content
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, A2A. CLI: Chat commands.

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. 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.
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:
Answer it with POST /api/hitl/{id}/resolve. See Approvals API. 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 Agent calls are bounded by the server’s agent-call timeout, AGENT_CALL_TIMEOUT_SECS (default 600).
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, 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

List chat sessions

GET /api/chat/sessions Your chat sessions, most recently updated first. Includes sessions reported by coding agents. Matches nasiko sessions.
Response 200 OK
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.
Response 201 Created, or 200 OK for an existing session_id of yours.
Use data.session_id as the A2A contextId when you message the agent. Errors

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 instead. Response 200 OK: { "data": [ <message>, ... ] }. 404 when the session isn’t yours.

Rename a chat session

PUT /api/chat/sessions/{session_id}
Response 200 OK
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, 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

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.
Response 200 OK
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} 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.
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

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. The type is detected from the file’s content, not only from its declared type.
Response 201 Created
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

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.
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

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.
Response 200 OK
Errors