curl -X POST 'https://api.openai.com/v1/uploads' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "filename": "example-filename",
  "purpose": "assistants",
  "bytes": 0,
  "mime_type": "example-mime-type"
}'

# POST /uploads (OpenAI API)
Base URL: https://api.openai.com/v1
Auth: Authorization; OpenAI API key; required.
Request formats: application/json.
Last verified: 2026-10-20

> Create upload

## Critical Gotchas
* The Responses API is the primary interface for new text and tool workflows; Chat Completions remains a separate compatibility API.
* Audio transcription uploads use multipart form data rather than a JSON request body.

## cURL
curl -X POST 'https://api.openai.com/v1/uploads' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "filename": "example-filename",
  "purpose": "assistants",
  "bytes": 0,
  "mime_type": "example-mime-type"
}'

## Parameters
| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| filename | body | string | Yes | The name of the file to upload.  |
| purpose | body | string | Yes | The intended purpose of the uploaded file.  See the [documentation on File pu... |
| bytes | body | integer | Yes | The number of bytes in the file you are uploading.  |
| mime_type | body | string | Yes | The MIME type of the file.   This must fall within the supported MIME types f... |
| expires_after | body | object | No | The expiration policy for a file. By default, files with `purpose=batch` expi... |

## Response example
{"id":"string","created_at":0}

---
Need an API key? Get one at https://platform.openai.com/api-keys

POST

POST /uploads — OpenAI API

OpenAI API key (required); https://api.openai.com/v1

OpenAI API

Create upload

Base URL: https://api.openai.com/v1
Auth: Authorization: Bearer <OPENAI_API_KEY>
Last verified: 2026-10-20 · upstream hash matched

Actions Try in browser→

Agents: curl -H "Accept: text/markdown" this URL
→ 302 tokens · Vary: Accept

Critical gotchas

The Responses API is the primary interface for new text and tool workflows; Chat Completions remains a separate compatibility API.

Audio transcription uploads use multipart form data rather than a JSON request body.

cURL

curl -X POST 'https://api.openai.com/v1/uploads' \  -H "Authorization: Bearer $OPENAI_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "filename": "example-filename",  "purpose": "assistants",  "bytes": 0,  "mime_type": "example-mime-type"}'

Parameters

Name	In	Type	Required	Description
filename	body	string	Yes	The name of the file to upload.
purpose	body	string	Yes	The intended purpose of the uploaded file. See the [documentation on File purposes](https://developers.openai.com/api/reference/resources/files/methods/create#%28resource%29%20files%20%3E%20%28method%29%20create%20%3E%20%28params%29%200%20%3E%20%28param%29%20purpose%20%3E%20%28schema%29).
bytes	body	integer	Yes	The number of bytes in the file you are uploading.
mime_type	body	string	Yes	The MIME type of the file. This must fall within the supported MIME types for your file purpose. See the supported MIME types for assistants and vision.
expires_after	body	object	No	The expiration policy for a file. By default, files with `purpose=batch` expire after 30 days and all other files are persisted until they are manually deleted.

Response 200 OK

{
  "id": "string",
  "created_at": 0,
  "filename": "string",
  "bytes": 0,
  "purpose": "string",
  "status": "pending",
  "expires_at": 0,
  "object": "upload",
  "file": {
    "id": "string",
    "bytes": 0,
    "created_at": 0,
    "expires_at": 0,
    "filename": "string",
    "object": "file",
    "purpose": "assistants",
    "status": "uploaded",
    "status_details": "string"
  }
}

Get a free OpenAI API key → sponsored

Affiliate link - we may earn a commission, at no extra cost to you.