openapi: 3.0.0
info:
title: OpenAI Assistants Files API
description: The Assistants API allows you to build AI assistants within your own applications. An Assistant has instructions and can leverage models, tools, and knowledge to respond to user queries. The Assistants API currently supports three types of tools - Code Interpreter, Retrieval, and Function calling. In the future, we plan to release more OpenAI-built tools, and allow you to provide your own tools on our platform.
version: 2.0.0
termsOfService: https://openai.com/policies/terms-of-use
contact:
name: OpenAI Support
url: https://help.openai.com/
license:
name: MIT
url: https://github.com/openai/openai-openapi/blob/master/LICENSE
servers:
- url: https://api.openai.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Files
description: Files are used to upload documents that can be used with features like Assistants and Fine-tuning.
paths:
/files:
get:
operationId: listFiles
tags:
- Files
summary: OpenAI Returns a list of files that belong to the user's organization.
parameters:
- in: query
name: purpose
required: false
schema:
type: string
description: Only return files with the given purpose.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListFilesResponse'
x-oaiMeta:
name: List files
group: files
returns: A list of [File](/docs/api-reference/files/object) objects.
examples:
request:
curl: "curl https://api.openai.com/v1/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n"
python: 'from openai import OpenAI
client = OpenAI()
client.files.list()
'
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.files.list();\n\n for await (const file of list) {\n console.log(file);\n }\n}\n\nmain();"
response: "{\n \"data\": [\n {\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 175,\n \"created_at\": 1613677385,\n \"filename\": \"salesOverview.pdf\",\n \"purpose\": \"assistants\",\n },\n {\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 140,\n \"created_at\": 1613779121,\n \"filename\": \"puppy.jsonl\",\n \"purpose\": \"fine-tune\",\n }\n ],\n \"object\": \"list\"\n}\n"
post:
operationId: createFile
tags:
- Files
summary: 'Upload a file that can be used across various endpoints. The size of all the files uploaded by one organization can be up to 100 GB.
The size of individual files can be a maximum of 512 MB or 2 million tokens for Assistants. See the [Assistants Tools guide](/docs/assistants/tools) to learn more about the types of files supported. The Fine-tuning API only supports `.jsonl` files.
Please [contact us](https://help.openai.com/) if you need to increase these storage limits.
'
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateFileRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIFile'
x-oaiMeta:
name: Upload file
group: files
returns: The uploaded [File](/docs/api-reference/files/object) object.
examples:
request:
curl: "curl https://api.openai.com/v1/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F purpose=\"fine-tune\" \\\n -F file=\"@mydata.jsonl\"\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.create(\n file=open(\"mydata.jsonl\", \"rb\"),\n purpose=\"fine-tune\"\n)\n"
node.js: "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.create({\n file: fs.createReadStream(\"mydata.jsonl\"),\n purpose: \"fine-tune\",\n });\n\n console.log(file);\n}\n\nmain();"
response: "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n}\n"
/files/{file_id}:
delete:
operationId: deleteFile
tags:
- Files
summary: OpenAI Delete a file.
parameters:
- in: path
name: file_id
required: true
schema:
type: string
description: The ID of the file to use for this request.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteFileResponse'
x-oaiMeta:
name: Delete file
group: files
returns: Deletion status.
examples:
request:
curl: "curl https://api.openai.com/v1/files/file-abc123 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n"
python: 'from openai import OpenAI
client = OpenAI()
client.files.delete("file-abc123")
'
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.del(\"file-abc123\");\n\n console.log(file);\n}\n\nmain();"
response: "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"deleted\": true\n}\n"
get:
operationId: retrieveFile
tags:
- Files
summary: OpenAI Returns information about a specific file.
parameters:
- in: path
name: file_id
required: true
schema:
type: string
description: The ID of the file to use for this request.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIFile'
x-oaiMeta:
name: Retrieve file
group: files
returns: The [File](/docs/api-reference/files/object) object matching the specified ID.
examples:
request:
curl: "curl https://api.openai.com/v1/files/file-abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n"
python: 'from openai import OpenAI
client = OpenAI()
client.files.retrieve("file-abc123")
'
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.retrieve(\"file-abc123\");\n\n console.log(file);\n}\n\nmain();"
response: "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n}\n"
/files/{file_id}/content:
get:
operationId: downloadFile
tags:
- Files
summary: OpenAI Returns the contents of the specified file.
parameters:
- in: path
name: file_id
required: true
schema:
type: string
description: The ID of the file to use for this request.
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
x-oaiMeta:
name: Retrieve file content
group: files
returns: The file content.
examples:
request:
curl: "curl https://api.openai.com/v1/files/file-abc123/content \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" > file.jsonl\n"
python: 'from openai import OpenAI
client = OpenAI()
content = client.files.retrieve_content("file-abc123")
'
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.retrieveContent(\"file-abc123\");\n\n console.log(file);\n}\n\nmain();\n"
components:
schemas:
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
DeleteFileResponse:
type: object
properties:
id:
type: string
object:
type: string
enum:
- file
deleted:
type: boolean
required:
- id
- object
- deleted
CreateFileRequest:
type: object
additionalProperties: false
properties:
file:
description: 'The File object (not file name) to be uploaded.
'
type: string
format: binary
purpose:
description: 'The intended purpose of the uploaded file. One of:
- `assistants`: Used in the Assistants API
- `batch`: Used in the Batch API
- `fine-tune`: Used for fine-tuning
- `vision`: Images used for vision fine-tuning
- `user_data`: Flexible file type for any purpose
- `evals`: Used for eval data sets
'
type: string
enum:
- assistants
- batch
- fine-tune
- vision
- user_data
- evals
expires_after:
$ref: '#/components/schemas/FileExpirationAfter'
required:
- file
- purpose
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
description: The Unix timestamp (in seconds) for when the file was created.
filename:
type: string
description: The name of the file.
object:
type: string
description: The object type, which is always `file`.
enum:
- file
purpose:
type: string
description: The intended purpose of the file. Supported values are `fine-tune`, `fine-tune-results`, `assistants`, and `assistants_output`.
enum:
- fine-tune
- fine-tune-results
- assistants
- assistants_output
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 \"filename\": \"salesOverview.pdf\",\n \"purpose\": \"assistants\",\n}\n"
ListFilesResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/OpenAIFile'
object:
type: string
enum:
- list
required:
- object
- data
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
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