Upload a file
POST/v1/files
Upload a document for an artifact-capable agent to read at runtime. OpenAI-Files-API wire-conformant: a multipart/form-data body with a file part and a purpose part. The returned object's id (file_…) is referenced from a Responses-API request as an input_file content part — see Sending Documents to the Agent and the Attach Files to an Agent guide.
Files are scoped to the caller's current organization. An active organization is required — uploads without one are rejected.
The stored MIME type is detected from the file's magic-number bytes, not the client-supplied Content-Type of the multipart part. The extension allowlist on the file field is a first-pass filter only; the byte-sniffed MIME must be in the allowlist (application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx), application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (.xlsx), text/markdown, text/plain). Maximum size is 50 MB.
Note: success responses are OpenAI-shaped and bypass the platform's { success, data } envelope.
Request
Responses
- 200
- 400
- 401
- 422
- 500
The uploaded file object.
Unsupported file MIME type — the byte-sniffed type (from the file's magic-number bytes) is not in the allowlist.
Unauthenticated, lacking the file:write ability, or no active organization could be resolved for the caller.
Validation failed
The file could not be read from disk, uploaded to storage, or its metadata persisted.