openapi: 3.1.0
info:
  title: Mistral AI Agents Files 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: Files
  description: File management operations
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:
  schemas:
    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
    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
  parameters:
    fileId:
      name: file_id
      in: path
      required: true
      description: The unique identifier of the file
      schema:
        type: string
        format: uuid
  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