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.
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 inAuthorization: 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
contextIdyou own. The message joins that session. Earlier messages in the session can be added to the agent’s context. - A
contextIdowned by another user. The request returns403.
GET /api/chat/sessions/{session_id}/messages.
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:
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 acontextId. 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.
200 OK
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.
201 Created, or 200 OK for an existing session_id of yours.
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}
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.
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.
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.
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.
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.
200 OK