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