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 active organization (resolved from x-organization-id, falling back 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
- 500
The uploaded file object.
Invalid request — unsupported file MIME type (byte-sniffed type not in the allowlist), a purpose other than user_data, a file exceeding 50 MB, or a disallowed extension.
Unauthenticated, lacking the file:write ability, or no active organization could be resolved for the caller.
The file could not be read from disk, uploaded to storage, or its metadata persisted.