---
title: "Upload a file to a chat's workspace"
method: POST
path: "/api/v2/chats/{chat}/workspace-files"
tags: ["Chats"]
---

# Upload a file to a chat's workspace

`POST /api/v2/chats/{chat}/workspace-files`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/v2/chats/{chat}/workspace-files`
- Auth: API key in header `Coder-Session-Token`

Streams the request body into the chat workspace's
upload directory. The request Content-Type header is
recorded as the file's media type. There is no
server-imposed size cap; client cancellation aborts the
stream and the agent leaves no partial target file behind.

## Path parameters

- `chat` string, uuid, required

## Headers

- `Content-Disposition` string, required

## Request body `*/*`

- string

## Response `201`

Created

- CodersdkUploadChatWorkspaceFileResponse
  - `media_type` string: MediaType is the client-declared content type for display.
  - `name` string: Name is the final basename of the uploaded file.
  - `path` string: Path is the absolute path of the file on the workspace.
  - `size` integer: Size is the number of bytes written to the workspace.
  - `workspace_id` string, uuid: WorkspaceID is the workspace whose filesystem received the bytes. Message parts referencing this upload must carry it.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `409`: Conflict
- `429`: Too Many Requests
- `500`: Internal Server Error
- `502`: Bad Gateway

## Changes

- **2026-09-26** `b8c8996a3706`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/coder/apis/coder-api/changes/api/v2/chats/:chat/workspace-files/post.md)

---

[API](https://skmtc.dev/coder/apis/coder-api.md) - [All operations](https://skmtc.dev/coder/apis/coder-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coder/apis/coder-api/revisions/4669d93796ab?raw)