openapi: 3.2.0
info:
  title: Mistral AI Chat Completions API
  description: The Mistral AI Chat Completions API enables developers to interact with Mistral's language models in a conversational manner. It supports multi-turn conversations, function calling, JSON mode for structured outputs, and vision capabilities. The API provides access to a range of models including Mistral Large, Mistral Small, and Codestral, each optimized for different use cases from general reasoning to code generation.
  version: 1.0.0
  contact:
    name: Mistral AI Support
    url: https://docs.mistral.ai
  termsOfService: https://mistral.ai/terms
servers:
- url: https://api.mistral.ai/v1
  description: Mistral AI Production Server
security:
- bearerAuth: []
tags:
- name: Chat Completions
  description: Endpoints for generating chat completions using Mistral language models in a conversational format.
paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create chat completion
      description: Creates a model response for the given chat conversation. The endpoint accepts a list of messages comprising a conversation and returns a model-generated message as a response. Supports multi-turn conversations, function calling, JSON mode, and streaming.
      tags:
      - Chat Completions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Successful chat completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
        '400':
          description: Bad request due to invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message.
        type:
          type: string
          description: The type of error.
        code:
          type: integer
          description: The HTTP status code.
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the chat completion.
        object:
          type: string
          description: The object type, always chat.completion.
          enum:
          - chat.completion
        created:
          type: integer
          description: The Unix timestamp in seconds of when the completion was created.
        model:
          type: string
          description: The model used for the chat completion.
        choices:
          type: array
          description: A list of chat completion choices.
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
        usage:
          $ref: '#/components/schemas/Usage'
    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 in the request.
    Tool:
      type: object
      required:
      - type
      - function
      properties:
        type:
          type: string
          enum:
          - function
          description: The type of the tool. Currently only function is supported.
        function:
          $ref: '#/components/schemas/FunctionDefinition'
    ToolCall:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tool call.
        type:
          type: string
          enum:
          - function
          description: The type of the tool call.
        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 a JSON string.
    FunctionDefinition:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the function to be called.
        description:
          type: string
          description: A description of what the function does.
        parameters:
          type: object
          description: The parameters the function accepts, described as a JSON Schema object.
    ChatMessage:
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
          description: The role of the message author.
          enum:
          - system
          - user
          - assistant
          - tool
        content:
          oneOf:
          - type: string
          - type: array
            items:
              type: object
          description: The content of the message. Can be a string or an array of content parts for multimodal inputs.
        tool_calls:
          type: array
          description: Tool calls generated by the model.
          items:
            $ref: '#/components/schemas/ToolCall'
        tool_call_id:
          type: string
          description: The ID of the tool call this message is responding to, required for tool role messages.
    ChatCompletionChoice:
      type: object
      properties:
        index:
          type: integer
          description: The index of the choice in the list of choices.
        message:
          $ref: '#/components/schemas/ChatMessage'
        finish_reason:
          type: string
          description: The reason the model stopped generating tokens.
          enum:
          - stop
          - length
          - tool_calls
          - model_length
    ChatCompletionRequest:
      type: object
      required:
      - model
      - messages
      properties:
        model:
          type: string
          description: ID of the model to use. You can use the Models API to see all available models.
          example: mistral-large-latest
        messages:
          type: array
          description: A list of messages comprising the conversation so far. Each message has a role and content.
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
          description: Sampling temperature between 0.0 and 1.5. Higher values like 0.7 produce more random output, while lower values like 0.2 produce more focused and deterministic output.
          minimum: 0.0
          maximum: 1.5
          default: 0.7
        top_p:
          type: number
          description: Nucleus sampling parameter. The model considers tokens with top_p probability mass. A value of 0.1 means only the top 10% of tokens are considered.
          minimum: 0.0
          maximum: 1.0
          default: 1.0
        max_tokens:
          type: integer
          description: The maximum number of tokens to generate in the chat completion. The total token count of the prompt plus max_tokens cannot exceed the model's context length.
          minimum: 1
        stream:
          type: boolean
          description: 'Whether to stream back partial progress as server-sent events. If true, tokens are sent as data-only events as they become available, terminated by a data: [DONE] message.'
          default: false
        stop:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: Stop generation if this token is detected, or if one of these tokens is detected when providing an array.
        random_seed:
          type: integer
          description: The seed to use for random sampling. If set, different calls will generate deterministic results.
        response_format:
          type: object
          description: An object specifying the format that the model must output. Setting to json_object enables JSON mode.
          properties:
            type:
              type: string
              enum:
              - text
              - json_object
              description: The format type. Use json_object to enable JSON mode.
        tools:
          type: array
          description: A list of tools the model may call. Currently only functions are supported as a tool.
          items:
            $ref: '#/components/schemas/Tool'
        tool_choice:
          type: string
          description: Controls which tool is called by the model. Can be auto, none, any, or required.
          enum:
          - auto
          - none
          - any
          - required
        presence_penalty:
          type: number
          description: Penalizes repetition of words or phrases. A higher value encourages the model to use a wider variety of words and phrases.
          minimum: -2.0
          maximum: 2.0
          default: 0.0
        frequency_penalty:
          type: number
          description: Penalizes repetition based on frequency in the generated text. A higher value discourages repeating frequently used words.
          minimum: -2.0
          maximum: 2.0
          default: 0.0
        safe_prompt:
          type: boolean
          description: Whether to inject a safety prompt before all conversations.
          default: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
externalDocs:
  description: Mistral AI Chat Completions Documentation
  url: https://docs.mistral.ai/api/endpoint/chat