Skip to main content
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.