Message reference
Reference for the roles, statuses, and content fields returned on every conversation message in Nairi's REST API. Useful when parsing agent replies.
Reference data for the role and status fields returned by the message endpoints.
Roles
| Role | Description |
|---|---|
user | Messages sent by the API caller (your prompts) |
assistant | Responses from the agent |
system | System notifications, including error messages from nairid |
progress | Intermediate streaming events emitted by the agent. The content field is a JSON envelope ({"job_id":"...","progress_type":"text","text_delta":"..."}); the most commonly needed fields are also surfaced at the top level (see Progress message fields). Most callers can skip these. |
Statuses
| Status | Description |
|---|---|
queued | Message is waiting to be processed (no agent available yet) |
pending | Message is being processed by an agent |
completed | Message has been processed successfully |
failed | Message processing failed. Check for a sibling system message for details. |
Attachments
Messages may include an optional attachment_ids array. On user messages it echoes the IDs you sent in conversations/start or conversations/{job_id}/continue. On assistant messages it lists files the agent produced in reply. The field is omitted when there are no attachments. Fetch the bytes via GET /api/public/v1/attachments/{id}.
Cost and token usage
assistant messages may also include the cost and token counts the agent reported for that turn:
| Field | Type | Description |
|---|---|---|
cost_usd | number | Total cost of the turn in US dollars (10-decimal precision) |
input_tokens | integer | Input tokens billed for this turn |
output_tokens | integer | Output tokens generated this turn |
cache_read_tokens | integer | Tokens served from the prompt cache |
cache_write_tokens | integer | Tokens written into the prompt cache |
model | string | Model identifier the agent used (e.g. claude-opus-4-7) |
All six fields are omitted when the agent did not report usage data. Claude Code and OpenCode harnesses populate them; the Cursor harness does not. Older messages produced before this field was added also have no cost data and omit them.
Progress message fields
For convenience, progress messages surface the most commonly needed fields from the JSON content envelope at the top level of the response, so you don't have to parse the blob yourself to correlate a tool_use event with its tool_result.
| Field | Type | Description |
|---|---|---|
progress_type | string | The kind of progress event. One of text (text delta from the agent), tool_use (a tool call), tool_heartbeat (long-running tool still alive), step (intermediate reasoning step), or subagent (delegated subagent activity). |
tool_name | string | Name of the tool the agent is invoking (e.g. Bash, Read, Edit). Present on tool_use and tool_heartbeat events. |
tool_use_id | string | Stable ID for a single tool call. Match this against the tool_use_id on later events to follow a call through running → completed / error. |
parent_tool_use_id | string | When a tool is invoked from within another tool (e.g. a subagent invoking its own tools), this points at the outer tool's tool_use_id. |
tool_status | string | Lifecycle status of the tool call. One of running, completed, or error. |
All five fields use omitempty — they're absent on non-progress messages and on progress events that don't carry them (for example a text progress event has only progress_type). The full payload (including text_delta, tool_input, tool_output, etc.) is still available inside the content JSON envelope for callers that need it.
List for agent
Returns the conversations (jobs) belonging to a specific Nairi agent, with filtering by status and standard pagination. Useful for activity dashboards.
Overview
Upload files to Nairi via the REST API and read back any files the agent returns. Two-step flow: upload to get an attachment_id, then reference it in messages.