files

Upload a file

Upload a file into the session's uploads directory. By default the file is stored under uploads/{filename} within the session scope; pass path to push it to a custom object-storage-style key (e.g. data/2024/report.pdf), relative to the uploads mount (/mnt/user-data/uploads/ inside the sandbox). The relative path is returned as the file ID. Uploading a file to an existing key overwrites it.

post/v1/files

Query parameters

scope_idstring required

Session / container identifier (matches the container field in chat requests).

pathstring nullable

Object-storage-style key for the uploaded file, relative to the uploads mount. Defaults to uploads/{filename}. Nested keys are supported and parent directories are created automatically. May be prefixed with uploads/ for convenience. Must be relative (no leading /), must not contain .. components, and must not end with /.

namespacestring

Namespace for the file. Defaults to 'session'.

Response

Successful Response

idstring required

Relative path of the file within the session, e.g. 'uploads/data.csv' or 'outputs/result.png'. Use this value as file_id in subsequent requests.

created_atstring date-time required

ISO-8601 timestamp when the file was created or last modified.

filenamestring required

Filename derived from the path.

mime_typestring required

MIME type detected from the file content.

size_bytesinteger required

File size in bytes.

type'file'

Object type discriminator, always 'file'.

downloadableboolean required

True for sandbox output files; False for uploaded input files.

etagstring nullable

Content checksum (MD5 hex or S3 ETag). Present after stat; None if unavailable.

namespacestring

Namespace this file belongs to (e.g. 'session', 'skills', or a custom namespace).

Changes

No recorded changes to this endpoint across all 1 revision of this API.