File data structures

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

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

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 `{}`

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`

Upload files to give your agent context, and download files it produces.