File object
Upload, get, and list endpoints return File objects.| Field | Type | Description |
|---|---|---|
id | string | File ID with the file_ prefix |
type | string | Always "file" |
filename | string | Stored file name |
size_bytes | integer | File size in bytes |
mime_type | string | MIME type supplied by the upload or detected from the file name |
downloadable | boolean | Whether this file can be downloaded through GET /api/v1/cloud/files/{file_id}/content |
scope | object | null | Scope object when associated with another resource, for example { "id": "sess_...", "type": "session" } |
metadata | object | Custom metadata object supplied on upload; defaults to {} |
created_at | string | UTC creation time in RFC 3339 format |
File content link
GET /api/v1/cloud/files/{file_id}/content returns this object.
| Field | Type | Description |
|---|---|---|
url | string | Presigned download URL |
expires_at | string | UTC expiration time for the URL in RFC 3339 format |
Upload form fields
POST /api/v1/cloud/files uses multipart/form-data.
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | Text-based file content |
name | string | No | Stored file name. Defaults to the uploaded file name. After server sanitization, length must be 1-255 bytes and cannot be . or .. |
metadata | JSON string | No | Valid JSON encoded as a form field. Maximum raw length is 8 KB. Defaults to {} |
Supported upload file types
The upload endpoint accepts text-based files only.| Category | Accepted values |
|---|---|
| MIME type | Any text/* MIME type, plus application/json, application/xml, application/javascript, application/x-yaml, and application/x-toml |
| Extension | .txt, .md, .csv, .json, .xml, .yaml, .yml, .toml, .ini, .conf, .cfg, .env, .log, .html, .htm, .css, .scss, .less, .js, .jsx, .ts, .tsx, .vue, .svelte, .py, .go, .rs, .java, .kt, .scala, .c, .cpp, .cc, .h, .hpp, .rb, .php, .swift, .r, .lua, .pl, .sh, .bash, .zsh, .fish, .ps1, .sql, .graphql, .gql, .proto, .dockerfile, .makefile, .gitignore, .editorconfig, .eslintrc, .prettierrc, .tex, .rst, .adoc, .org, .svg |
| Extensionless file name | dockerfile, makefile, gemfile, rakefile, procfile, vagrantfile, justfile, brewfile |
Related
Attach and download files
Upload files to give your agent context, and download files it produces.