openapi: 3.1.0
info:
  title: Mistral AI Agents 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
externalDocs:
  description: Mistral AI Agents Documentation
  url: https://docs.mistral.ai/api/endpoint/agents
servers:
  - url: https://api.mistral.ai/v1
    description: Mistral AI Production Server
tags:
  - name: Agents
    description: >-
      Endpoints for interacting with Mistral AI agents that can handle
      complex tasks with tool use and multi-step reasoning.
security:
  - bearerAuth: []
paths:
  /agents/completions:
    post:
      operationId: createAgentCompletion
      summary: Create agent completion
      description: >-
        Creates a completion using a pre-configured Mistral AI agent. The
        agent processes the input messages using its configured tools,
        instructions, and model settings. Supports streaming, function
        calling, and multi-turn conversations.
      tags:
        - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCompletionRequest'
      responses:
        '200':
          description: Successful agent completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCompletionResponse'
        '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'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  schemas:
    AgentCompletionRequest:
      type: object
      required:
        - agent_id
        - messages
      properties:
        agent_id:
          type: string
          description: >-
            The ID of the agent to use. Agent IDs are created and managed
            through the Mistral AI platform.
        messages:
          type: array
          description: >-
            A list of messages comprising the conversation so far.
          items:
            $ref: '#/components/schemas/ChatMessage'
        stream:
          type: boolean
          description: >-
            Whether to stream back partial progress as server-sent events.
          default: false
        max_tokens:
          type: integer
          description: >-
            The maximum number of tokens to generate in the completion.
          minimum: 1
        stop:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: >-
            Stop generation if this token or one of these tokens is detected.
        random_seed:
          type: integer
          description: >-
            The seed to use for random sampling for deterministic results.
        response_format:
          type: object
          description: >-
            An object specifying the format that the model must output.
          properties:
            type:
              type: string
              enum:
                - text
                - json_object
              description: >-
                The format type for the response.
        tool_choice:
          type: string
          description: >-
            Controls which tool is called by the agent.
          enum:
            - auto
            - none
            - any
            - required
    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.
        tool_calls:
          type: array
          description: >-
            Tool calls generated by the agent.
          items:
            $ref: '#/components/schemas/ToolCall'
        tool_call_id:
          type: string
          description: >-
            The ID of the tool call this message is responding to.
    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.
    AgentCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: >-
            A unique identifier for the agent completion.
        object:
          type: string
          description: >-
            The object type.
          enum:
            - chat.completion
        created:
          type: integer
          description: >-
            The Unix timestamp of when the completion was created.
        model:
          type: string
          description: >-
            The model used by the agent for the completion.
        choices:
          type: array
          description: >-
            A list of completion choices.
          items:
            $ref: '#/components/schemas/AgentCompletionChoice'
        usage:
          $ref: '#/components/schemas/Usage'
    AgentCompletionChoice:
      type: object
      properties:
        index:
          type: integer
          description: >-
            The index of the choice.
        message:
          $ref: '#/components/schemas/ChatMessage'
        finish_reason:
          type: string
          description: >-
            The reason the model stopped generating tokens.
          enum:
            - stop
            - length
            - tool_calls
            - model_length
    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.