Skip to main content
POST
Create a resumable upload session

Authorizations

Authorization
string
header
required

API key passed as Bearer token

Headers

Idempotency-Key
string
required

Reuse the same key to safely retry the same create, reusable snapshot create, fork, upload create/complete, or agent deployment create operation without duplicating work.

Path Parameters

id
string
required

Machine ID (e.g. mch_a1b2c3d4)

Body

application/json
kind
enum<string>
required
Available options:
file,
directory_tar
source_kind
enum<string>
required
Available options:
restartable_file,
spooled_stream,
directory_archive
target_path
string
required

Requested upload destination path. Absolute paths may target valid machine locations such as /workspace, /tmp, /data, or /context where present. Relative paths resolve from the machine cwd when set, otherwise from the selected user's home when user is provided, otherwise from /workspace. Reserved runtime paths under /workspace/.nullspace are rejected.

content_length
integer<uint64>
required
conflict
enum<string>
required
Available options:
merge,
replace,
error
checksum_algorithm
enum<string>
required
Available options:
sha256
user
string

Optional machine user for relative-path resolution and ownership.

archive_format
enum<string>
Available options:
tar
whole_checksum_sha256
string
metadata
object

Free-form client-supplied metadata for the upload session; stored verbatim, deliberately open.

Response

200 - application/json

Upload session created

session
object
required