Concepts
Purposes, references, expiry and downloads.
Purpose
purpose records how you intend to use an uploaded file. Uploads accept three values:
| Purpose | Use and limitation |
|---|---|
user_data | General input files. Required when referencing an image in a conversation. |
assistants | Files intended for assistant or knowledge-store workflows. Uploading does not attach a file to an agent or store. Conversation image references reject this purpose. |
vision | Accepts only PNG, JPEG, GIF or WebP images (detected from content); other content returns 400 FILE_TYPE_UNSUPPORTED. Conversation image references reject this purpose. |
batch, fine-tune and evals are not accepted upload purposes. Anthropic uploads are stored as user_data.
Reuse a file ID
/file/v1/files, /openai/v1/files and /anthropic/v1/files share file IDs for the same account. Metadata and deletion work across these APIs. Download uploaded files through the native or OpenAI API; Anthropic downloads only support session output files.
- Conversations: reference a
user_dataimage usingtype: "file"andfile.file_id. Do not place the ID inimage_url.url. Text and PDF file IDs are not currently accepted as conversation image input. See the runnable image example. - Media libraries: import the ID as
file_idto create an asset. See media files. - Knowledge stores: add
file_idto a store to extract and index its content. See knowledge concepts. - Agents: attach a file to a session resource using
type: "file",file_idandmount_path. Settingpurpose=assistantsalone does not attach it. See session resources.
Session output metadata can include scope, relative_path and revision. List a session's files with scope_id; Anthropic requires anthropic-beta: managed-agents-2026-04-01 for this filter.
Expiry
Without an expiry setting, an uploaded file persists until deleted. expires_after measures seconds from created_at; the returned expires_at is the expiry timestamp. Expired files cannot be read or reused. See the supported ranges.
Download safety
Downloaded content identified as HTML, SVG, XML or JavaScript is served as an attachment. Responses use X-Content-Type-Options: nosniff. Detection uses content rather than the filename: uploaded HTML or SVG may be identified and returned as plain text. Downloading does not execute that content.
Range downloads
Content downloads accept one Range interval: bytes=0-1023, bytes=1024- (to the end) or bytes=-1024 (the last 1024 bytes). A satisfiable range returns 206 with Content-Range; a range beyond the file size returns 416. Every download response carries Accept-Ranges: bytes, so downloads can resume and audio or video can seek.