openapi: 3.1.0
info:
  title: Mistral AI Fine-Tuning API
  description: >-
    The Mistral AI Fine-Tuning API allows developers to create and manage
    fine-tuning jobs that customize Mistral models on proprietary datasets.
    Users can upload training data, configure hyperparameters, and monitor
    job progress through the API. Fine-tuned models can then be deployed
    and accessed through the Chat Completions endpoint, enabling domain-
    specific performance improvements for enterprise applications.
  version: '1.0.0'
  contact:
    name: Mistral AI Support
    url: https://docs.mistral.ai
  termsOfService: https://mistral.ai/terms
externalDocs:
  description: Mistral AI Fine-Tuning Documentation
  url: https://docs.mistral.ai/api/endpoint/fine-tuning
servers:
  - url: https://api.mistral.ai/v1
    description: Mistral AI Production Server
tags:
  - name: Fine-Tuning Jobs
    description: >-
      Endpoints for creating, managing, and monitoring fine-tuning jobs
      on Mistral AI models.
security:
  - bearerAuth: []
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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  parameters:
    JobIdParam:
      name: job_id
      in: path
      required: true
      description: >-
        The ID of the fine-tuning job.
      schema:
        type: string
        format: uuid
    PageParam:
      name: page
      in: query
      required: false
      description: >-
        The page number for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    PageSizeParam:
      name: page_size
      in: query
      required: false
      description: >-
        The number of items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  schemas:
    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'
    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
    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
    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.
    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'
    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.
    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.