---
title: "Upload agent chat attachments"
method: POST
path: "/agents/{agentKey}/conversations/attachments/upload"
tags: ["Agents"]
---

# Upload agent chat attachments

`POST /agents/{agentKey}/conversations/attachments/upload`

Multipart upload of PDF, JPEG, or PNG files for agent chat. Same limits as assistant
chat (`POST /conversations/attachments/upload`): up to 10 files, 5 MiB each. Proxies to
the AI backend. Optional `conversationId` associates uploads with an existing agent thread.

## Path parameters

- `agentKey` string, required

## Response `200`

Success. The gateway proxies the AI-backend JSON envelope after transforming the multipart upload into the backend attachment payload.

- ChatAttachmentUploadResponse — Success envelope returned by `POST /conversations/attachments/upload` and `POST /agents/{agentKey}/conversations/attachments/upload`.
  - `conversationId` string, nullable, required — Existing conversation id echoed from the request when the upload is tied to a thread; otherwise `null`.
  - `attachments` ChatAttachmentUploadRef[], required
    - `recordId` string, required — Server-assigned attachment record id.
    - `recordName` string, required — Original filename stored for the attachment.
    - `mimeType` string, required — MIME type of the uploaded file.
    - `extension` string, required — File extension derived by the backend.
    - `virtualRecordId` string, required — Synthetic record id used by the graph layer.
    - `ocrMode` string — Optional backend-reported processing mode for the attachment.

## Other responses

- `400` — Invalid `conversationId`, no files, unsupported MIME type (not PDF/JPEG/PNG), or Multer rejection (e.g. file too large).
- `401` — Unauthorized
- `403` — Missing `agent:execute` scope
- `500` — Gateway fallback when the upstream call does not return a status (implementation default).

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)