---
title: "Plan Workspace Uploads"
method: POST
path: "/v1/workspaces/{workspace}/files/upload-urls"
tags: ["v1", "protected", "files"]
---

# Plan Workspace Uploads

`POST /v1/workspaces/{workspace}/files/upload-urls`

Diff a client's ``{path, sha256}`` manifest against workspace storage.

Files already stored under the same digest come back ``unchanged``; the
rest get a presigned PUT bound to their digest, so the bytes go straight to
the object store. This is what ``agentarea files sync`` calls, and the same
plan the MCP ``workspace_files.upload_urls`` tool returns.

## Path parameters

- `workspace` string, required — Slug of the workspace the request acts in

## Request body

- UploadPlanRequest
  - `files` UploadPlanEntry[], required
    - `content_type` string, nullable
    - `path` string, required
    - `sha256` string, required

## Response `200`

Successful Response

- UploadPlanResponse
  - `uploads` PlannedUpload[], required
    - `error` string, nullable
    - `expires_in` integer, nullable
    - `headers` object, nullable
    - `method` string, nullable
    - `path` string, required
    - `status` 'unchanged' | 'upload' | 'error', required
    - `upload_url` string, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-27** `3d0d16868fa4` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/agentarea/apis/agentarea-api/changes/v1/workspaces/:workspace/files/upload-urls/post.md)

---

[API](https://skmtc.dev/agentarea/apis/agentarea-api.md) · [All operations](https://skmtc.dev/agentarea/apis/agentarea-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentarea/apis/agentarea-api/revisions/0c5907c0d7f3?raw)