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.
Attachments are a two-step flow: upload bytes to get an ID, then reference that ID by including it in a conversations/start or conversations/{job_id}/continue request. The agent receives the files alongside the prompt. Any files the agent produces in reply are surfaced the same way — as IDs on the assistant message, which you fetch back via the GET endpoint.
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /api/public/v1/attachments | Upload a file (multipart). Returns an attachment_id. |
GET | /api/public/v1/attachments/{id} | Fetch an attachment's metadata + bytes (base64-encoded). |
Limits
- Max file size: 50 MB per attachment.
- Max attachments per message: 10 referenced IDs.
- Org-scoped: an attachment can only be referenced or fetched by the org that uploaded it.
Sending attachments with a prompt
POST /api/public/v1/attachmentsfor each file → record the returnedattachment_idvalues.- Include them as
attachment_ids: [...]in yourconversations/startorconversations/{job_id}/continuerequest body.
The IDs must be valid ULIDs (att_...). Invalid IDs or IDs belonging to a different org are rejected with 400 before the message is created.
Reading attachments from an agent reply
When you fetch a message via GET /api/public/v1/messages/{message_id} or GET /api/public/v1/conversations/{job_id}/messages, any attachments the agent emitted appear as an attachment_ids array on the message. Call GET /api/public/v1/attachments/{id} on each one to download the bytes.
The download response embeds the file as a base64-encoded data field on the JSON body, so you don't need a separate streaming endpoint. Decode it once and write to disk.