Mistral AI Agents API

openapi: 3.2.0
info:
  title: Mistral AI Agents 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: Agents
  description: Agent completion operations
paths:
  /agents/completions:
    post:
      operationId: createAgentCompletion
      summary: Mistral AI Create an agent completion
      description: Generate a response from a configured agent. The agent is identified by its agent_id and can use tools, maintain conversation context, and follow custom instructions defined in the platform.
      tags:
      - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCompletionRequest'
      responses:
        '200':
          description: Agent completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCompletionResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AgentCompletionStreamResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Agent not found
        '429':
          description: Rate limit exceeded
components:
  schemas:
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
    ToolCall:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
    AgentCompletionStreamResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - chat.completion.chunk
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              delta:
                $ref: '#/components/schemas/Message'
              finish_reason:
                type:
                - string
                - 'null'
    AgentCompletionRequest:
      type: object
      required:
      - agent_id
      - messages
      properties:
        agent_id:
          type: string
          description: The ID of the agent to use, created on the Mistral platform
        messages:
          type: array
          description: List of messages comprising the conversation
          items:
            $ref: '#/components/schemas/Message'
        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
        random_seed:
          type: integer
          description: Random seed for deterministic generation
        response_format:
          type: object
          properties:
            type:
              type: string
              enum:
              - text
              - json_object
        tool_choice:
          type: string
          enum:
          - auto
          - none
          - any
          default: auto
          description: Controls how the agent uses tools
    Choice:
      type: object
      properties:
        index:
          type: integer
        message:
          $ref: '#/components/schemas/Message'
        finish_reason:
          type: string
          enum:
          - stop
          - length
          - tool_calls
          - model_length
    AgentCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/Choice'
        usage:
          $ref: '#/components/schemas/Usage'
    Message:
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
          enum:
          - system
          - user
          - assistant
          - tool
        content:
          oneOf:
          - type: string
          - type: array
            items:
              type: object
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
        tool_call_id:
          type: string
  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