---
title: "Upload File"
method: PUT
path: "/filesystems/{filesystem_id}/file-upload"
tags: ["Filesystems"]
---

# Upload File

`PUT /filesystems/{filesystem_id}/file-upload`

Upload a single file into a filesystem by relative path. Defaults to overwrite mode; conditional mode can be used for strict concurrency control.

## Path parameters

- `filesystem_id` string, required

## Query parameters

- `path` string, required — Relative path to write.
- `writeMode` 'overwrite' | 'conditional' — Single-file upload write semantics.
- `baseVersion` string, nullable — Required in conditional mode: expected current archive version.
- `expectedVersion` string, nullable — Conditional replace precondition on current file version.
- `createOnly` string, nullable — Conditional create precondition; must be '*'.
- `digest` string, nullable — Optional digest in format sha-256=<base64>.

## Headers

- `Idempotency-Key` string, nullable — Optional idempotency key for safe retries.

## Response `200`

File replaced

- SingleFileUploadResponse — Response model for single-file upload operations.
  - `archive_version` string, required — New archive version token after this commit.
  - `created` boolean, required — True when the upload created a previously missing file.
  - `file_version` string, required — New per-file version token (SHA256 of file content).
  - `filesystem_id` string, required — The filesystem ID.
  - `path` string, required — Normalized relative path written.
  - `size_bytes` integer, required — Uploaded file size in bytes.
  - `write_mode` 'overwrite' | 'conditional', required — Single-file upload write semantics.

## Other responses

- `201` — File created
- `400` — Invalid path, write mode, or digest
- `404` — Filesystem not found
- `409` — Conflict (stale base version or idempotency conflict)
- `412` — Precondition failed for conditional upload
- `422` — Validation Error
- `428` — Conditional upload missing required preconditions

---

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