components:
  parameters:
    Filename:
      name: filename
      in: path
      required: true
      schema:
        type: string
        description: The name of the file
  schemas:
    FileData:
      type: object
      required:
        - content
      properties:
        content:
          type: string
          format: binary
          description: The content of the file

SaveFile:
  post:
    tags:
      - particles
    summary: Save a file
    description: Save a file to the server (requires authorization)
    operationId: saveFile
    security:
      - bearerAuth: []
    parameters:
      - $ref: '#/components/parameters/Filename'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '#/components/schemas/FileData'
    responses:
      '200':
        description: File saved successfully
      '401':
        description: Unauthorized - Invalid or missing token
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
      '403':
        description: Forbidden - Insufficient permissions
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'

SaveFileForUser:
  post:
    tags:
      - particles
    summary: Save a file for a specific user
    description: Save a file to the server for a specific user (requires head_mod permission)
    operationId: saveFileForUser
    security:
      - bearerAuth: []
    parameters:
      - $ref: '../generic/parameters.yml#/components/parameters/Uuid'
      - $ref: '#/components/parameters/Filename'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '#/components/schemas/FileData'
    responses:
      '200':
        description: File saved successfully
      '401':
        description: Unauthorized - Invalid or missing token
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
      '403':
        description: Forbidden - Insufficient permissions
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'

DownloadFile:
  get:
    tags:
      - particles
    summary: Download a file
    description: Download a file from the server
    operationId: downloadFile
    parameters:
      - $ref: '#/components/parameters/Filename'
    responses:
      '200':
        description: File downloaded successfully
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      '404':
        description: File not found
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'

DownloadFileForUser:
  get:
    tags:
      - particles
    summary: Download a file for a specific user
    description: Download a file from the server for a specific user
    operationId: downloadFileForUser
    security:
      - bearerAuth: []
    parameters:
      - $ref: '../generic/parameters.yml#/components/parameters/Uuid'
      - $ref: '#/components/parameters/Filename'
    responses:
      '200':
        description: File downloaded successfully
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      '401':
        description: Unauthorized - Invalid or missing token
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
      '404':
        description: File not found
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
