openapi: 3.1.0
info:
  title: Mistral AI Agents Chat API
  description: Agent completions API for building AI agents that can handle complex tasks, maintain context, coordinate multiple actions, and use tools including function calling. Agents are created and configured via the Mistral platform and invoked through this API.
  version: '1.0'
  contact:
    name: Mistral AI Support
    url: https://docs.mistral.ai/
    email: support@mistral.ai
  termsOfService: https://mistral.ai/terms/
servers:
- url: https://api.mistral.ai/v1
  description: Mistral AI Production
security:
- bearerAuth: []
tags:
- name: Chat
  description: Chat completion operations
paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      summary: Mistral AI Create a chat completion
      description: Generate a model response for the given chat conversation. Supports multi-turn conversations, streaming, function calling, JSON mode, and vision inputs depending on the model.
      tags:
      - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ChatCompletionStreamResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API key
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
      - model
      - messages
      properties:
        model:
          type: string
          description: ID of the model to use
          examples:
          - mistral-large-latest
          - mistral-small-latest
          - open-mistral-nemo
        messages:
          type: array
          description: List of messages comprising the conversation
          items:
            $ref: '#/components/schemas/Message'
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 0.7
          description: Sampling temperature between 0 and 2
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 1
          description: Nucleus sampling parameter
        max_tokens:
          type: integer
          minimum: 1
          description: Maximum number of tokens to generate
        stream:
          type: boolean
          default: false
          description: Whether to stream partial message deltas
        stop:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: Stop sequences where the model will stop generating
        random_seed:
          type: integer
          description: Random seed for deterministic generation
        response_format:
          type: object
          properties:
            type:
              type: string
              enum:
              - text
              - json_object
          description: Output format specification
        tools:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
          description: List of tools the model may call
        tool_choice:
          type: string
          enum:
          - auto
          - none
          - any
          default: auto
          description: Controls how the model uses tools
        safe_prompt:
          type: boolean
          default: false
          description: Whether to prepend a safety system prompt
    ChatCompletionStreamResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - chat.completion.chunk
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/StreamChoice'
    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 completion
        total_tokens:
          type: integer
          description: Total tokens used
    Error:
      type: object
      properties:
        type:
          type: string
        message:
          type: string
        param:
          type:
          - string
          - 'null'
        code:
          type:
          - string
          - 'null'
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the 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:
            $ref: '#/components/schemas/Choice'
        usage:
          $ref: '#/components/schemas/Usage'
    FunctionDefinition:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the function
        description:
          type: string
          description: Description of what the function does
        parameters:
          type: object
          description: JSON Schema describing the function parameters
    Choice:
      type: object
      properties:
        index:
          type: integer
        message:
          $ref: '#/components/schemas/Message'
        finish_reason:
          type: string
          enum:
          - stop
          - length
          - tool_calls
          - model_length
          description: Reason the model stopped generating
    ContentPart:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - text
          - image_url
        text:
          type: string
          description: Text content
        image_url:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: URL or base64 data URI of the image
    Tool:
      type: object
      required:
      - type
      - function
      properties:
        type:
          type: string
          enum:
          - function
        function:
          $ref: '#/components/schemas/FunctionDefinition'
    StreamChoice:
      type: object
      properties:
        index:
          type: integer
        delta:
          $ref: '#/components/schemas/Message'
        finish_reason:
          type:
          - string
          - 'null'
          enum:
          - stop
          - length
          - tool_calls
          - model_length
          - null
    ToolCall:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the tool call
        type:
          type: string
          enum:
          - function
        function:
          type: object
          properties:
            name:
              type: string
              description: The function name
            arguments:
              type: string
              description: JSON string of the function arguments
    Message:
      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:
              $ref: '#/components/schemas/ContentPart'
          description: The content of the message
        name:
          type: string
          description: 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: ID of the tool call this message is a response to
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Mistral AI API key passed as a Bearer token
externalDocs:
  description: Mistral AI Agents API Documentation
  url: https://docs.mistral.ai/api/endpoint/agents