# OpenAI Files API and Uploads API

Status: DOCUMENTED · LIVE_VERIFIED (all 5 Files endpoints and all 4 Uploads endpoints called on 2026-09-18 with a project key; one LIVE_DISCOVERED behaviour on Uploads purposes). Sources: Files reference · Uploads reference · File inputs guide · Batch guide · Retrieval guide · OpenAPI openapi-master.yaml. Last verified: 2026-09-18. Machine-readable twins: generated/fragments/endpoints/openai-files-vectorstores-batch-finetuning-evals.json, generated/fragments/parameters/openai-files.json, openai-uploads.json, generated/fragments/objects/openai-platform-objects.json, generated/fragments/status-lifecycles/openai-lifecycles.json.

Files are the storage primitive shared by Batch, Fine-tuning, Evals, vector stores / file_search, and file inputs (input_file) to Responses. Uploads is the multipart variant for large files (> what a single POST /v1/files request can carry).

# 1. Endpoints

No streaming, no beta header. All list endpoints use cursor pagination (after, limit) and return {object:"list", data, first_id, last_id, has_more}.

# 2. Purposes

Observation: evals is accepted by the API and by the guide, and the OpenAPI enum lists it as well; the File object enum (response side) does not list evals, yet the live response returned "purpose": "evals".

# 3. Limits (documented) and retention

Observed on 2026-09-18: expires_after given as multipart fields (expires_after[anchor], expires_after[seconds]=3600) produced expires_at = created_at + 3600 on a user_data file. On POST /v1/uploads, passing expires_after {seconds: 3600} produced the same expires_at as without it (upload TTL is 1 h either way); the resulting File had expires_at: null — so expires_after on Uploads is UNVERIFIED as a File expiry mechanism.

# 4. Objects

File (object: "file"): id (file-…), bytes, created_at, expires_at (int | null), filename, purpose, status (deprecated: uploaded | processed | error — observed processed immediately), status_details (deprecated).

Upload (object: "upload"): id (upload_…), bytes (declared), created_at, expires_at, filename, purpose, status (pending | completed | cancelled | expired), file (File, only after complete).

UploadPart (object: "upload.part"): id (part_…), created_at, upload_id.

Lifecycles: see generated/fragments/status-lifecycles/openai-lifecycles.json (upload, file).

# 5. Supported formats for retrieval (assistants / user_data into vector stores)

.c .cpp .cs .css .doc .docx .go .html .java .js .json .md .pdf .php .pptx .py .rb .sh .tex .ts .txt with the MIME types listed in the Retrieval guide; text/* must be utf-8 / utf-16 / ascii. Images and audio are not indexable. (Responses input_file accepts a wider set incl. rich documents; see the tools agent's docs/tools/ pages.)

# 6. Uploads protocol (large files)

1. POST /v1/uploads {filename, purpose, bytes, mime_type} → Upload pending. Declared bytes must equal the sum of parts at completion.
2. POST /v1/uploads/{id}/parts for each chunk (≤ 64 MB each, any order, parallel allowed) — multipart field data.
3. POST /v1/uploads/{id}/complete {part_ids: [in order], md5?} → completed, file.id usable everywhere a File is.
4. Or POST …/cancel → cancelled (parts can no longer be added; verified 400).

Observed: the OpenAPI enum for purpose on POST /v1/uploads is assistants | batch | fine-tune | vision, yet user_data was accepted (200) and propagated to the resulting File → LIVE_DISCOVERED.

# 7. Errors seen

# 8. Cost

File storage itself is not billed (vector-store storage is, see vector-stores.md). The 2026-09-18 tests cost $0 for this area.