Uploads a single file using multipart/form-data, with a maximum size of 50 MB. The file enters a security review after upload; only files with available status can be mounted or used as message content.
Prerequisites
Endpoint and authentication configured. For details, see Overview and authentication.
Quotas and limits
- Total file storage per workspace is limited to 100 GB.
- Files are retained for 30 days. Files older than 30 days are not guaranteed to be available and may be automatically cleaned up. Re-upload periodically for long-term retention.
- Maximum size for a single file uploaded via this endpoint is 50 MB.
Endpoint
POST /files
Uses multipart/form-data encoding. filename is automatically extracted from the form part, and mime_type is detected by the server.
Request example
Response example
Response fields
| Field | Type | Description |
|---|---|---|
id | string | File ID, format file_<24 alphanumeric> (e.g. file_maznwes8t9rsysg5r5enkvpr) |
type | string | Fixed value file |
filename | string | Filename (parsed from the upload form part) |
mime_type | string | MIME type detected by the server |
size_bytes | int | File size in bytes |
downloadable | bool | Whether the file supports download. Both direct uploads and session sandbox copies are false |
status | string | Security review status: available (passed, can be mounted) / checking (under review) / rejected (content rejected) / type_rejected (unsupported type). Newly uploaded files default to checking |
created_at | string | Upload time, ISO 8601 |
requestId | string | Unique identifier for this request |
Scope
Files from regular uploads have no scope field (shared within the workspace by default). When a file is mounted to a session sandbox, the server creates an internal copy with a new file_id; the metadata of this copy includes scope: {"type": "session", "id": "sesn_..."}, making it visible only to the corresponding session.