File data structures

File object

Upload, get, and list endpoints return File objects.

Field	Type	Description
`file_id`	string	File ID with the `file_` prefix
`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
`purpose`	string	File purpose. See File purpose
`status`	string	File status. See File status
`metadata`	JSON value	Metadata JSON supplied at upload time; defaults to `{}`
`created_at`	string	UTC creation time in RFC 3339 format
`updated_at`	string	UTC update time, returned only when different from `created_at`
`session_id`	string	Returned when the file is associated with a Session

Value	Description
`user_upload`	File uploaded by the user for later use
`tool_output`	File produced by a tool
`skill_output`	File produced by a Skill
`session_resource`	File attached as a Session resource
`agent_output`	File produced as an Agent output

Value	Description
`uploading`	Upload record has been created and content upload is in progress
`ready`	File content is available
`error`	Upload failed after the record was created
`deleted`	File has been deleted; returned only by list requests that explicitly include deleted files

GET /v1/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 /v1/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 `..`
`purpose`	string	No	Defaults to `user_upload`. See File purpose
`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.