Skip to main content
PUT
Upload File
Upload a single file into a filesystem by relative path. For most calls, provide only path plus the raw file bytes. writeMode defaults to overwrite. This is the single-file write surface. Use Get Upload URL only for whole-filesystem archive uploads. There is no dedicated tu fs CLI subcommand for single-file upload today.

Required Inputs

  • path: Relative file path (for example src/app.py).
  • Request body: Raw bytes (Content-Type: application/octet-stream).

Version Fields

baseVersion and expectedVersion come from previous reads/writes:
  • baseVersion: previous archive_version response field (or current filesystem archive checksum).
  • expectedVersion: previous file_version response field (or current file checksum).

Status Codes and Retry Guidance

Use writeMode=conditional when you need optimistic concurrency:
  • Replace flow: send baseVersion + expectedVersion.
  • Create flow: send baseVersion + createOnly="*".
Use Idempotency-Key for safe retries:
  • Same key + same request -> original response is replayed.
  • Same key + different request -> 409 conflict.

Headers

Idempotency-Key
string | null

Optional idempotency key for safe retries.

Path Parameters

filesystem_id
string
required

Query Parameters

path
string
required

Relative path to write.

writeMode
enum<string>
default:overwrite

Upload semantics: overwrite (default) or conditional.

Available options:
overwrite,
conditional
baseVersion
string | null

Required in conditional mode: expected current archive version.

expectedVersion
string | null

Conditional replace precondition on current file version.

createOnly
string | null

Conditional create precondition; must be '*'.

digest
string | null

Optional digest in format sha-256=.

Body

application/octet-stream

The body is of type file.

Response

File replaced

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
enum<string>
required

Applied upload write mode.

Available options:
overwrite,
conditional