openapi: 3.1.0
info:
  title: OpenAI APIs OpenAI Assistants Chat API
  description: API for building AI assistants with custom instructions, knowledge retrieval, code execution, and function calling capabilities. Supports managing assistants, threads, messages, and runs.
  version: '2.0'
  contact:
    name: OpenAI Support
    email: support@openai.com
    url: https://help.openai.com
  termsOfService: https://openai.com/policies/terms-of-use
servers:
- url: https://api.openai.com/v1
  description: OpenAI Production API
security:
- bearerAuth: []
tags:
- name: Chat
  description: Chat completion operations
paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      summary: OpenAI APIs Create chat completion
      description: Creates a model response for the given chat conversation. Supports text, image, and audio inputs and can produce text, tool call, and structured JSON outputs.
      tags:
      - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatCompletionRequest'
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized - invalid or missing API key
        '429':
          description: Rate limit exceeded
        '500':
          description: Server error
components:
  schemas:
    ChatMessage:
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
          enum:
          - system
          - user
          - assistant
          - tool
          description: The role of the message author
        content:
          oneOf:
          - type: string
          - type: array
            items:
              type: object
          description: The contents of the message
        name:
          type: string
          description: An optional name for the participant
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
          description: Tool calls generated by the model
        tool_call_id:
          type: string
          description: Tool call that this message is responding to
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          description: Number of tokens in the prompt
        completion_tokens:
          type: integer
          description: Number of tokens in the generated completion
        total_tokens:
          type: integer
          description: Total number of tokens used
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the chat completion
        object:
          type: string
          enum:
          - chat.completion
        created:
          type: integer
          description: Unix timestamp of when the completion was created
        model:
          type: string
          description: The model used for the completion
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/ChatMessage'
              finish_reason:
                type: string
                enum:
                - stop
                - length
                - tool_calls
                - content_filter
        usage:
          $ref: '#/components/schemas/Usage'
        system_fingerprint:
          type: string
          description: Fingerprint of the backend configuration
    Tool:
      type: object
      required:
      - type
      - function
      properties:
        type:
          type: string
          enum:
          - function
          description: The type of the tool
        function:
          type: object
          required:
          - name
          properties:
            name:
              type: string
              description: The name of the function
            description:
              type: string
              description: A description of what the function does
            parameters:
              type: object
              description: The parameters the function accepts as JSON Schema
    CreateChatCompletionRequest:
      type: object
      required:
      - model
      - messages
      properties:
        model:
          type: string
          description: ID of the model to use (e.g., gpt-4o, gpt-4-turbo, gpt-3.5-turbo)
          examples:
          - gpt-4o
        messages:
          type: array
          description: A list of messages comprising the conversation so far
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1
          description: Sampling temperature between 0 and 2
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 1
          description: Nucleus sampling parameter
        n:
          type: integer
          minimum: 1
          default: 1
          description: Number of chat completion choices to generate
        stream:
          type: boolean
          default: false
          description: Whether to stream partial message deltas
        stop:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: Up to 4 sequences where the API will stop generating
        max_tokens:
          type: integer
          description: Maximum number of tokens to generate in the completion
        max_completion_tokens:
          type: integer
          description: Upper bound for tokens generated in the completion including reasoning tokens
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
          description: Penalize new tokens based on presence in text so far
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
          description: Penalize new tokens based on frequency in text so far
        logit_bias:
          type: object
          additionalProperties:
            type: number
          description: Modify the likelihood of specified tokens appearing
        user:
          type: string
          description: A unique identifier representing your end-user
        tools:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
          description: A list of tools the model may call
        tool_choice:
          oneOf:
          - type: string
            enum:
            - none
            - auto
            - required
          - type: object
            properties:
              type:
                type: string
                enum:
                - function
              function:
                type: object
                properties:
                  name:
                    type: string
          description: Controls which tool is called by the model
        response_format:
          type: object
          properties:
            type:
              type: string
              enum:
              - text
              - json_object
              - json_schema
          description: Specifies the format that the model must output
        seed:
          type: integer
          description: Deterministic sampling seed for reproducible outputs
    ToolCall:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tool call
        type:
          type: string
          enum:
          - function
        function:
          type: object
          properties:
            name:
              type: string
              description: The name of the function to call
            arguments:
              type: string
              description: The arguments to call the function with as JSON
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: OpenAI API key passed as a Bearer token
externalDocs:
  description: OpenAI Assistants API Documentation
  url: https://platform.openai.com/docs/api-reference/assistants