openapi: 3.1.0
info:
  title: Mistral AI Agents Fine-Tuning Jobs 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: Fine-Tuning Jobs
  description: Endpoints for creating, managing, and monitoring fine-tuning jobs on Mistral AI models.
paths:
  /fine_tuning/jobs:
    post:
      operationId: createFineTuningJob
      summary: Create fine-tuning job
      description: Creates a fine-tuning job which begins the process of creating a new model from a given dataset. The job runs asynchronously and its progress can be monitored via the retrieve endpoint.
      tags:
      - Fine-Tuning Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFineTuningJobRequest'
      responses:
        '200':
          description: Successfully created fine-tuning job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FineTuningJob'
        '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'
    get:
      operationId: listFineTuningJobs
      summary: List fine-tuning jobs
      description: List fine-tuning jobs for your organization. Returns a paginated list of jobs with their current status and configuration.
      tags:
      - Fine-Tuning Jobs
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageSizeParam'
      responses:
        '200':
          description: Successfully retrieved list of fine-tuning jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FineTuningJobList'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fine_tuning/jobs/{job_id}:
    get:
      operationId: getFineTuningJob
      summary: Get fine-tuning job
      description: Get info about a fine-tuning job including its status, configuration, training metrics, and resulting model identifier.
      tags:
      - Fine-Tuning Jobs
      parameters:
      - $ref: '#/components/parameters/JobIdParam'
      responses:
        '200':
          description: Successfully retrieved fine-tuning job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FineTuningJob'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Fine-tuning job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fine_tuning/jobs/{job_id}/cancel:
    post:
      operationId: cancelFineTuningJob
      summary: Cancel fine-tuning job
      description: Request the cancellation of a fine-tuning job. The job will be cancelled if it has not already completed or failed.
      tags:
      - Fine-Tuning Jobs
      parameters:
      - $ref: '#/components/parameters/JobIdParam'
      responses:
        '200':
          description: Successfully cancelled fine-tuning job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FineTuningJob'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Fine-tuning job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fine_tuning/jobs/{job_id}/start:
    post:
      operationId: startFineTuningJob
      summary: Start fine-tuning job
      description: Start a fine-tuning job that was created with auto_start set to false. The job must have passed validation before it can be started.
      tags:
      - Fine-Tuning Jobs
      parameters:
      - $ref: '#/components/parameters/JobIdParam'
      responses:
        '200':
          description: Successfully started fine-tuning job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FineTuningJob'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Fine-tuning job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    FineTuningJob:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the fine-tuning job.
        auto_start:
          type: boolean
          description: Whether the job was configured to auto-start.
        hyperparameters:
          $ref: '#/components/schemas/Hyperparameters'
        model:
          type: string
          description: The base model being fine-tuned.
        status:
          type: string
          description: The current status of the fine-tuning job.
          enum:
          - QUEUED
          - STARTED
          - VALIDATING
          - VALIDATED
          - RUNNING
          - FAILED_VALIDATION
          - FAILED
          - SUCCESS
          - CANCELLED
          - CANCELLATION_REQUESTED
        job_type:
          type: string
          description: The type of fine-tuning job.
        created_at:
          type: integer
          description: Unix timestamp when the job was created.
        modified_at:
          type: integer
          description: Unix timestamp when the job was last modified.
        training_files:
          type: array
          description: The training files used for this job.
          items:
            type: string
            format: uuid
        validation_files:
          type: array
          description: The validation files used for this job.
          items:
            type: string
            format: uuid
        fine_tuned_model:
          type: string
          description: The ID of the fine-tuned model, available after successful completion.
        integrations:
          type: array
          description: The integrations enabled for this job.
          items:
            $ref: '#/components/schemas/Integration'
    TrainingFile:
      type: object
      required:
      - file_id
      properties:
        file_id:
          type: string
          format: uuid
          description: The ID of the uploaded training file.
        weight:
          type: number
          description: The weight of this training file in the training mix.
          default: 1.0
    Integration:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          description: The type of integration.
          enum:
          - wandb
        project:
          type: string
          description: The project name for the integration.
        name:
          type: string
          description: The run name for the integration.
        api_key:
          type: string
          description: The API key for the integration service.
    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.
    Hyperparameters:
      type: object
      properties:
        training_steps:
          type: integer
          description: The number of training steps for the fine-tuning job.
          minimum: 1
        learning_rate:
          type: number
          description: The learning rate for the fine-tuning job.
          minimum: 0.0
        weight_decay:
          type: number
          description: Weight decay applied during training.
          minimum: 0.0
        warmup_fraction:
          type: number
          description: The fraction of training steps to use for warmup.
          minimum: 0.0
          maximum: 1.0
    CreateFineTuningJobRequest:
      type: object
      required:
      - model
      - training_files
      properties:
        model:
          type: string
          description: The name of the model to fine-tune.
          example: open-mistral-7b
        training_files:
          type: array
          description: A collection of training file IDs with optional weights.
          items:
            $ref: '#/components/schemas/TrainingFile'
        validation_files:
          type: array
          description: A collection of validation file IDs.
          items:
            type: string
            format: uuid
        hyperparameters:
          $ref: '#/components/schemas/Hyperparameters'
        suffix:
          type: string
          description: A string that will be added to the fine-tuned model name.
          maxLength: 18
        auto_start:
          type: boolean
          description: Whether to automatically start the fine-tuning job after validation. If false, the job must be started manually.
          default: false
        integrations:
          type: array
          description: A list of integrations to enable for the fine-tuning job, such as Weights and Biases for experiment tracking.
          items:
            $ref: '#/components/schemas/Integration'
    FineTuningJobList:
      type: object
      properties:
        data:
          type: array
          description: A list of fine-tuning jobs.
          items:
            $ref: '#/components/schemas/FineTuningJob'
        total:
          type: integer
          description: The total number of fine-tuning jobs.
  parameters:
    PageParam:
      name: page
      in: query
      required: false
      description: The page number for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    JobIdParam:
      name: job_id
      in: path
      required: true
      description: The ID of the fine-tuning job.
      schema:
        type: string
        format: uuid
    PageSizeParam:
      name: page_size
      in: query
      required: false
      description: The number of items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
externalDocs:
  description: Mistral AI Agents Documentation
  url: https://docs.mistral.ai/api/endpoint/agents