Upload File
Upload a single file into a filesystem by relative path. Defaults to overwrite mode; conditional mode can be used for strict concurrency control.
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 examplesrc/app.py).- Request body: Raw bytes (
Content-Type: application/octet-stream).
Version Fields
baseVersion and expectedVersion come from previous reads/writes:
baseVersion: previousarchive_versionresponse field (or current filesystem archive checksum).expectedVersion: previousfile_versionresponse field (or current file checksum).
Status Codes and Retry Guidance
Advanced: Conditional mode
Advanced: Conditional mode
writeMode=conditional when you need optimistic concurrency:- Replace flow: send
baseVersion+expectedVersion. - Create flow: send
baseVersion+createOnly="*".
Advanced: Idempotent retries
Advanced: Idempotent retries
Idempotency-Key for safe retries:- Same key + same request -> original response is replayed.
- Same key + different request ->
409conflict.
Headers
Optional idempotency key for safe retries.
Path Parameters
Query Parameters
Relative path to write.
Upload semantics: overwrite (default) or conditional.
overwrite, conditional Required in conditional mode: expected current archive version.
Conditional replace precondition on current file version.
Conditional create precondition; must be '*'.
Optional digest in format sha-256=.
Body
The body is of type file.
Response
File replaced
Response model for single-file upload operations.
New archive version token after this commit.
True when the upload created a previously missing file.
New per-file version token (SHA256 of file content).
The filesystem ID.
Normalized relative path written.
Uploaded file size in bytes.
Applied upload write mode.
overwrite, conditional