openapi: 3.1.0
info:
  title: Mistral AI Agents Chat Completions API
  description: The Mistral AI Agents API provides a dedicated framework for building agentic applications. It complements the Chat Completion API by enabling AI agents to handle complex tasks, maintain context across interactions, and coordinate multiple actions. Developers can create agents with specific configurations, tools, and instructions, making it suitable for enterprise-grade agentic platforms and multi-step workflow automation.
  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:
    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
    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.
    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.
    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'
    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.
    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.
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
externalDocs:
  description: Mistral AI Agents Documentation
  url: https://docs.mistral.ai/api/endpoint/agents