Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Openai Uploads API
version: 2.3.0
contact:
name: OpenAI Support
url: https://help.openai.com/
license:
name: MIT
identifier: MIT
termsOfService: https://openai.com/policies/terms-of-use
description: 'Operations tagged Uploads across 2 of this provider''s published API definitions: openai-openapi-master-2026-09-23.yml, openai-openapi-master-2026-10-12.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.openai.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Uploads
description: Use Uploads to upload large files in multiple parts.
paths:
/uploads:
post:
operationId: createUpload
tags:
- Uploads
summary: Create upload
description: 'Creates an intermediate Upload object
that you can add Parts to.
Currently, an Upload can accept at most 8 GB in total and expires after an
hour after you create it.
Once you complete the Upload, we will create a
File object that contains all the parts
you uploaded. This File is usable in the rest of our platform as a regular
File object.
For certain `purpose` values, the correct `mime_type` must be specified.
Please refer to documentation for the
supported MIME types for your use case.
For guidance on the proper filename extensions for each purpose, please
follow the documentation on creating a
File.
Returns the Upload object with status `pending`.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUploadRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Upload'
x-oaiMeta:
group: uploads
examples:
request:
curl: "curl https://api.openai.com/v1/uploads \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"purpose\": \"fine-tune\",\n \"filename\": \"training_examples.jsonl\",\n \"bytes\": 2147483648,\n \"mime_type\": \"text/jsonl\",\n \"expires_after\": {\n \"anchor\": \"created_at\",\n \"seconds\": 3600\n }\n }'\n"
response: "{\n \"id\": \"upload_abc123\",\n \"object\": \"upload\",\n \"bytes\": 2147483648,\n \"created_at\": 1719184911,\n \"filename\": \"training_examples.jsonl\",\n \"purpose\": \"fine-tune\",\n \"status\": \"pending\",\n \"expires_at\": 1719127296\n}\n"
servers:
- url: https://api.openai.com/v1
/uploads/{upload_id}/cancel:
post:
operationId: cancelUpload
tags:
- Uploads
summary: Cancel upload
description: 'Cancels the Upload. No Parts may be added after an Upload is cancelled.
Returns the Upload object with status `cancelled`.'
parameters:
- in: path
name: upload_id
required: true
schema:
type: string
example: upload_abc123
description: 'The ID of the Upload.
'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Upload'
x-oaiMeta:
group: uploads
examples:
request:
curl: 'curl https://api.openai.com/v1/uploads/upload_abc123/cancel
'
response: "{\n \"id\": \"upload_abc123\",\n \"object\": \"upload\",\n \"bytes\": 2147483648,\n \"created_at\": 1719184911,\n \"filename\": \"training_examples.jsonl\",\n \"purpose\": \"fine-tune\",\n \"status\": \"cancelled\",\n \"expires_at\": 1719127296\n}\n"
servers:
- url: https://api.openai.com/v1
/uploads/{upload_id}/complete:
post:
operationId: completeUpload
tags:
- Uploads
summary: Complete upload
description: 'Completes the Upload.
Within the returned Upload object, there is a nested File object that is ready to use in the rest of the platform.
You can specify the order of the Parts by passing in an ordered list of the Part IDs.
The number of bytes uploaded upon completion must match the number of bytes initially specified when creating the Upload object. No Parts may be added after an Upload is completed.
Returns the Upload object with status `completed`, including an additional `file` property containing the created usable File object.'
parameters:
- in: path
name: upload_id
required: true
schema:
type: string
example: upload_abc123
description: 'The ID of the Upload.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompleteUploadRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Upload'
x-oaiMeta:
group: uploads
examples:
request:
curl: "curl https://api.openai.com/v1/uploads/upload_abc123/complete\n -d '{\n \"part_ids\": [\"part_def456\", \"part_ghi789\"]\n }'\n"
response: "{\n \"id\": \"upload_abc123\",\n \"object\": \"upload\",\n \"bytes\": 2147483648,\n \"created_at\": 1719184911,\n \"filename\": \"training_examples.jsonl\",\n \"purpose\": \"fine-tune\",\n \"status\": \"completed\",\n \"expires_at\": 1719127296,\n \"file\": {\n \"id\": \"file-xyz321\",\n \"object\": \"file\",\n \"bytes\": 2147483648,\n \"created_at\": 1719186911,\n \"expires_at\": 1719127296,\n \"filename\": \"training_examples.jsonl\",\n \"purpose\": \"fine-tune\",\n }\n}\n"
servers:
- url: https://api.openai.com/v1
/uploads/{upload_id}/parts:
post:
operationId: addUploadPart
tags:
- Uploads
summary: Add upload part
description: 'Adds a Part to an Upload object. A Part represents a chunk of bytes from the file you are trying to upload.
Each Part can be at most 64 MB, and you can add Parts until you hit the Upload maximum of 8 GB.
It is possible to add multiple Parts in parallel. You can decide the intended order of the Parts when you complete the Upload.'
parameters:
- in: path
name: upload_id
required: true
schema:
type: string
example: upload_abc123
description: 'The ID of the Upload.
'
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/AddUploadPartRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UploadPart'
x-oaiMeta:
group: uploads
examples:
request:
curl: "curl https://api.openai.com/v1/uploads/upload_abc123/parts\n -F data=\"aHR0cHM6Ly9hcGkub3BlbmFpLmNvbS92MS91cGxvYWRz...\"\n"
response: "{\n \"id\": \"part_def456\",\n \"object\": \"upload.part\",\n \"created_at\": 1719185911,\n \"upload_id\": \"upload_abc123\"\n}\n"
servers:
- url: https://api.openai.com/v1
components:
schemas:
CreateUploadRequest:
type: object
additionalProperties: false
properties:
filename:
description: 'The name of the file to upload.
'
type: string
purpose:
description: '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).
'
type: string
enum:
- assistants
- batch
- fine-tune
- vision
bytes:
description: 'The number of bytes in the file you are uploading.
'
type: integer
mime_type:
description: '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.
'
type: string
expires_after:
$ref: '#/components/schemas/FileExpirationAfter'
required:
- filename
- purpose
- bytes
- mime_type
FileExpirationAfter:
type: object
title: File expiration policy
description: 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.
properties:
anchor:
description: 'Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`.'
type: string
enum:
- created_at
x-stainless-const: true
seconds:
description: The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).
type: integer
format: int64
minimum: 3600
maximum: 2592000
required:
- anchor
- seconds
UploadPart:
type: object
title: UploadPart
description: 'The upload Part represents a chunk of bytes we can add to an Upload object.
'
properties:
id:
type: string
description: The upload Part unique identifier, which can be referenced in API endpoints.
created_at:
type: integer
format: unixtime
description: The Unix timestamp (in seconds) for when the Part was created.
upload_id:
type: string
description: The ID of the Upload object that this Part was added to.
object:
type: string
description: The object type, which is always `upload.part`.
enum:
- upload.part
x-stainless-const: true
required:
- created_at
- id
- object
- upload_id
x-oaiMeta:
name: The upload part object
example: "{\n \"id\": \"part_def456\",\n \"object\": \"upload.part\",\n \"created_at\": 1719186911,\n \"upload_id\": \"upload_abc123\"\n}\n"
OpenAIFile:
title: OpenAIFile
description: The `File` object represents a document that has been uploaded to OpenAI.
properties:
id:
type: string
description: The file identifier, which can be referenced in the API endpoints.
bytes:
type: integer
description: The size of the file, in bytes.
created_at:
type: integer
format: unixtime
description: The Unix timestamp (in seconds) for when the file was created.
expires_at:
type: integer
format: unixtime
description: The Unix timestamp (in seconds) for when the file will expire.
filename:
type: string
description: The name of the file.
object:
type: string
description: The object type, which is always `file`.
enum:
- file
x-stainless-const: true
purpose:
type: string
description: The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
enum:
- assistants
- assistants_output
- batch
- batch_output
- fine-tune
- fine-tune-results
- vision
- user_data
status:
type: string
deprecated: true
description: Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
enum:
- uploaded
- processed
- error
status_details:
type: string
deprecated: true
description: Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
required:
- id
- object
- bytes
- created_at
- filename
- purpose
- status
x-oaiMeta:
name: The file object
example: "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1680202602,\n \"filename\": \"salesOverview.pdf\",\n \"purpose\": \"assistants\",\n}\n"
AddUploadPartRequest:
type: object
additionalProperties: false
properties:
data:
description: 'The chunk of bytes for this Part.
'
type: string
format: binary
required:
- data
Upload:
type: object
title: Upload
description: 'The Upload object can accept byte chunks in the form of Parts.
'
properties:
id:
type: string
description: The Upload unique identifier, which can be referenced in API endpoints.
created_at:
type: integer
format: unixtime
description: The Unix timestamp (in seconds) for when the Upload was created.
filename:
type: string
description: The name of the file to be uploaded.
bytes:
type: integer
description: The intended number of bytes to be uploaded.
purpose:
type: string
description: The intended purpose of the file. [Please refer here](https://developers.openai.com/api/reference/resources/files#%28resource%29%20files%20%3E%20%28model%29%20file_object%20%3E%20%28schema%29%20%3E%20%28property%29%20purpose) for acceptable values.
status:
type: string
description: The status of the Upload.
enum:
- pending
- completed
- cancelled
- expired
expires_at:
type: integer
format: unixtime
description: The Unix timestamp (in seconds) for when the Upload will expire.
object:
type: string
description: The object type, which is always "upload".
enum:
- upload
x-stainless-const: true
file:
allOf:
- $ref: '#/components/schemas/OpenAIFile'
- nullable: true
description: The ready File object after the Upload is completed.
required:
- bytes
- created_at
- expires_at
- filename
- id
- purpose
- status
x-oaiMeta:
name: The upload object
example: "{\n \"id\": \"upload_abc123\",\n \"object\": \"upload\",\n \"bytes\": 2147483648,\n \"created_at\": 1719184911,\n \"filename\": \"training_examples.jsonl\",\n \"purpose\": \"fine-tune\",\n \"status\": \"completed\",\n \"expires_at\": 1719127296,\n \"file\": {\n \"id\": \"file-xyz321\",\n \"object\": \"file\",\n \"bytes\": 2147483648,\n \"created_at\": 1719186911,\n \"filename\": \"training_examples.jsonl\",\n \"purpose\": \"fine-tune\",\n }\n}\n"
CompleteUploadRequest:
type: object
additionalProperties: false
properties:
part_ids:
type: array
description: 'The ordered list of Part IDs.
'
items:
type: string
md5:
description: 'The optional md5 checksum for the file contents to verify if the bytes uploaded matches what you expect.
'
type: string
required:
- part_ids
_MisalignmentSteer:
properties:
message:
type: string
description: The public continuation instruction.
type: object
required:
- message
Error:
type: object
properties:
code:
anyOf:
- type: string
- type: 'null'
message:
type: string
param:
anyOf:
- type: string
- type: 'null'
type:
type: string
misalignment:
$ref: '#/components/schemas/MisalignmentErrorDetailsResource'
required:
- type
- message
- param
- code
_MisalignmentErrorType:
anyOf:
- type: string
- type: string
enum:
- potentially_unintended_data_transfer
- potentially_unintended_data_access
- potentially_unintended_destructive_activity
- other
OpenAIFile_2:
title: OpenAIFile
description: The `File` object represents a document that has been uploaded to OpenAI.
properties:
id:
type: string
description: The file identifier, which can be referenced in the API endpoints.
bytes:
type:
- integer
- 'null'
description: 'The size of the file, in bytes. In a completed file upload response, this can
be null when the file size is not yet available.
'
created_at:
type: integer
format: unixtime
description: The Unix timestamp (in seconds) for when the file was created.
expires_at:
type: integer
format: unixtime
description: 'The Unix timestamp (in seconds) for when the file will expire. In a
completed file upload response, this can be null when no expiry is set.
'
filename:
type: string
description: The name of the file.
object:
type: string
description: The object type, which is always `file`.
enum:
- file
x-stainless-const: true
purpose:
type: string
description: The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
enum:
- assistants
- assistants_output
- batch
- batch_output
- fine-tune
- fine-tune-results
- vision
- user_data
status:
type: string
deprecated: true
description: Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
enum:
- uploaded
- processed
- error
status_details:
type: string
deprecated: true
description: Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`. Completed file upload responses can return null when these details are unset.
required:
- id
- object
- bytes
- created_at
- filename
- purpose
- status
x-oaiMeta:
name: The file object
example: "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1680202602,\n \"filename\": \"salesOverview.pdf\",\n \"purpose\": \"assistants\",\n \"status\": \"processed\"\n}\n"
ErrorResponse:
type: object
properties:
error:
$ref: '#/components/schemas/Error'
required:
- error
Upload_2:
type: object
title: Upload
description: 'The Upload object can accept byte chunks in the form of Parts.
'
properties:
id:
type: string
description: The Upload unique identifier, which can be referenced in API endpoints.
created_at:
type: integer
format: unixtime
description: The Unix timestamp (in seconds) for when the Upload was created.
filename:
type: string
description: The name of the file to be uploaded.
bytes:
type: integer
description: The intended number of bytes to be uploaded.
purpose:
type: string
description: The intended purpose of the file. [Please refer here](https://developers.openai.com/api/reference/resources/files#%28resource%29%20files%20%3E%20%28model%29%20file_object%20%3E%20%28schema%29%20%3E%20%28property%29%20purpose) for acceptable values.
status:
type: string
description: The status of the Upload.
enum:
- pending
- completed
- cancelled
- expired
expires_at:
type: integer
format: unixtime
description: The Unix timestamp (in seconds) for when the Upload will expire.
object:
type: string
description: The object type, which is always "upload".
enum:
- upload
x-stainless-const: true
file:
description: The ready File object after the Upload is completed.
anyOf:
- $ref: '#/components/schemas/OpenAIFile_2'
- type: 'null'
required:
- bytes
- created_at
- expires_at
- filename
- id
- purpose
- status
x-oaiMeta:
name: The upload object
example: "{\n \"id\": \"upload_abc123\",\n \"object\": \"upload\",\n \"bytes\": 2147483648,\n \"created_at\": 1719184911,\n \"filename\": \"training_examples.jsonl\",\n \"purpose\": \"fine-tune\",\n \"status\": \"completed\",\n \"expires_at\": 1719127296,\n \"file\": {\n \"id\": \"file-xyz321\",\n \"object\": \"file\",\n \"bytes\": 2147483648,\n \"created_at\": 1719186911,\n \"filename\": \"training_examples.jsonl\",\n \"purpose\": \"fine-tune\",\n \"status\": \"processed\"\n }\n}\n"
MisalignmentErrorDetailsResource:
properties:
review_target:
anyOf:
- not:
pattern: '[^A-Za-z0-9._~:-]'
type: string
maxLength: 96
minLength: 1
pattern: ^[A-Za-z0-9._~:-]+$
description: An opaque target for explicitly continuing this review, or null when unavailable.
- type: 'null'
error_type:
$ref: '#/components/schemas/_MisalignmentErrorType'
description: An optional classification; clients must accept additional values.
detailed_explanation:
type: string
description: The public explanation for this block.
steer:
$ref: '#/components/schemas/_MisalignmentSteer'
description: An optional public continuation instruction.
type: object
required: []
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
AdminApiKeyAuth:
type: http
scheme: bearer
x-refined-from:
- openai-openapi-master-2026-09-23.yml
- openai-openapi-master-2026-10-12.yml
x-oaiMeta:
groups:
- id: audio
title: Audio
description: 'Learn how to turn audio into text or text into audio.
Related guide: [Speech to text](/docs/guides/speech-to-text)
'
sections:
- type: endpoint
key: createSpeech
path: createSpeech
- type: endpoint
key: createTranscription
path: createTranscription
- type: endpoint
key: createTranslation
path: createTranslation
- id: chat
title: Chat
description: 'Given a list of messages comprising a conversation, the model will return a response.
Related guide: [Chat Completions](/docs/guides/text-generation)
'
sections:
- type: endpoint
key: createChatCompletion
path: create
- type: object
key: CreateChatCompletionResponse
path: object
- type: object
key: CreateChatCompletionStreamResponse
path: streaming
- id: embeddings
title: Embeddings
description: 'Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms.
Related guide: [Embeddings](/docs/guides/embeddings)
'
sections:
- type: endpoint
key: createEmbedding
path: create
- type: object
key: Embedding
path: object
- id: fine-tuning
title: Fine-tuning
description: 'Manage fine-tuning jobs to tailor a model to your specific training data.
Related guide: [Fine-tune models](/docs/guides/fine-tuning)
'
sections:
- type: endpoint
key: createFineTuningJob
path: create
- type: endpoint
key: listPaginatedFineTuningJobs
path: list
- type: endpoint
key: listFineTuningEvents
path: list-events
- type: endpoint
key: retrieveFineTuningJob
path: retrieve
- type: endpoint
key: cancelFineTuningJob
path: cancel
- type: object
key: FineTuningJob
path: object
- type: object
key: FineTuningJobEvent
path: event-object
- id: files
title: Files
description: 'Files are used to upload documents that can be used with features like [Assistants](/docs/api-reference/assistants) and [Fine-tuning](/docs/api-reference/fine-tuning).
'
sections:
- type: endpoint
key: createFile
path: create
- type: endpoint
key: listFiles
path: list
- type: endpoint
key: retrieveFile
path: retrieve
- type: endpoint
key: deleteFile
path: delete
- type: endpoint
key: downloadFile
path: retrieve-contents
- type: object
key: OpenAIFile
path: object
- id: images
title: Images
description: 'Given a prompt and/or an input image, the model will generate a new image.
Related guide: [Image generation](/docs/guides/images)
'
sections:
- type: endpoint
key: createImage
path: create
- type: endpoint
key: createImageEdit
path: createEdit
- type: endpoint
key: createImageVariation
path: createVariation
- type: object
key: Image
path: object
- id: models
title: Models
description: 'List and describe the various models available in the API. You can refer to the [Models](/docs/models) documentation to understand what models are available and the differences between them.
'
sections:
- type: endpoint
key: listModels
path: list
- type: endpoint
key: retrieveModel
path: retrieve
- type: endpoint
key: deleteModel
path: delete
- type: object
key: Model
path: object
- id: moderations
title: Moderations
description: 'Given a input text, outputs if the model classifies it as violating OpenAI''s content policy.
Related guide: [Moderations](/docs/guides/moderation)
'
sections:
- type: endpoint
key: createModeration
path: create
- type: object
key: CreateModerationResponse
path: object
- id: assistants
title: Assistants
beta: true
description: 'Build assistants that can call models and use tools to perform tasks.
[Get started with the Assistants API](/docs/assistants)
'
sections:
- type: endpoint
key: createAssistant
path: createAssistant
- type: endpoint
key: createAssistantFile
path: createAssistantFile
- type: endpoint
key: listAssistants
path: listAssistants
- type: endpoint
key: listAssistantFiles
path: listAssistantFiles
- type: endpoint
key: getAssistant
path: getAssistant
- type: endpoint
key: getAssistantFile
path: getAssistantFile
- type: endpoint
key: modifyAssistant
path: modifyAssistant
- type: endpoint
key: deleteAssistant
path: deleteAssistant
- type: endpoint
key: deleteAssistantFile
path: deleteAssistantFile
- type: object
key: AssistantObject
path: object
- type: object
key: AssistantFileObject
path: file-object
- id: threads
title: Threads
beta: true
description: 'Create threads that assistants can interact with.
Related guide: [Assistants](/docs/assistants/overview)
'
sections:
- type: endpoint
key: createThread
path: createThread
- type: endpoint
key: getThread
path: getThread
- type: endpoint
key: modifyThread
path: modifyThread
- type: endpoint
key: deleteThread
path: deleteThread
- type: object
key: ThreadObject
path: object
- id: messages
title: Messages
beta: true
description: 'Create messages within threads
Related guide: [Assistants](/docs/assistants/overview)
'
sections:
- type: endpoint
key: createMessage
path: createMessage
- type: endpoint
key: listMessages
path: listMessages
- type: endpoint
key: listMessageFiles
path: listMessageFiles
- type: endpoint
key: getMessage
path: getMessage
- type: endpoint
key: getMessageFile
path: getMessageFile
- type: endpoint
key: modifyMessage
path: modifyMessage
- type: object
key: MessageObject
path: object
- type: object
key: MessageFileObject
path: file-object
- id: runs
title: Runs
beta: true
description: 'Represents an execution run on a thread.
Related guide: [Assistants](/docs/assistants/overview)
'
sections:
- type: endpoint
key: createRun
path: createRun
- type: endpoint
key: createThreadAndRun
path: createThreadAndRun
- type: endpoint
key: listRuns
path: listRuns
- type: endpoint
key: listRunSteps
path: listRunSteps
- type: endpoint
key: getRun
path: getRun
- type: endpoint
key: getRunStep
path: getRunStep
- type: endpoint
key: modifyRun
path: modifyRun
- type: endpoint
key: submitToolOuputsToRun
path: submitToolOutputs
- type: endpoint
key: cancelRun
path: cancelRun
- type: object
key: RunObject
path: object
- type: object
key: RunStepObject
path: step-object
- id: completions
title: Completions
legacy: true
description: 'Given a prompt, the model will return one or more predicted completions along with the probabilities of alternative tokens at each position. Most developer should use our [Chat Completions API](/docs/guides/text-generation/text-generation-models) to leverage our best and newest models. Most models that support the legacy Completions endpoint [will be shut off on January 4th, 2024](/docs/deprecations/2023-07-06-gpt-and-embeddings).
'
sections:
- type: endpoint
key: createCompletion
path: create
- type: object
key: CreateCompletionResponse
path: object