Skip to main content
PUT
/
filesystems
/
{filesystem_id}
/
file-upload
Upload File
curl --request PUT \
  --url https://api.example.com/filesystems/{filesystem_id}/file-upload \
  --header 'Content-Type: application/octet-stream' \
  --data '"<string>"'
{
  "archive_version": "a9502c997a...",
  "created": false,
  "file_version": "d4f9678f0c...",
  "filesystem_id": "fs_123",
  "path": "src/main.py",
  "size_bytes": 14,
  "write_mode": "overwrite"
}

Documentation Index

Fetch the complete documentation index at: https://docs.terminaluse.com/llms.txt

Use this file to discover all available pages before exploring further.

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

FieldMeaningRequired when
writeModeWrite strategy: overwrite or conditionalOptional (overwrite is default)
baseVersionExpected current archive versionwriteMode=conditional
expectedVersionExpected current file version at pathwriteMode=conditional replace flow
createOnlyCreate only if file does not exist ("*" only)writeMode=conditional create flow
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

StatusMeaningWhat to do
200Existing file replacedSuccess
201New file createdSuccess
400Invalid path or digest (or malformed request)Fix request; do not retry unchanged
404Filesystem not found or not authorizedVerify ID and access
409Conflict (stale baseVersion or idempotency key reused with different request)Refresh state or use new idempotency key
412expectedVersion precondition failedRefresh file version and retry
428Missing/invalid conditional preconditionsAdd required conditional fields
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