openapi: 3.1.0
info:
  title: Mistral AI Files API
  description: >-
    File management API for uploading, retrieving, downloading, and deleting
    files used across fine-tuning, batch processing, and OCR endpoints.
    Supports files up to 512 MB with various purposes.
  version: '1.0'
  contact:
    name: Mistral AI Support
    url: https://docs.mistral.ai/
    email: support@mistral.ai
  termsOfService: https://mistral.ai/terms/
externalDocs:
  description: Mistral AI Files API Documentation
  url: https://docs.mistral.ai/api/endpoint/files
servers:
  - url: https://api.mistral.ai/v1
    description: Mistral AI Production
tags:
  - name: Files
    description: File management operations
security:
  - bearerAuth: []
paths:
  /files:
    get:
      operationId: listFiles
      summary: Mistral AI List files
      description: Retrieve a list of all uploaded files for the authenticated account.
      tags:
        - Files
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 0
          description: Page number for pagination
        - name: page_size
          in: query
          schema:
            type: integer
            default: 20
          description: Number of items per page
        - name: purpose
          in: query
          schema:
            type: string
            enum:
              - fine-tune
              - batch
              - ocr
          description: Filter files by purpose
      responses:
        '200':
          description: List of files
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileList'
        '401':
          description: Unauthorized
    post:
      operationId: uploadFile
      summary: Mistral AI Upload a file
      description: >-
        Upload a file for use with fine-tuning, batch processing, or OCR.
        Maximum file size is 512 MB.
      tags:
        - Files
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - purpose
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                purpose:
                  type: string
                  enum:
                    - fine-tune
                    - batch
                    - ocr
                  description: Intended purpose of the file
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /files/{file_id}:
    get:
      operationId: getFile
      summary: Mistral AI Get file details
      description: Retrieve metadata about a specific uploaded file.
      tags:
        - Files
      parameters:
        - $ref: '#/components/parameters/fileId'
      responses:
        '200':
          description: File details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '401':
          description: Unauthorized
        '404':
          description: File not found
    delete:
      operationId: deleteFile
      summary: Mistral AI Delete a file
      description: Delete a previously uploaded file.
      tags:
        - Files
      parameters:
        - $ref: '#/components/parameters/fileId'
      responses:
        '200':
          description: File deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFileResponse'
        '401':
          description: Unauthorized
        '404':
          description: File not found
  /files/{file_id}/content:
    get:
      operationId: downloadFile
      summary: Mistral AI Download file content
      description: Download the contents of a previously uploaded file.
      tags:
        - Files
      parameters:
        - $ref: '#/components/parameters/fileId'
      responses:
        '200':
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '404':
          description: File not found
  /files/{file_id}/url:
    get:
      operationId: getFileSignedUrl
      summary: Mistral AI Get a signed download URL
      description: >-
        Get a time-limited signed URL for downloading the file content.
        The URL expires after a short period.
      tags:
        - Files
      parameters:
        - $ref: '#/components/parameters/fileId'
        - name: expiry
          in: query
          schema:
            type: integer
            default: 24
          description: URL expiry time in hours
      responses:
        '200':
          description: Signed URL for downloading
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                    description: Signed download URL
        '401':
          description: Unauthorized
        '404':
          description: File not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Mistral AI API key passed as a Bearer token
  parameters:
    fileId:
      name: file_id
      in: path
      required: true
      description: The unique identifier of the file
      schema:
        type: string
        format: uuid
  schemas:
    File:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the file
        object:
          type: string
          enum:
            - file
        bytes:
          type: integer
          description: File size in bytes
        created_at:
          type: integer
          description: Unix timestamp when the file was uploaded
        filename:
          type: string
          description: Original filename
        purpose:
          type: string
          enum:
            - fine-tune
            - batch
            - ocr
          description: Purpose of the file
        num_lines:
          type:
            - integer
            - 'null'
          description: Number of lines in the file (for JSONL files)
        source:
          type: string
          enum:
            - upload
            - repository
          description: How the file was created
    FileList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/File'
        total:
          type: integer
          description: Total number of files
        object:
          type: string
          enum:
            - list
    DeleteFileResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
          enum:
            - file
        deleted:
          type: boolean