Feature request: Clarify and standardize Files API purposes and download semantics
- The recent restriction preventing downloads for files with purpose=user_data appears to be intentional for security, but it caused regressions in API-based workflows that relied on downloading their own uploads. This likely shares infrastructure with ChatGPT/CustomGPTs where the restriction makes sense but inadvertently impacts developer use cases.
- Please simplify and document file purposes with clear, stable semantics - especially around what can be downloaded and by whom - so developers can choose the correct purpose without guesswork
Proposal
- Publish a definitive matrix for each file purpose describing intended use, supported APIs, and whether direct content download via files.content is allowed.
- Guarantee consistent server behavior across APIs (Chat Completions, Responses, Batch, Fine-tuning).
- If download must be restricted for security, add explicit, documented flags (e.g., ephemeral, private-only)
- Provide migration guidance (e.g., Assistants → Responses) and a deprecation timeline.
Proposed purposes table
| Purpose | Definition / Intended use | Download via files.content | Primary APIs | Lifecycle / Notes |
|---|---|---|---|---|
| assistants | Files used by the legacy Assistants API and its tools (file search/code interpreter) | Yes (owner/org) | Assistants | Deprecated; prefer Responses. Keep behavior stable until EOL. |
| batch | Inputs for asynchronous Batch jobs | Yes (owner/org) | Batch | Stable; clarify size/format constraints. |
| fine-tune | Training/validation files for fine-tuning | Yes (owner/org) | Fine-tuning | Stable; document retention and access post-job. |
| vision | Images for vision training/inference workloads | Yes (owner/org) | Vision / Fine-tuning | Stable; clarify supported formats and preprocessing. |
| user_data | General-purpose uploads for prototyping, ChatGPT/CustomGPTs, or playground | Yes (owner/org). Today appears restricted - please either allow or document restriction and provide alternative. | ChatGPT/Playground; general API | Mark as “flexible”; document when/why downloads are blocked; provide replacement guidance. |
| evals | Datasets for eval pipelines | Yes (owner/org) | Evals | Stable; clarify expected schemas and sizes. |
| chatcompletions | Files attached as part of user input to Chat Completions | Yes (owner/org) | Chat Completions | Stable; document tokenization/size limits and ingestion behavior. |
Notes:
- “Yes (owner/org)” means the uploading org (and authorized tokens) can download bytes via files.content. If there are contexts where download should be blocked, please expose an explicit, documented flag (e.g., purpose=user_data + access=private_only) instead of hardcoding behavior per-purpose.
- If “assistants” is being replaced by the Responses API, document how the same file should be uploaded/linked for Responses (or introduce a “responses” purpose) and provide a migration guide.
Migration and compatibility
- Grandfather existing files by allowing download for owner/org, or provide an automated re-tagging path (purpose=user_data → purpose=responses/assistants) without re-upload.
- Return precise, stable error codes (e.g., purpose_download_forbidden) to unblock programmatic fallbacks.
- Announce deprecation timelines for purpose semantics changes with SDK examples.
Success criteria
- Developers can deterministically choose a purpose and know if files.content will work.
- No regressions for Responses/Chat Completions uploads.
- Clear migration from Assistants to Responses without breaking file access