API ReferenceFiles

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.

Query parameters

scope_idstringRequired

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

pathstring or nullOptional
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 `/`.
namespacestringOptionalDefaults to session
Namespace for the file. Defaults to 'session'.

Request

Request payload.
filefileRequired
file field.

Response

Successful Response
idstring

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_atdatetime

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

filenamestring
Filename derived from the path.
mime_typestring
MIME type detected from the file content.
size_bytesinteger
File size in bytes.
downloadableboolean

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

scopeobject
Session scope this file belongs to.
type"file"OptionalDefaults to file
Object type discriminator, always 'file'.
etagstring or nullOptional

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

namespacestringOptionalDefaults to session

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

Errors

401
Unauthorized Error
422
Unprocessable Entity Error