---
title: "Upload Workspace Files"
method: POST
path: "/workspaces/{workspace_id}/files/upload"
tags: ["Workspaces"]
---

# Upload Workspace Files

`POST /workspaces/{workspace_id}/files/upload`

## Request

- Base URL: `https://api.browser-use.com/api/v4`
- URL: `https://api.browser-use.com/api/v4/workspaces/{workspace_id}/files/upload`
- Auth: API key in header `X-Browser-Use-API-Key`

Presigned PUT URLs for input files, placed under ``uploads/`` in the
workspace. The agent pulls them in at the start of every run. URLs are
pinned to the declared Content-Type and exact Content-Length.

## Path parameters

- `workspace_id` string, uuid, required

## Request body

- WorkspaceFileUploadRequest
  - `files` WorkspaceFileUploadItem[], required
    - `name` string, required: Filename, e.g. "data.csv"
    - `contentType` string: MIME type, e.g. "text/csv"
    - `size` integer, required: Exact file size in bytes; the presigned URL is pinned to it.
  - `allowOverrides` boolean: When false, return 409 before reserving storage if any uploaded filename would replace an existing workspace file.

## Response `200`

Successful Response

- WorkspaceFileUploadResponse
  - `files` WorkspaceFileUploadResponseItem[], required
    - `id` string, uuid, required: Upload id. Pass THIS in RunCreateRequest.attachedFileIds to attach the file to a run.
    - `name` string, required: Original filename from the request
    - `storedName` string, required: Sanitized filename the object is stored under, e.g. "data.csv".
    - `path` string, required: Path within the workspace, e.g. "uploads/data.csv"
    - `willOverride` boolean, required: True if a file with this stored_name already exists in the workspace and uploading will replace it. Surface a warning to the user.
    - `uploadUrl` string, required: Presigned PUT URL (5 min expiry). PUT the file bytes with the matching Content-Type and Content-Length headers.

## Other responses

- `400`: Invalid request (bad session/workspace pairing or file path).
- `403`: Zero Data Retention is enabled on the project (V4 unsupported).
- `404`: Run, session, workspace, or profile not found.
- `409`: One or more files would replace existing workspace files.
- `422`: Validation Error

---

[API](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4.md) · [All operations](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4/llms.txt) · [OpenAPI document](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4/revisions/cd7b1eee1102?raw)