openapi: 3.1.0
info:
  title: Mistral AI Forge API
  description: >-
    Mistral AI Forge is a model-training platform providing a unified API for
    the entire model lifecycle from pre-training to reinforcement learning.
    Forge enables enterprises to build frontier-grade AI models grounded in
    proprietary knowledge, supporting pre-training on large internal datasets,
    post-training through supervised fine-tuning with DPO and ODPO, and
    reinforcement learning pipelines for aligning models with internal policies.
    Forge is optimized for agentic workflows, allowing AI agents to
    programmatically schedule training jobs, optimize hyperparameters, and
    generate synthetic data.
  version: '1.0.0'
  contact:
    name: Mistral AI Support
    url: https://docs.mistral.ai
  termsOfService: https://mistral.ai/terms
externalDocs:
  description: Mistral AI Forge Documentation
  url: https://mistral.ai/news/forge
servers:
  - url: https://api.mistral.ai
    description: Mistral AI Production Server
tags:
  - name: Training Jobs
    description: >-
      Endpoints for creating and managing training jobs including pre-training,
      supervised fine-tuning, and reinforcement learning pipelines.
security:
  - bearerAuth: []
paths:
  /forge/training/jobs:
    post:
      operationId: createTrainingJob
      summary: Create training job
      description: >-
        Creates a new Forge training job for pre-training, post-training, or
        reinforcement learning. Supports Dense and Mixture-of-Experts model
        architectures with configurable hyperparameters and training stages.
      tags:
        - Training Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTrainingJobRequest'
      responses:
        '200':
          description: Successfully created training job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainingJob'
        '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: listTrainingJobs
      summary: List training jobs
      description: >-
        List all Forge training jobs for the organization. Returns a paginated
        list of jobs with their current status and configuration.
      tags:
        - Training Jobs
      parameters:
        - name: page
          in: query
          required: false
          description: >-
            The page number for pagination.
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: page_size
          in: query
          required: false
          description: >-
            The number of items per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Successfully retrieved list of training jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainingJobList'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forge/training/jobs/{job_id}:
    get:
      operationId: getTrainingJob
      summary: Get training job
      description: >-
        Retrieve information about a specific Forge training job including
        its status, configuration, and training metrics.
      tags:
        - Training Jobs
      parameters:
        - name: job_id
          in: path
          required: true
          description: >-
            The ID of the training job.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved training job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainingJob'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Training job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forge/training/jobs/{job_id}/cancel:
    post:
      operationId: cancelTrainingJob
      summary: Cancel training job
      description: >-
        Request the cancellation of a Forge training job.
      tags:
        - Training Jobs
      parameters:
        - name: job_id
          in: path
          required: true
          description: >-
            The ID of the training job.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully cancelled training job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainingJob'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Training job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  schemas:
    CreateTrainingJobRequest:
      type: object
      required:
        - job_type
        - model_config
      properties:
        job_type:
          type: string
          description: >-
            The type of training job to create.
          enum:
            - pre_training
            - supervised_fine_tuning
            - dpo
            - odpo
            - reinforcement_learning
        model_config:
          $ref: '#/components/schemas/ModelConfig'
        dataset_ids:
          type: array
          description: >-
            The IDs of datasets to use for training.
          items:
            type: string
            format: uuid
        hyperparameters:
          $ref: '#/components/schemas/ForgeHyperparameters'
        auto_start:
          type: boolean
          description: >-
            Whether to automatically start the training job after validation.
          default: false
    ModelConfig:
      type: object
      properties:
        architecture:
          type: string
          description: >-
            The model architecture to use.
          enum:
            - dense
            - mixture_of_experts
        base_model:
          type: string
          description: >-
            The base model to start from. Required for post-training and
            reinforcement learning jobs.
        num_experts:
          type: integer
          description: >-
            Number of experts for MoE architecture.
          minimum: 1
        active_experts:
          type: integer
          description: >-
            Number of active experts per token for MoE architecture.
          minimum: 1
    ForgeHyperparameters:
      type: object
      properties:
        learning_rate:
          type: number
          description: >-
            The learning rate for training.
          minimum: 0.0
        training_steps:
          type: integer
          description: >-
            The number of training steps.
          minimum: 1
        batch_size:
          type: integer
          description: >-
            The batch size for training.
          minimum: 1
        weight_decay:
          type: number
          description: >-
            Weight decay applied during training.
          minimum: 0.0
        warmup_steps:
          type: integer
          description: >-
            Number of warmup steps.
          minimum: 0
    TrainingJob:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: >-
            The unique identifier for the training job.
        job_type:
          type: string
          description: >-
            The type of training job.
        status:
          type: string
          description: >-
            The current status of the training job.
          enum:
            - QUEUED
            - VALIDATING
            - RUNNING
            - SUCCESS
            - FAILED
            - CANCELLED
        model_config:
          $ref: '#/components/schemas/ModelConfig'
        hyperparameters:
          $ref: '#/components/schemas/ForgeHyperparameters'
        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.
        output_model:
          type: string
          description: >-
            The ID of the resulting trained model, available after success.
    TrainingJobList:
      type: object
      properties:
        data:
          type: array
          description: >-
            A list of training jobs.
          items:
            $ref: '#/components/schemas/TrainingJob'
        total:
          type: integer
          description: >-
            The total number of training 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.