backbone-bucket 0.4.3

openapi: '3.0.3'
info:
  title: Backbone API
  version: '1.0.0'
  description: |
    Auto-generated by backbone-cli.
    This API provides 11 standard CRUD endpoints for each model.

servers:
  - url: /
    description: Development server

tags:
  - name: AccessLogs
    description: AccessLog management endpoints
  - name: Buckets
    description: Bucket management endpoints
  - name: ContentHashes
    description: ContentHash management endpoints
  - name: ConversionJobs
    description: ConversionJob management endpoints
  - name: FileComments
    description: FileComment management endpoints
  - name: FileLocks
    description: FileLock management endpoints
  - name: FileShares
    description: FileShare management endpoints
  - name: FileVersions
    description: FileVersion management endpoints
  - name: ProcessingJobs
    description: ProcessingJob management endpoints
  - name: StoredFiles
    description: StoredFile management endpoints
  - name: Thumbnails
    description: Thumbnail management endpoints
  - name: UploadSessions
    description: UploadSession management endpoints
  - name: UserQuotas
    description: UserQuota management endpoints

paths:
  /api/v1/bucket/access_logs:
    get:
      tags:
        - AccessLogs
      summary: List AccessLogs
      description: Get a paginated list of AccessLogs with optional filtering and sorting
      operationId: listAccessLogs
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLogList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - AccessLogs
      summary: Create AccessLog
      description: Create a new AccessLog
      operationId: createAccessLog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccessLogRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLog'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/access_logs/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - AccessLogs
      summary: Get AccessLog by ID
      operationId: getAccessLog
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLog'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - AccessLogs
      summary: Update AccessLog (full)
      operationId: updateAccessLog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccessLogRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLog'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - AccessLogs
      summary: Update AccessLog (partial)
      operationId: patchAccessLog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchAccessLogRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLog'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - AccessLogs
      summary: Delete AccessLog (soft)
      operationId: deleteAccessLog
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/access_logs/bulk:
    post:
      tags:
        - AccessLogs
      summary: Bulk create AccessLogs
      operationId: bulkCreateAccessLogs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateAccessLogRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccessLog'
    put:
      tags:
        - AccessLogs
      summary: Bulk update AccessLogs (full, atomic)
      operationId: bulkUpdateAccessLogs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateAccessLogRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLogBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - AccessLogs
      summary: Bulk partial-update AccessLogs (atomic)
      operationId: bulkPatchAccessLogs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLogBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/access_logs/upsert:
    post:
      tags:
        - AccessLogs
      summary: Upsert AccessLog
      operationId: upsertAccessLog
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccessLogRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLog'

  /api/v1/bucket/access_logs/trash:
    get:
      tags:
        - AccessLogs
      summary: List deleted AccessLogs
      operationId: listDeletedAccessLogs
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLogList'

  /api/v1/bucket/access_logs/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - AccessLogs
      summary: Restore deleted AccessLog
      operationId: restoreAccessLog
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLog'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/access_logs/empty:
    delete:
      tags:
        - AccessLogs
      summary: Empty trash for AccessLogs
      operationId: emptyTrashAccessLogs
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/access_logs/delete/bulk:
    post:
      tags:
        - AccessLogs
      summary: Bulk soft-delete AccessLogs by ids (atomic)
      operationId: bulkDeleteAccessLogs
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/access_logs/restore/bulk:
    post:
      tags:
        - AccessLogs
      summary: Bulk restore AccessLogs by ids (atomic)
      operationId: bulkRestoreAccessLogs
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLogBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/access_logs/restore/all:
    post:
      tags:
        - AccessLogs
      summary: Restore all soft-deleted AccessLogs
      operationId: restoreAllAccessLogs
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/access_logs/trash/bulk:
    delete:
      tags:
        - AccessLogs
      summary: Bulk permanently-delete AccessLogs from trash by ids (atomic)
      operationId: bulkPermanentDeleteAccessLogs
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/buckets:
    get:
      tags:
        - Buckets
      summary: List Buckets
      description: Get a paginated list of Buckets with optional filtering and sorting
      operationId: listBuckets
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - Buckets
      summary: Create Bucket
      description: Create a new Bucket
      operationId: createBucket
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBucketRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/buckets/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - Buckets
      summary: Get Bucket by ID
      operationId: getBucket
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Buckets
      summary: Update Bucket (full)
      operationId: updateBucket
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBucketRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - Buckets
      summary: Update Bucket (partial)
      operationId: patchBucket
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchBucketRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Buckets
      summary: Delete Bucket (soft)
      operationId: deleteBucket
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/buckets/bulk:
    post:
      tags:
        - Buckets
      summary: Bulk create Buckets
      operationId: bulkCreateBuckets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateBucketRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bucket'
    put:
      tags:
        - Buckets
      summary: Bulk update Buckets (full, atomic)
      operationId: bulkUpdateBuckets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateBucketRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - Buckets
      summary: Bulk partial-update Buckets (atomic)
      operationId: bulkPatchBuckets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/buckets/upsert:
    post:
      tags:
        - Buckets
      summary: Upsert Bucket
      operationId: upsertBucket
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBucketRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'

  /api/v1/bucket/buckets/trash:
    get:
      tags:
        - Buckets
      summary: List deleted Buckets
      operationId: listDeletedBuckets
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketList'

  /api/v1/bucket/buckets/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - Buckets
      summary: Restore deleted Bucket
      operationId: restoreBucket
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/buckets/empty:
    delete:
      tags:
        - Buckets
      summary: Empty trash for Buckets
      operationId: emptyTrashBuckets
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/buckets/delete/bulk:
    post:
      tags:
        - Buckets
      summary: Bulk soft-delete Buckets by ids (atomic)
      operationId: bulkDeleteBuckets
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/buckets/restore/bulk:
    post:
      tags:
        - Buckets
      summary: Bulk restore Buckets by ids (atomic)
      operationId: bulkRestoreBuckets
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/buckets/restore/all:
    post:
      tags:
        - Buckets
      summary: Restore all soft-deleted Buckets
      operationId: restoreAllBuckets
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/buckets/trash/bulk:
    delete:
      tags:
        - Buckets
      summary: Bulk permanently-delete Buckets from trash by ids (atomic)
      operationId: bulkPermanentDeleteBuckets
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/content_hashes:
    get:
      tags:
        - ContentHashes
      summary: List ContentHashes
      description: Get a paginated list of ContentHashes with optional filtering and sorting
      operationId: listContentHashes
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHashList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - ContentHashes
      summary: Create ContentHash
      description: Create a new ContentHash
      operationId: createContentHash
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContentHashRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHash'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/content_hashes/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - ContentHashes
      summary: Get ContentHash by ID
      operationId: getContentHash
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHash'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - ContentHashes
      summary: Update ContentHash (full)
      operationId: updateContentHash
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContentHashRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHash'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - ContentHashes
      summary: Update ContentHash (partial)
      operationId: patchContentHash
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchContentHashRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHash'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - ContentHashes
      summary: Delete ContentHash (soft)
      operationId: deleteContentHash
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/content_hashes/bulk:
    post:
      tags:
        - ContentHashes
      summary: Bulk create ContentHashes
      operationId: bulkCreateContentHashes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateContentHashRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContentHash'
    put:
      tags:
        - ContentHashes
      summary: Bulk update ContentHashes (full, atomic)
      operationId: bulkUpdateContentHashes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateContentHashRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHashBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - ContentHashes
      summary: Bulk partial-update ContentHashes (atomic)
      operationId: bulkPatchContentHashes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHashBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/content_hashes/upsert:
    post:
      tags:
        - ContentHashes
      summary: Upsert ContentHash
      operationId: upsertContentHash
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContentHashRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHash'

  /api/v1/bucket/content_hashes/trash:
    get:
      tags:
        - ContentHashes
      summary: List deleted ContentHashes
      operationId: listDeletedContentHashes
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHashList'

  /api/v1/bucket/content_hashes/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - ContentHashes
      summary: Restore deleted ContentHash
      operationId: restoreContentHash
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHash'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/content_hashes/empty:
    delete:
      tags:
        - ContentHashes
      summary: Empty trash for ContentHashes
      operationId: emptyTrashContentHashes
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/content_hashes/delete/bulk:
    post:
      tags:
        - ContentHashes
      summary: Bulk soft-delete ContentHashes by ids (atomic)
      operationId: bulkDeleteContentHashes
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/content_hashes/restore/bulk:
    post:
      tags:
        - ContentHashes
      summary: Bulk restore ContentHashes by ids (atomic)
      operationId: bulkRestoreContentHashes
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHashBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/content_hashes/restore/all:
    post:
      tags:
        - ContentHashes
      summary: Restore all soft-deleted ContentHashes
      operationId: restoreAllContentHashes
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/content_hashes/trash/bulk:
    delete:
      tags:
        - ContentHashes
      summary: Bulk permanently-delete ContentHashes from trash by ids (atomic)
      operationId: bulkPermanentDeleteContentHashes
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/conversion_jobs:
    get:
      tags:
        - ConversionJobs
      summary: List ConversionJobs
      description: Get a paginated list of ConversionJobs with optional filtering and sorting
      operationId: listConversionJobs
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionJobList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - ConversionJobs
      summary: Create ConversionJob
      description: Create a new ConversionJob
      operationId: createConversionJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversionJobRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/conversion_jobs/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - ConversionJobs
      summary: Get ConversionJob by ID
      operationId: getConversionJob
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionJob'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - ConversionJobs
      summary: Update ConversionJob (full)
      operationId: updateConversionJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConversionJobRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionJob'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - ConversionJobs
      summary: Update ConversionJob (partial)
      operationId: patchConversionJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchConversionJobRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionJob'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - ConversionJobs
      summary: Delete ConversionJob (soft)
      operationId: deleteConversionJob
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/conversion_jobs/bulk:
    post:
      tags:
        - ConversionJobs
      summary: Bulk create ConversionJobs
      operationId: bulkCreateConversionJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateConversionJobRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConversionJob'
    put:
      tags:
        - ConversionJobs
      summary: Bulk update ConversionJobs (full, atomic)
      operationId: bulkUpdateConversionJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateConversionJobRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionJobBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - ConversionJobs
      summary: Bulk partial-update ConversionJobs (atomic)
      operationId: bulkPatchConversionJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionJobBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/conversion_jobs/upsert:
    post:
      tags:
        - ConversionJobs
      summary: Upsert ConversionJob
      operationId: upsertConversionJob
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConversionJobRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionJob'

  /api/v1/bucket/conversion_jobs/trash:
    get:
      tags:
        - ConversionJobs
      summary: List deleted ConversionJobs
      operationId: listDeletedConversionJobs
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionJobList'

  /api/v1/bucket/conversion_jobs/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - ConversionJobs
      summary: Restore deleted ConversionJob
      operationId: restoreConversionJob
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionJob'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/conversion_jobs/empty:
    delete:
      tags:
        - ConversionJobs
      summary: Empty trash for ConversionJobs
      operationId: emptyTrashConversionJobs
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/conversion_jobs/delete/bulk:
    post:
      tags:
        - ConversionJobs
      summary: Bulk soft-delete ConversionJobs by ids (atomic)
      operationId: bulkDeleteConversionJobs
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/conversion_jobs/restore/bulk:
    post:
      tags:
        - ConversionJobs
      summary: Bulk restore ConversionJobs by ids (atomic)
      operationId: bulkRestoreConversionJobs
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionJobBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/conversion_jobs/restore/all:
    post:
      tags:
        - ConversionJobs
      summary: Restore all soft-deleted ConversionJobs
      operationId: restoreAllConversionJobs
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/conversion_jobs/trash/bulk:
    delete:
      tags:
        - ConversionJobs
      summary: Bulk permanently-delete ConversionJobs from trash by ids (atomic)
      operationId: bulkPermanentDeleteConversionJobs
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_comments:
    get:
      tags:
        - FileComments
      summary: List FileComments
      description: Get a paginated list of FileComments with optional filtering and sorting
      operationId: listFileComments
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileCommentList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - FileComments
      summary: Create FileComment
      description: Create a new FileComment
      operationId: createFileComment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFileCommentRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileComment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/file_comments/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - FileComments
      summary: Get FileComment by ID
      operationId: getFileComment
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileComment'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - FileComments
      summary: Update FileComment (full)
      operationId: updateFileComment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileCommentRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileComment'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - FileComments
      summary: Update FileComment (partial)
      operationId: patchFileComment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchFileCommentRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileComment'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - FileComments
      summary: Delete FileComment (soft)
      operationId: deleteFileComment
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/file_comments/bulk:
    post:
      tags:
        - FileComments
      summary: Bulk create FileComments
      operationId: bulkCreateFileComments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateFileCommentRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileComment'
    put:
      tags:
        - FileComments
      summary: Bulk update FileComments (full, atomic)
      operationId: bulkUpdateFileComments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateFileCommentRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileCommentBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - FileComments
      summary: Bulk partial-update FileComments (atomic)
      operationId: bulkPatchFileComments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileCommentBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_comments/upsert:
    post:
      tags:
        - FileComments
      summary: Upsert FileComment
      operationId: upsertFileComment
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileCommentRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileComment'

  /api/v1/bucket/file_comments/trash:
    get:
      tags:
        - FileComments
      summary: List deleted FileComments
      operationId: listDeletedFileComments
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileCommentList'

  /api/v1/bucket/file_comments/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - FileComments
      summary: Restore deleted FileComment
      operationId: restoreFileComment
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileComment'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/file_comments/empty:
    delete:
      tags:
        - FileComments
      summary: Empty trash for FileComments
      operationId: emptyTrashFileComments
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/file_comments/delete/bulk:
    post:
      tags:
        - FileComments
      summary: Bulk soft-delete FileComments by ids (atomic)
      operationId: bulkDeleteFileComments
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_comments/restore/bulk:
    post:
      tags:
        - FileComments
      summary: Bulk restore FileComments by ids (atomic)
      operationId: bulkRestoreFileComments
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileCommentBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_comments/restore/all:
    post:
      tags:
        - FileComments
      summary: Restore all soft-deleted FileComments
      operationId: restoreAllFileComments
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/file_comments/trash/bulk:
    delete:
      tags:
        - FileComments
      summary: Bulk permanently-delete FileComments from trash by ids (atomic)
      operationId: bulkPermanentDeleteFileComments
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_locks:
    get:
      tags:
        - FileLocks
      summary: List FileLocks
      description: Get a paginated list of FileLocks with optional filtering and sorting
      operationId: listFileLocks
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileLockList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - FileLocks
      summary: Create FileLock
      description: Create a new FileLock
      operationId: createFileLock
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFileLockRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileLock'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/file_locks/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - FileLocks
      summary: Get FileLock by ID
      operationId: getFileLock
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileLock'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - FileLocks
      summary: Update FileLock (full)
      operationId: updateFileLock
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileLockRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileLock'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - FileLocks
      summary: Update FileLock (partial)
      operationId: patchFileLock
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchFileLockRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileLock'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - FileLocks
      summary: Delete FileLock (soft)
      operationId: deleteFileLock
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/file_locks/bulk:
    post:
      tags:
        - FileLocks
      summary: Bulk create FileLocks
      operationId: bulkCreateFileLocks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateFileLockRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileLock'
    put:
      tags:
        - FileLocks
      summary: Bulk update FileLocks (full, atomic)
      operationId: bulkUpdateFileLocks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateFileLockRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileLockBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - FileLocks
      summary: Bulk partial-update FileLocks (atomic)
      operationId: bulkPatchFileLocks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileLockBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_locks/upsert:
    post:
      tags:
        - FileLocks
      summary: Upsert FileLock
      operationId: upsertFileLock
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileLockRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileLock'

  /api/v1/bucket/file_locks/trash:
    get:
      tags:
        - FileLocks
      summary: List deleted FileLocks
      operationId: listDeletedFileLocks
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileLockList'

  /api/v1/bucket/file_locks/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - FileLocks
      summary: Restore deleted FileLock
      operationId: restoreFileLock
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileLock'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/file_locks/empty:
    delete:
      tags:
        - FileLocks
      summary: Empty trash for FileLocks
      operationId: emptyTrashFileLocks
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/file_locks/delete/bulk:
    post:
      tags:
        - FileLocks
      summary: Bulk soft-delete FileLocks by ids (atomic)
      operationId: bulkDeleteFileLocks
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_locks/restore/bulk:
    post:
      tags:
        - FileLocks
      summary: Bulk restore FileLocks by ids (atomic)
      operationId: bulkRestoreFileLocks
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileLockBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_locks/restore/all:
    post:
      tags:
        - FileLocks
      summary: Restore all soft-deleted FileLocks
      operationId: restoreAllFileLocks
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/file_locks/trash/bulk:
    delete:
      tags:
        - FileLocks
      summary: Bulk permanently-delete FileLocks from trash by ids (atomic)
      operationId: bulkPermanentDeleteFileLocks
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_shares:
    get:
      tags:
        - FileShares
      summary: List FileShares
      description: Get a paginated list of FileShares with optional filtering and sorting
      operationId: listFileShares
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileShareList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - FileShares
      summary: Create FileShare
      description: Create a new FileShare
      operationId: createFileShare
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFileShareRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileShare'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/file_shares/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - FileShares
      summary: Get FileShare by ID
      operationId: getFileShare
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileShare'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - FileShares
      summary: Update FileShare (full)
      operationId: updateFileShare
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileShareRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileShare'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - FileShares
      summary: Update FileShare (partial)
      operationId: patchFileShare
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchFileShareRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileShare'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - FileShares
      summary: Delete FileShare (soft)
      operationId: deleteFileShare
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/file_shares/bulk:
    post:
      tags:
        - FileShares
      summary: Bulk create FileShares
      operationId: bulkCreateFileShares
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateFileShareRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileShare'
    put:
      tags:
        - FileShares
      summary: Bulk update FileShares (full, atomic)
      operationId: bulkUpdateFileShares
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateFileShareRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileShareBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - FileShares
      summary: Bulk partial-update FileShares (atomic)
      operationId: bulkPatchFileShares
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileShareBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_shares/upsert:
    post:
      tags:
        - FileShares
      summary: Upsert FileShare
      operationId: upsertFileShare
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileShareRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileShare'

  /api/v1/bucket/file_shares/trash:
    get:
      tags:
        - FileShares
      summary: List deleted FileShares
      operationId: listDeletedFileShares
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileShareList'

  /api/v1/bucket/file_shares/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - FileShares
      summary: Restore deleted FileShare
      operationId: restoreFileShare
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileShare'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/file_shares/empty:
    delete:
      tags:
        - FileShares
      summary: Empty trash for FileShares
      operationId: emptyTrashFileShares
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/file_shares/delete/bulk:
    post:
      tags:
        - FileShares
      summary: Bulk soft-delete FileShares by ids (atomic)
      operationId: bulkDeleteFileShares
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_shares/restore/bulk:
    post:
      tags:
        - FileShares
      summary: Bulk restore FileShares by ids (atomic)
      operationId: bulkRestoreFileShares
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileShareBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_shares/restore/all:
    post:
      tags:
        - FileShares
      summary: Restore all soft-deleted FileShares
      operationId: restoreAllFileShares
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/file_shares/trash/bulk:
    delete:
      tags:
        - FileShares
      summary: Bulk permanently-delete FileShares from trash by ids (atomic)
      operationId: bulkPermanentDeleteFileShares
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_versions:
    get:
      tags:
        - FileVersions
      summary: List FileVersions
      description: Get a paginated list of FileVersions with optional filtering and sorting
      operationId: listFileVersions
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersionList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - FileVersions
      summary: Create FileVersion
      description: Create a new FileVersion
      operationId: createFileVersion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFileVersionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersion'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/file_versions/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - FileVersions
      summary: Get FileVersion by ID
      operationId: getFileVersion
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersion'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - FileVersions
      summary: Update FileVersion (full)
      operationId: updateFileVersion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileVersionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersion'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - FileVersions
      summary: Update FileVersion (partial)
      operationId: patchFileVersion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchFileVersionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersion'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - FileVersions
      summary: Delete FileVersion (soft)
      operationId: deleteFileVersion
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/file_versions/bulk:
    post:
      tags:
        - FileVersions
      summary: Bulk create FileVersions
      operationId: bulkCreateFileVersions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateFileVersionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileVersion'
    put:
      tags:
        - FileVersions
      summary: Bulk update FileVersions (full, atomic)
      operationId: bulkUpdateFileVersions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateFileVersionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - FileVersions
      summary: Bulk partial-update FileVersions (atomic)
      operationId: bulkPatchFileVersions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_versions/upsert:
    post:
      tags:
        - FileVersions
      summary: Upsert FileVersion
      operationId: upsertFileVersion
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileVersionRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersion'

  /api/v1/bucket/file_versions/trash:
    get:
      tags:
        - FileVersions
      summary: List deleted FileVersions
      operationId: listDeletedFileVersions
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersionList'

  /api/v1/bucket/file_versions/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - FileVersions
      summary: Restore deleted FileVersion
      operationId: restoreFileVersion
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersion'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/file_versions/empty:
    delete:
      tags:
        - FileVersions
      summary: Empty trash for FileVersions
      operationId: emptyTrashFileVersions
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/file_versions/delete/bulk:
    post:
      tags:
        - FileVersions
      summary: Bulk soft-delete FileVersions by ids (atomic)
      operationId: bulkDeleteFileVersions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_versions/restore/bulk:
    post:
      tags:
        - FileVersions
      summary: Bulk restore FileVersions by ids (atomic)
      operationId: bulkRestoreFileVersions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/file_versions/restore/all:
    post:
      tags:
        - FileVersions
      summary: Restore all soft-deleted FileVersions
      operationId: restoreAllFileVersions
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/file_versions/trash/bulk:
    delete:
      tags:
        - FileVersions
      summary: Bulk permanently-delete FileVersions from trash by ids (atomic)
      operationId: bulkPermanentDeleteFileVersions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/processing_jobs:
    get:
      tags:
        - ProcessingJobs
      summary: List ProcessingJobs
      description: Get a paginated list of ProcessingJobs with optional filtering and sorting
      operationId: listProcessingJobs
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJobList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - ProcessingJobs
      summary: Create ProcessingJob
      description: Create a new ProcessingJob
      operationId: createProcessingJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProcessingJobRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/processing_jobs/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - ProcessingJobs
      summary: Get ProcessingJob by ID
      operationId: getProcessingJob
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJob'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - ProcessingJobs
      summary: Update ProcessingJob (full)
      operationId: updateProcessingJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProcessingJobRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJob'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - ProcessingJobs
      summary: Update ProcessingJob (partial)
      operationId: patchProcessingJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchProcessingJobRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJob'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - ProcessingJobs
      summary: Delete ProcessingJob (soft)
      operationId: deleteProcessingJob
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/processing_jobs/bulk:
    post:
      tags:
        - ProcessingJobs
      summary: Bulk create ProcessingJobs
      operationId: bulkCreateProcessingJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateProcessingJobRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProcessingJob'
    put:
      tags:
        - ProcessingJobs
      summary: Bulk update ProcessingJobs (full, atomic)
      operationId: bulkUpdateProcessingJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateProcessingJobRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJobBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - ProcessingJobs
      summary: Bulk partial-update ProcessingJobs (atomic)
      operationId: bulkPatchProcessingJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJobBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/processing_jobs/upsert:
    post:
      tags:
        - ProcessingJobs
      summary: Upsert ProcessingJob
      operationId: upsertProcessingJob
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProcessingJobRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJob'

  /api/v1/bucket/processing_jobs/trash:
    get:
      tags:
        - ProcessingJobs
      summary: List deleted ProcessingJobs
      operationId: listDeletedProcessingJobs
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJobList'

  /api/v1/bucket/processing_jobs/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - ProcessingJobs
      summary: Restore deleted ProcessingJob
      operationId: restoreProcessingJob
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJob'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/processing_jobs/empty:
    delete:
      tags:
        - ProcessingJobs
      summary: Empty trash for ProcessingJobs
      operationId: emptyTrashProcessingJobs
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/processing_jobs/delete/bulk:
    post:
      tags:
        - ProcessingJobs
      summary: Bulk soft-delete ProcessingJobs by ids (atomic)
      operationId: bulkDeleteProcessingJobs
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/processing_jobs/restore/bulk:
    post:
      tags:
        - ProcessingJobs
      summary: Bulk restore ProcessingJobs by ids (atomic)
      operationId: bulkRestoreProcessingJobs
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJobBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/processing_jobs/restore/all:
    post:
      tags:
        - ProcessingJobs
      summary: Restore all soft-deleted ProcessingJobs
      operationId: restoreAllProcessingJobs
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/processing_jobs/trash/bulk:
    delete:
      tags:
        - ProcessingJobs
      summary: Bulk permanently-delete ProcessingJobs from trash by ids (atomic)
      operationId: bulkPermanentDeleteProcessingJobs
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/stored_files:
    get:
      tags:
        - StoredFiles
      summary: List StoredFiles
      description: Get a paginated list of StoredFiles with optional filtering and sorting
      operationId: listStoredFiles
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFileList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - StoredFiles
      summary: Create StoredFile
      description: Create a new StoredFile
      operationId: createStoredFile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStoredFileRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/stored_files/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - StoredFiles
      summary: Get StoredFile by ID
      operationId: getStoredFile
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFile'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - StoredFiles
      summary: Update StoredFile (full)
      operationId: updateStoredFile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStoredFileRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFile'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - StoredFiles
      summary: Update StoredFile (partial)
      operationId: patchStoredFile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchStoredFileRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFile'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - StoredFiles
      summary: Delete StoredFile (soft)
      operationId: deleteStoredFile
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/stored_files/bulk:
    post:
      tags:
        - StoredFiles
      summary: Bulk create StoredFiles
      operationId: bulkCreateStoredFiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateStoredFileRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoredFile'
    put:
      tags:
        - StoredFiles
      summary: Bulk update StoredFiles (full, atomic)
      operationId: bulkUpdateStoredFiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateStoredFileRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFileBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - StoredFiles
      summary: Bulk partial-update StoredFiles (atomic)
      operationId: bulkPatchStoredFiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFileBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/stored_files/upsert:
    post:
      tags:
        - StoredFiles
      summary: Upsert StoredFile
      operationId: upsertStoredFile
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStoredFileRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFile'

  /api/v1/bucket/stored_files/trash:
    get:
      tags:
        - StoredFiles
      summary: List deleted StoredFiles
      operationId: listDeletedStoredFiles
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFileList'

  /api/v1/bucket/stored_files/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - StoredFiles
      summary: Restore deleted StoredFile
      operationId: restoreStoredFile
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFile'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/stored_files/empty:
    delete:
      tags:
        - StoredFiles
      summary: Empty trash for StoredFiles
      operationId: emptyTrashStoredFiles
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/stored_files/delete/bulk:
    post:
      tags:
        - StoredFiles
      summary: Bulk soft-delete StoredFiles by ids (atomic)
      operationId: bulkDeleteStoredFiles
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/stored_files/restore/bulk:
    post:
      tags:
        - StoredFiles
      summary: Bulk restore StoredFiles by ids (atomic)
      operationId: bulkRestoreStoredFiles
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFileBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/stored_files/restore/all:
    post:
      tags:
        - StoredFiles
      summary: Restore all soft-deleted StoredFiles
      operationId: restoreAllStoredFiles
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/stored_files/trash/bulk:
    delete:
      tags:
        - StoredFiles
      summary: Bulk permanently-delete StoredFiles from trash by ids (atomic)
      operationId: bulkPermanentDeleteStoredFiles
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/thumbnails:
    get:
      tags:
        - Thumbnails
      summary: List Thumbnails
      description: Get a paginated list of Thumbnails with optional filtering and sorting
      operationId: listThumbnails
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThumbnailList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - Thumbnails
      summary: Create Thumbnail
      description: Create a new Thumbnail
      operationId: createThumbnail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateThumbnailRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thumbnail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/thumbnails/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - Thumbnails
      summary: Get Thumbnail by ID
      operationId: getThumbnail
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thumbnail'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Thumbnails
      summary: Update Thumbnail (full)
      operationId: updateThumbnail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateThumbnailRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thumbnail'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - Thumbnails
      summary: Update Thumbnail (partial)
      operationId: patchThumbnail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchThumbnailRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thumbnail'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Thumbnails
      summary: Delete Thumbnail (soft)
      operationId: deleteThumbnail
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/thumbnails/bulk:
    post:
      tags:
        - Thumbnails
      summary: Bulk create Thumbnails
      operationId: bulkCreateThumbnails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateThumbnailRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Thumbnail'
    put:
      tags:
        - Thumbnails
      summary: Bulk update Thumbnails (full, atomic)
      operationId: bulkUpdateThumbnails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateThumbnailRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThumbnailBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - Thumbnails
      summary: Bulk partial-update Thumbnails (atomic)
      operationId: bulkPatchThumbnails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThumbnailBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/thumbnails/upsert:
    post:
      tags:
        - Thumbnails
      summary: Upsert Thumbnail
      operationId: upsertThumbnail
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateThumbnailRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thumbnail'

  /api/v1/bucket/thumbnails/trash:
    get:
      tags:
        - Thumbnails
      summary: List deleted Thumbnails
      operationId: listDeletedThumbnails
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThumbnailList'

  /api/v1/bucket/thumbnails/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - Thumbnails
      summary: Restore deleted Thumbnail
      operationId: restoreThumbnail
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thumbnail'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/thumbnails/empty:
    delete:
      tags:
        - Thumbnails
      summary: Empty trash for Thumbnails
      operationId: emptyTrashThumbnails
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/thumbnails/delete/bulk:
    post:
      tags:
        - Thumbnails
      summary: Bulk soft-delete Thumbnails by ids (atomic)
      operationId: bulkDeleteThumbnails
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/thumbnails/restore/bulk:
    post:
      tags:
        - Thumbnails
      summary: Bulk restore Thumbnails by ids (atomic)
      operationId: bulkRestoreThumbnails
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThumbnailBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/thumbnails/restore/all:
    post:
      tags:
        - Thumbnails
      summary: Restore all soft-deleted Thumbnails
      operationId: restoreAllThumbnails
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/thumbnails/trash/bulk:
    delete:
      tags:
        - Thumbnails
      summary: Bulk permanently-delete Thumbnails from trash by ids (atomic)
      operationId: bulkPermanentDeleteThumbnails
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/upload_sessions:
    get:
      tags:
        - UploadSessions
      summary: List UploadSessions
      description: Get a paginated list of UploadSessions with optional filtering and sorting
      operationId: listUploadSessions
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSessionList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - UploadSessions
      summary: Create UploadSession
      description: Create a new UploadSession
      operationId: createUploadSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUploadSessionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/upload_sessions/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - UploadSessions
      summary: Get UploadSession by ID
      operationId: getUploadSession
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - UploadSessions
      summary: Update UploadSession (full)
      operationId: updateUploadSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUploadSessionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - UploadSessions
      summary: Update UploadSession (partial)
      operationId: patchUploadSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchUploadSessionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - UploadSessions
      summary: Delete UploadSession (soft)
      operationId: deleteUploadSession
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/upload_sessions/bulk:
    post:
      tags:
        - UploadSessions
      summary: Bulk create UploadSessions
      operationId: bulkCreateUploadSessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateUploadSessionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UploadSession'
    put:
      tags:
        - UploadSessions
      summary: Bulk update UploadSessions (full, atomic)
      operationId: bulkUpdateUploadSessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateUploadSessionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSessionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - UploadSessions
      summary: Bulk partial-update UploadSessions (atomic)
      operationId: bulkPatchUploadSessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSessionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/upload_sessions/upsert:
    post:
      tags:
        - UploadSessions
      summary: Upsert UploadSession
      operationId: upsertUploadSession
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUploadSessionRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'

  /api/v1/bucket/upload_sessions/trash:
    get:
      tags:
        - UploadSessions
      summary: List deleted UploadSessions
      operationId: listDeletedUploadSessions
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSessionList'

  /api/v1/bucket/upload_sessions/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - UploadSessions
      summary: Restore deleted UploadSession
      operationId: restoreUploadSession
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/upload_sessions/empty:
    delete:
      tags:
        - UploadSessions
      summary: Empty trash for UploadSessions
      operationId: emptyTrashUploadSessions
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/upload_sessions/delete/bulk:
    post:
      tags:
        - UploadSessions
      summary: Bulk soft-delete UploadSessions by ids (atomic)
      operationId: bulkDeleteUploadSessions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/upload_sessions/restore/bulk:
    post:
      tags:
        - UploadSessions
      summary: Bulk restore UploadSessions by ids (atomic)
      operationId: bulkRestoreUploadSessions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSessionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/upload_sessions/restore/all:
    post:
      tags:
        - UploadSessions
      summary: Restore all soft-deleted UploadSessions
      operationId: restoreAllUploadSessions
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/upload_sessions/trash/bulk:
    delete:
      tags:
        - UploadSessions
      summary: Bulk permanently-delete UploadSessions from trash by ids (atomic)
      operationId: bulkPermanentDeleteUploadSessions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/user_quotas:
    get:
      tags:
        - UserQuotas
      summary: List UserQuotas
      description: Get a paginated list of UserQuotas with optional filtering and sorting
      operationId: listUserQuotas
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserQuotaList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - UserQuotas
      summary: Create UserQuota
      description: Create a new UserQuota
      operationId: createUserQuota
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserQuotaRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserQuota'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/bucket/user_quotas/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - UserQuotas
      summary: Get UserQuota by ID
      operationId: getUserQuota
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserQuota'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - UserQuotas
      summary: Update UserQuota (full)
      operationId: updateUserQuota
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserQuotaRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserQuota'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - UserQuotas
      summary: Update UserQuota (partial)
      operationId: patchUserQuota
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchUserQuotaRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserQuota'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - UserQuotas
      summary: Delete UserQuota (soft)
      operationId: deleteUserQuota
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/user_quotas/bulk:
    post:
      tags:
        - UserQuotas
      summary: Bulk create UserQuotas
      operationId: bulkCreateUserQuotas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateUserQuotaRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserQuota'
    put:
      tags:
        - UserQuotas
      summary: Bulk update UserQuotas (full, atomic)
      operationId: bulkUpdateUserQuotas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateUserQuotaRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserQuotaBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - UserQuotas
      summary: Bulk partial-update UserQuotas (atomic)
      operationId: bulkPatchUserQuotas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserQuotaBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/user_quotas/upsert:
    post:
      tags:
        - UserQuotas
      summary: Upsert UserQuota
      operationId: upsertUserQuota
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserQuotaRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserQuota'

  /api/v1/bucket/user_quotas/trash:
    get:
      tags:
        - UserQuotas
      summary: List deleted UserQuotas
      operationId: listDeletedUserQuotas
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserQuotaList'

  /api/v1/bucket/user_quotas/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - UserQuotas
      summary: Restore deleted UserQuota
      operationId: restoreUserQuota
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserQuota'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/bucket/user_quotas/empty:
    delete:
      tags:
        - UserQuotas
      summary: Empty trash for UserQuotas
      operationId: emptyTrashUserQuotas
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/bucket/user_quotas/delete/bulk:
    post:
      tags:
        - UserQuotas
      summary: Bulk soft-delete UserQuotas by ids (atomic)
      operationId: bulkDeleteUserQuotas
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/user_quotas/restore/bulk:
    post:
      tags:
        - UserQuotas
      summary: Bulk restore UserQuotas by ids (atomic)
      operationId: bulkRestoreUserQuotas
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserQuotaBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/bucket/user_quotas/restore/all:
    post:
      tags:
        - UserQuotas
      summary: Restore all soft-deleted UserQuotas
      operationId: restoreAllUserQuotas
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/bucket/user_quotas/trash/bulk:
    delete:
      tags:
        - UserQuotas
      summary: Bulk permanently-delete UserQuotas from trash by ids (atomic)
      operationId: bulkPermanentDeleteUserQuotas
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    AccessLog:
      type: object
      required:
        - id
        - file_id
        - action
        - is_owner
        - is_shared
        - is_public
        - success
        - accessed_at
        - metadata
      properties:
        id:
          type: string
          format: uuid
        file_id:
          type: string
          format: uuid
        bucket_id:
          nullable: true
          type: string
          format: uuid
        action:
          type: string
        user_id:
          nullable: true
          type: string
          format: uuid
        share_id:
          nullable: true
          type: string
          format: uuid
        is_owner:
          type: boolean
        is_shared:
          type: boolean
        is_public:
          type: boolean
        ip_address:
          nullable: true
          type: string
          maxLength: 45
        user_agent:
          nullable: true
          type: string
          maxLength: 500
        referer:
          nullable: true
          type: string
          maxLength: 500
        country_code:
          nullable: true
          type: string
          maxLength: 2
        city:
          nullable: true
          type: string
          maxLength: 100
        bytes_transferred:
          nullable: true
          type: integer
          format: int64
        duration_ms:
          nullable: true
          type: integer
          format: int32
        success:
          type: boolean
        error_message:
          nullable: true
          type: string
          maxLength: 500
        accessed_at:
          type: string
          format: date-time
        metadata:
          type: object

    AccessLogBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AccessLog'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateAccessLogRequest:
      type: object
      required:
        - file_id
        - action
        - is_owner
        - is_shared
        - is_public
        - success
        - accessed_at
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        bucket_id:
          nullable: true
          type: string
          format: uuid
        action:
          type: string
        user_id:
          nullable: true
          type: string
          format: uuid
        share_id:
          nullable: true
          type: string
          format: uuid
        is_owner:
          type: boolean
        is_shared:
          type: boolean
        is_public:
          type: boolean
        ip_address:
          nullable: true
          type: string
          maxLength: 45
        user_agent:
          nullable: true
          type: string
          maxLength: 500
        referer:
          nullable: true
          type: string
          maxLength: 500
        country_code:
          nullable: true
          type: string
          maxLength: 2
        city:
          nullable: true
          type: string
          maxLength: 100
        bytes_transferred:
          nullable: true
          type: integer
          format: int64
        duration_ms:
          nullable: true
          type: integer
          format: int32
        success:
          type: boolean
        error_message:
          nullable: true
          type: string
          maxLength: 500
        accessed_at:
          type: string
          format: date-time
        metadata:
          type: object

    UpdateAccessLogRequest:
      type: object
      required:
        - file_id
        - action
        - is_owner
        - is_shared
        - is_public
        - success
        - accessed_at
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        bucket_id:
          nullable: true
          type: string
          format: uuid
        action:
          type: string
        user_id:
          nullable: true
          type: string
          format: uuid
        share_id:
          nullable: true
          type: string
          format: uuid
        is_owner:
          type: boolean
        is_shared:
          type: boolean
        is_public:
          type: boolean
        ip_address:
          nullable: true
          type: string
          maxLength: 45
        user_agent:
          nullable: true
          type: string
          maxLength: 500
        referer:
          nullable: true
          type: string
          maxLength: 500
        country_code:
          nullable: true
          type: string
          maxLength: 2
        city:
          nullable: true
          type: string
          maxLength: 100
        bytes_transferred:
          nullable: true
          type: integer
          format: int64
        duration_ms:
          nullable: true
          type: integer
          format: int32
        success:
          type: boolean
        error_message:
          nullable: true
          type: string
          maxLength: 500
        accessed_at:
          type: string
          format: date-time
        metadata:
          type: object

    PatchAccessLogRequest:
      type: object
      properties:
        file_id:
          type: string
          format: uuid
        bucket_id:
          nullable: true
          type: string
          format: uuid
        action:
          type: string
        user_id:
          nullable: true
          type: string
          format: uuid
        share_id:
          nullable: true
          type: string
          format: uuid
        is_owner:
          type: boolean
        is_shared:
          type: boolean
        is_public:
          type: boolean
        ip_address:
          nullable: true
          type: string
          maxLength: 45
        user_agent:
          nullable: true
          type: string
          maxLength: 500
        referer:
          nullable: true
          type: string
          maxLength: 500
        country_code:
          nullable: true
          type: string
          maxLength: 2
        city:
          nullable: true
          type: string
          maxLength: 100
        bytes_transferred:
          nullable: true
          type: integer
          format: int64
        duration_ms:
          nullable: true
          type: integer
          format: int32
        success:
          type: boolean
        error_message:
          nullable: true
          type: string
          maxLength: 500
        accessed_at:
          type: string
          format: date-time
        metadata:
          type: object

    AccessLogList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AccessLog'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    Bucket:
      type: object
      required:
        - id
        - name
        - slug
        - owner_id
        - bucket_type
        - status
        - storage_backend
        - root_path
        - file_count
        - total_size_bytes
        - allowed_mime_types
        - enable_cdn
        - enable_versioning
        - enable_deduplication
        - metadata
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 255
        slug:
          type: string
          maxLength: 255
        description:
          nullable: true
          type: string
        owner_id:
          type: string
          format: uuid
        bucket_type:
          type: string
        status:
          type: string
        storage_backend:
          type: string
        root_path:
          type: string
          maxLength: 1024
        file_count:
          type: integer
          format: int32
        total_size_bytes:
          type: integer
          format: int64
        max_file_size:
          nullable: true
          type: integer
          format: int64
        allowed_mime_types:
          type: array
        auto_delete_after_days:
          nullable: true
          type: integer
          format: int32
        enable_cdn:
          type: boolean
        enable_versioning:
          type: boolean
        enable_deduplication:
          type: boolean
        metadata:
          type: object

    BucketBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Bucket'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateBucketRequest:
      type: object
      required:
        - name
        - slug
        - owner_id
        - bucket_type
        - status
        - storage_backend
        - root_path
        - file_count
        - total_size_bytes
        - allowed_mime_types
        - enable_cdn
        - enable_versioning
        - enable_deduplication
        - metadata
      properties:
        name:
          type: string
          maxLength: 255
        slug:
          type: string
          maxLength: 255
        description:
          nullable: true
          type: string
        owner_id:
          type: string
          format: uuid
        bucket_type:
          type: string
        status:
          type: string
        storage_backend:
          type: string
        root_path:
          type: string
          maxLength: 1024
        file_count:
          type: integer
          format: int32
        total_size_bytes:
          type: integer
          format: int64
        max_file_size:
          nullable: true
          type: integer
          format: int64
        allowed_mime_types:
          type: array
        auto_delete_after_days:
          nullable: true
          type: integer
          format: int32
        enable_cdn:
          type: boolean
        enable_versioning:
          type: boolean
        enable_deduplication:
          type: boolean
        metadata:
          type: object

    UpdateBucketRequest:
      type: object
      required:
        - name
        - slug
        - owner_id
        - bucket_type
        - status
        - storage_backend
        - root_path
        - file_count
        - total_size_bytes
        - allowed_mime_types
        - enable_cdn
        - enable_versioning
        - enable_deduplication
        - metadata
      properties:
        name:
          type: string
          maxLength: 255
        slug:
          type: string
          maxLength: 255
        description:
          nullable: true
          type: string
        owner_id:
          type: string
          format: uuid
        bucket_type:
          type: string
        status:
          type: string
        storage_backend:
          type: string
        root_path:
          type: string
          maxLength: 1024
        file_count:
          type: integer
          format: int32
        total_size_bytes:
          type: integer
          format: int64
        max_file_size:
          nullable: true
          type: integer
          format: int64
        allowed_mime_types:
          type: array
        auto_delete_after_days:
          nullable: true
          type: integer
          format: int32
        enable_cdn:
          type: boolean
        enable_versioning:
          type: boolean
        enable_deduplication:
          type: boolean
        metadata:
          type: object

    PatchBucketRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
        slug:
          type: string
          maxLength: 255
        description:
          nullable: true
          type: string
        owner_id:
          type: string
          format: uuid
        bucket_type:
          type: string
        status:
          type: string
        storage_backend:
          type: string
        root_path:
          type: string
          maxLength: 1024
        file_count:
          type: integer
          format: int32
        total_size_bytes:
          type: integer
          format: int64
        max_file_size:
          nullable: true
          type: integer
          format: int64
        allowed_mime_types:
          type: array
        auto_delete_after_days:
          nullable: true
          type: integer
          format: int32
        enable_cdn:
          type: boolean
        enable_versioning:
          type: boolean
        enable_deduplication:
          type: boolean
        metadata:
          type: object

    BucketList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Bucket'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    ContentHash:
      type: object
      required:
        - id
        - hash
        - size_bytes
        - storage_key
        - storage_backend
        - reference_count
        - first_uploaded_at
        - last_referenced_at
        - metadata
      properties:
        id:
          type: string
          format: uuid
        hash:
          type: string
        size_bytes:
          type: integer
          format: int64
        storage_key:
          type: string
          maxLength: 1024
        storage_backend:
          type: string
        reference_count:
          type: integer
          format: int32
          minimum: 1
        first_uploaded_at:
          type: string
          format: date-time
        last_referenced_at:
          type: string
          format: date-time
        fingerprint:
          nullable: true
          type: string
          maxLength: 128
        metadata:
          type: object

    ContentHashBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ContentHash'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateContentHashRequest:
      type: object
      required:
        - hash
        - size_bytes
        - storage_key
        - storage_backend
        - reference_count
        - first_uploaded_at
        - last_referenced_at
        - metadata
      properties:
        hash:
          type: string
        size_bytes:
          type: integer
          format: int64
        storage_key:
          type: string
          maxLength: 1024
        storage_backend:
          type: string
        reference_count:
          type: integer
          format: int32
          minimum: 1
        first_uploaded_at:
          type: string
          format: date-time
        last_referenced_at:
          type: string
          format: date-time
        fingerprint:
          nullable: true
          type: string
          maxLength: 128
        metadata:
          type: object

    UpdateContentHashRequest:
      type: object
      required:
        - hash
        - size_bytes
        - storage_key
        - storage_backend
        - reference_count
        - first_uploaded_at
        - last_referenced_at
        - metadata
      properties:
        hash:
          type: string
        size_bytes:
          type: integer
          format: int64
        storage_key:
          type: string
          maxLength: 1024
        storage_backend:
          type: string
        reference_count:
          type: integer
          format: int32
          minimum: 1
        first_uploaded_at:
          type: string
          format: date-time
        last_referenced_at:
          type: string
          format: date-time
        fingerprint:
          nullable: true
          type: string
          maxLength: 128
        metadata:
          type: object

    PatchContentHashRequest:
      type: object
      properties:
        hash:
          type: string
        size_bytes:
          type: integer
          format: int64
        storage_key:
          type: string
          maxLength: 1024
        storage_backend:
          type: string
        reference_count:
          type: integer
          format: int32
          minimum: 1
        first_uploaded_at:
          type: string
          format: date-time
        last_referenced_at:
          type: string
          format: date-time
        fingerprint:
          nullable: true
          type: string
          maxLength: 128
        metadata:
          type: object

    ContentHashList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ContentHash'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    ConversionJob:
      type: object
      required:
        - id
        - source_file_id
        - target_format
        - status
        - progress
        - metadata
      properties:
        id:
          type: string
          format: uuid
        source_file_id:
          type: string
          format: uuid
        target_format:
          type: string
          maxLength: 50
        status:
          type: string
        conversion_options:
          nullable: true
          type: object
        result_file_id:
          nullable: true
          type: string
          format: uuid
        progress:
          type: integer
          format: int32
        error_message:
          nullable: true
          type: string
        started_at:
          nullable: true
          type: string
          format: date-time
        completed_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    ConversionJobBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ConversionJob'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateConversionJobRequest:
      type: object
      required:
        - source_file_id
        - target_format
        - status
        - progress
        - metadata
      properties:
        source_file_id:
          type: string
          format: uuid
        target_format:
          type: string
          maxLength: 50
        status:
          type: string
        conversion_options:
          nullable: true
          type: object
        result_file_id:
          nullable: true
          type: string
          format: uuid
        progress:
          type: integer
          format: int32
        error_message:
          nullable: true
          type: string
        started_at:
          nullable: true
          type: string
          format: date-time
        completed_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    UpdateConversionJobRequest:
      type: object
      required:
        - source_file_id
        - target_format
        - status
        - progress
        - metadata
      properties:
        source_file_id:
          type: string
          format: uuid
        target_format:
          type: string
          maxLength: 50
        status:
          type: string
        conversion_options:
          nullable: true
          type: object
        result_file_id:
          nullable: true
          type: string
          format: uuid
        progress:
          type: integer
          format: int32
        error_message:
          nullable: true
          type: string
        started_at:
          nullable: true
          type: string
          format: date-time
        completed_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    PatchConversionJobRequest:
      type: object
      properties:
        source_file_id:
          type: string
          format: uuid
        target_format:
          type: string
          maxLength: 50
        status:
          type: string
        conversion_options:
          nullable: true
          type: object
        result_file_id:
          nullable: true
          type: string
          format: uuid
        progress:
          type: integer
          format: int32
        error_message:
          nullable: true
          type: string
        started_at:
          nullable: true
          type: string
          format: date-time
        completed_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    ConversionJobList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ConversionJob'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    FileComment:
      type: object
      required:
        - id
        - file_id
        - user_id
        - content
        - mentions
        - resolved
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        file_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        parent_id:
          nullable: true
          type: string
          format: uuid
        content:
          type: string
          maxLength: 10000
        annotation_region:
          nullable: true
          type: object
        mentions:
          type: array
        resolved:
          type: boolean
        resolved_by:
          nullable: true
          type: string
          format: uuid
        resolved_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        metadata:
          type: object

    FileCommentBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FileComment'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateFileCommentRequest:
      type: object
      required:
        - file_id
        - user_id
        - content
        - mentions
        - resolved
        - status
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        parent_id:
          nullable: true
          type: string
          format: uuid
        content:
          type: string
          maxLength: 10000
        annotation_region:
          nullable: true
          type: object
        mentions:
          type: array
        resolved:
          type: boolean
        resolved_by:
          nullable: true
          type: string
          format: uuid
        resolved_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        metadata:
          type: object

    UpdateFileCommentRequest:
      type: object
      required:
        - file_id
        - user_id
        - content
        - mentions
        - resolved
        - status
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        parent_id:
          nullable: true
          type: string
          format: uuid
        content:
          type: string
          maxLength: 10000
        annotation_region:
          nullable: true
          type: object
        mentions:
          type: array
        resolved:
          type: boolean
        resolved_by:
          nullable: true
          type: string
          format: uuid
        resolved_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        metadata:
          type: object

    PatchFileCommentRequest:
      type: object
      properties:
        file_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        parent_id:
          nullable: true
          type: string
          format: uuid
        content:
          type: string
          maxLength: 10000
        annotation_region:
          nullable: true
          type: object
        mentions:
          type: array
        resolved:
          type: boolean
        resolved_by:
          nullable: true
          type: string
          format: uuid
        resolved_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        metadata:
          type: object

    FileCommentList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FileComment'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    FileLock:
      type: object
      required:
        - id
        - file_id
        - user_id
        - locked_at
        - expires_at
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        file_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        locked_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        refreshed_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        metadata:
          type: object

    FileLockBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FileLock'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateFileLockRequest:
      type: object
      required:
        - file_id
        - user_id
        - locked_at
        - expires_at
        - status
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        locked_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        refreshed_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        metadata:
          type: object

    UpdateFileLockRequest:
      type: object
      required:
        - file_id
        - user_id
        - locked_at
        - expires_at
        - status
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        locked_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        refreshed_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        metadata:
          type: object

    PatchFileLockRequest:
      type: object
      properties:
        file_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        locked_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        refreshed_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        metadata:
          type: object

    FileLockList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FileLock'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    FileShare:
      type: object
      required:
        - id
        - file_id
        - owner_id
        - token
        - share_type
        - permission
        - shared_with
        - download_count
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        file_id:
          type: string
          format: uuid
        owner_id:
          type: string
          format: uuid
        token:
          type: string
          minLength: 32
          maxLength: 64
        share_type:
          type: string
        permission:
          type: string
        shared_with:
          type: array
        password_hash:
          nullable: true
          type: string
        max_downloads:
          nullable: true
          type: integer
          format: int32
        download_count:
          type: integer
          format: int32
        expires_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        revoked_at:
          nullable: true
          type: string
          format: date-time
        revoked_by:
          nullable: true
          type: string
          format: uuid
        message:
          nullable: true
          type: string
        metadata:
          type: object

    FileShareBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FileShare'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateFileShareRequest:
      type: object
      required:
        - file_id
        - owner_id
        - token
        - share_type
        - permission
        - shared_with
        - download_count
        - status
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        owner_id:
          type: string
          format: uuid
        token:
          type: string
          minLength: 32
          maxLength: 64
        share_type:
          type: string
        permission:
          type: string
        shared_with:
          type: array
        password_hash:
          nullable: true
          type: string
        max_downloads:
          nullable: true
          type: integer
          format: int32
        download_count:
          type: integer
          format: int32
        expires_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        revoked_at:
          nullable: true
          type: string
          format: date-time
        revoked_by:
          nullable: true
          type: string
          format: uuid
        message:
          nullable: true
          type: string
        metadata:
          type: object

    UpdateFileShareRequest:
      type: object
      required:
        - file_id
        - owner_id
        - token
        - share_type
        - permission
        - shared_with
        - download_count
        - status
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        owner_id:
          type: string
          format: uuid
        token:
          type: string
          minLength: 32
          maxLength: 64
        share_type:
          type: string
        permission:
          type: string
        shared_with:
          type: array
        password_hash:
          nullable: true
          type: string
        max_downloads:
          nullable: true
          type: integer
          format: int32
        download_count:
          type: integer
          format: int32
        expires_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        revoked_at:
          nullable: true
          type: string
          format: date-time
        revoked_by:
          nullable: true
          type: string
          format: uuid
        message:
          nullable: true
          type: string
        metadata:
          type: object

    PatchFileShareRequest:
      type: object
      properties:
        file_id:
          type: string
          format: uuid
        owner_id:
          type: string
          format: uuid
        token:
          type: string
          minLength: 32
          maxLength: 64
        share_type:
          type: string
        permission:
          type: string
        shared_with:
          type: array
        password_hash:
          nullable: true
          type: string
        max_downloads:
          nullable: true
          type: integer
          format: int32
        download_count:
          type: integer
          format: int32
        expires_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        revoked_at:
          nullable: true
          type: string
          format: date-time
        revoked_by:
          nullable: true
          type: string
          format: uuid
        message:
          nullable: true
          type: string
        metadata:
          type: object

    FileShareList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FileShare'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    FileVersion:
      type: object
      required:
        - id
        - file_id
        - version_number
        - version_type
        - storage_key
        - storage_backend
        - name
        - mime_type
        - created_by_id
        - is_current
        - status
        - size_bytes
        - metadata
      properties:
        id:
          type: string
          format: uuid
        file_id:
          type: string
          format: uuid
        version_number:
          type: integer
          format: int32
        version_type:
          type: string
        storage_key:
          type: string
        storage_backend:
          type: string
        name:
          type: string
          maxLength: 255
        mime_type:
          type: string
        checksum_md5:
          nullable: true
          type: string
          maxLength: 32
        checksum_sha256:
          nullable: true
          type: string
          maxLength: 64
        created_by_id:
          type: string
          format: uuid
        change_summary:
          nullable: true
          type: string
          maxLength: 500
        is_current:
          type: boolean
        restored_from_id:
          nullable: true
          type: string
          format: uuid
        expires_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        deleted_at:
          nullable: true
          type: string
          format: date-time
        size_bytes:
          type: integer
          format: int64
        metadata:
          type: object

    FileVersionBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FileVersion'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateFileVersionRequest:
      type: object
      required:
        - file_id
        - version_number
        - version_type
        - storage_key
        - storage_backend
        - name
        - mime_type
        - created_by_id
        - is_current
        - status
        - size_bytes
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        version_number:
          type: integer
          format: int32
        version_type:
          type: string
        storage_key:
          type: string
        storage_backend:
          type: string
        name:
          type: string
          maxLength: 255
        mime_type:
          type: string
        checksum_md5:
          nullable: true
          type: string
          maxLength: 32
        checksum_sha256:
          nullable: true
          type: string
          maxLength: 64
        created_by_id:
          type: string
          format: uuid
        change_summary:
          nullable: true
          type: string
          maxLength: 500
        is_current:
          type: boolean
        restored_from_id:
          nullable: true
          type: string
          format: uuid
        expires_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        size_bytes:
          type: integer
          format: int64
        metadata:
          type: object

    UpdateFileVersionRequest:
      type: object
      required:
        - file_id
        - version_number
        - version_type
        - storage_key
        - storage_backend
        - name
        - mime_type
        - created_by_id
        - is_current
        - status
        - size_bytes
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        version_number:
          type: integer
          format: int32
        version_type:
          type: string
        storage_key:
          type: string
        storage_backend:
          type: string
        name:
          type: string
          maxLength: 255
        mime_type:
          type: string
        checksum_md5:
          nullable: true
          type: string
          maxLength: 32
        checksum_sha256:
          nullable: true
          type: string
          maxLength: 64
        created_by_id:
          type: string
          format: uuid
        change_summary:
          nullable: true
          type: string
          maxLength: 500
        is_current:
          type: boolean
        restored_from_id:
          nullable: true
          type: string
          format: uuid
        expires_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        size_bytes:
          type: integer
          format: int64
        metadata:
          type: object

    PatchFileVersionRequest:
      type: object
      properties:
        file_id:
          type: string
          format: uuid
        version_number:
          type: integer
          format: int32
        version_type:
          type: string
        storage_key:
          type: string
        storage_backend:
          type: string
        name:
          type: string
          maxLength: 255
        mime_type:
          type: string
        checksum_md5:
          nullable: true
          type: string
          maxLength: 32
        checksum_sha256:
          nullable: true
          type: string
          maxLength: 64
        created_by_id:
          type: string
          format: uuid
        change_summary:
          nullable: true
          type: string
          maxLength: 500
        is_current:
          type: boolean
        restored_from_id:
          nullable: true
          type: string
          format: uuid
        expires_at:
          nullable: true
          type: string
          format: date-time
        status:
          type: string
        size_bytes:
          type: integer
          format: int64
        metadata:
          type: object

    FileVersionList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FileVersion'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    ProcessingJob:
      type: object
      required:
        - id
        - file_id
        - job_type
        - status
        - priority
        - retry_count
        - max_retries
        - metadata
      properties:
        id:
          type: string
          format: uuid
        file_id:
          type: string
          format: uuid
        job_type:
          type: string
        status:
          type: string
        priority:
          type: integer
          format: int32
        input_data:
          nullable: true
          type: object
        result_data:
          nullable: true
          type: object
        error_message:
          nullable: true
          type: string
        started_at:
          nullable: true
          type: string
          format: date-time
        completed_at:
          nullable: true
          type: string
          format: date-time
        retry_count:
          type: integer
          format: int32
        max_retries:
          type: integer
          format: int32
        metadata:
          type: object

    ProcessingJobBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProcessingJob'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateProcessingJobRequest:
      type: object
      required:
        - file_id
        - job_type
        - status
        - priority
        - retry_count
        - max_retries
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        job_type:
          type: string
        status:
          type: string
        priority:
          type: integer
          format: int32
        input_data:
          nullable: true
          type: object
        result_data:
          nullable: true
          type: object
        error_message:
          nullable: true
          type: string
        started_at:
          nullable: true
          type: string
          format: date-time
        completed_at:
          nullable: true
          type: string
          format: date-time
        retry_count:
          type: integer
          format: int32
        max_retries:
          type: integer
          format: int32
        metadata:
          type: object

    UpdateProcessingJobRequest:
      type: object
      required:
        - file_id
        - job_type
        - status
        - priority
        - retry_count
        - max_retries
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        job_type:
          type: string
        status:
          type: string
        priority:
          type: integer
          format: int32
        input_data:
          nullable: true
          type: object
        result_data:
          nullable: true
          type: object
        error_message:
          nullable: true
          type: string
        started_at:
          nullable: true
          type: string
          format: date-time
        completed_at:
          nullable: true
          type: string
          format: date-time
        retry_count:
          type: integer
          format: int32
        max_retries:
          type: integer
          format: int32
        metadata:
          type: object

    PatchProcessingJobRequest:
      type: object
      properties:
        file_id:
          type: string
          format: uuid
        job_type:
          type: string
        status:
          type: string
        priority:
          type: integer
          format: int32
        input_data:
          nullable: true
          type: object
        result_data:
          nullable: true
          type: object
        error_message:
          nullable: true
          type: string
        started_at:
          nullable: true
          type: string
          format: date-time
        completed_at:
          nullable: true
          type: string
          format: date-time
        retry_count:
          type: integer
          format: int32
        max_retries:
          type: integer
          format: int32
        metadata:
          type: object

    ProcessingJobList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProcessingJob'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    StoredFile:
      type: object
      required:
        - id
        - bucket_id
        - owner_id
        - path
        - original_name
        - size_bytes
        - mime_type
        - is_compressed
        - is_scanned
        - has_thumbnail
        - has_video_thumbnail
        - has_document_preview
        - sort_order
        - status
        - storage_key
        - version
        - download_count
        - metadata
      properties:
        id:
          type: string
          format: uuid
        bucket_id:
          type: string
          format: uuid
        owner_id:
          type: string
          format: uuid
        path:
          type: string
          maxLength: 1024
        original_name:
          type: string
          maxLength: 255
        size_bytes:
          type: integer
          format: int64
        mime_type:
          type: string
          maxLength: 127
        checksum:
          nullable: true
          type: string
          maxLength: 128
        is_compressed:
          type: boolean
        original_size:
          nullable: true
          type: integer
          format: int64
        compression_algorithm:
          nullable: true
          type: string
        is_scanned:
          type: boolean
        scan_result:
          nullable: true
          type: object
        threat_level:
          nullable: true
          type: string
        has_thumbnail:
          type: boolean
        thumbnail_path:
          nullable: true
          type: string
        has_video_thumbnail:
          type: boolean
        has_document_preview:
          type: boolean
        processing_status:
          nullable: true
          type: string
        content_hash_id:
          nullable: true
          type: string
          format: uuid
        cdn_url:
          nullable: true
          type: string
        cdn_url_expires_at:
          nullable: true
          type: string
          format: date-time
        owner_module:
          nullable: true
          type: string
          maxLength: 100
        owner_entity:
          nullable: true
          type: string
          maxLength: 100
        owner_entity_id:
          nullable: true
          type: string
          format: uuid
        field_name:
          nullable: true
          type: string
          maxLength: 100
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        storage_key:
          type: string
          maxLength: 1024
        version:
          type: integer
          format: int32
        previous_version_id:
          nullable: true
          type: string
          format: uuid
        download_count:
          type: integer
          format: int32
        last_accessed_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    StoredFileBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/StoredFile'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateStoredFileRequest:
      type: object
      required:
        - bucket_id
        - owner_id
        - path
        - original_name
        - size_bytes
        - mime_type
        - is_compressed
        - is_scanned
        - has_thumbnail
        - has_video_thumbnail
        - has_document_preview
        - sort_order
        - status
        - storage_key
        - version
        - download_count
        - metadata
      properties:
        bucket_id:
          type: string
          format: uuid
        owner_id:
          type: string
          format: uuid
        path:
          type: string
          maxLength: 1024
        original_name:
          type: string
          maxLength: 255
        size_bytes:
          type: integer
          format: int64
        mime_type:
          type: string
          maxLength: 127
        checksum:
          nullable: true
          type: string
          maxLength: 128
        is_compressed:
          type: boolean
        original_size:
          nullable: true
          type: integer
          format: int64
        compression_algorithm:
          nullable: true
          type: string
        is_scanned:
          type: boolean
        scan_result:
          nullable: true
          type: object
        threat_level:
          nullable: true
          type: string
        has_thumbnail:
          type: boolean
        thumbnail_path:
          nullable: true
          type: string
        has_video_thumbnail:
          type: boolean
        has_document_preview:
          type: boolean
        processing_status:
          nullable: true
          type: string
        content_hash_id:
          nullable: true
          type: string
          format: uuid
        cdn_url:
          nullable: true
          type: string
        cdn_url_expires_at:
          nullable: true
          type: string
          format: date-time
        owner_module:
          nullable: true
          type: string
          maxLength: 100
        owner_entity:
          nullable: true
          type: string
          maxLength: 100
        owner_entity_id:
          nullable: true
          type: string
          format: uuid
        field_name:
          nullable: true
          type: string
          maxLength: 100
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        storage_key:
          type: string
          maxLength: 1024
        version:
          type: integer
          format: int32
        previous_version_id:
          nullable: true
          type: string
          format: uuid
        download_count:
          type: integer
          format: int32
        last_accessed_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    UpdateStoredFileRequest:
      type: object
      required:
        - bucket_id
        - owner_id
        - path
        - original_name
        - size_bytes
        - mime_type
        - is_compressed
        - is_scanned
        - has_thumbnail
        - has_video_thumbnail
        - has_document_preview
        - sort_order
        - status
        - storage_key
        - version
        - download_count
        - metadata
      properties:
        bucket_id:
          type: string
          format: uuid
        owner_id:
          type: string
          format: uuid
        path:
          type: string
          maxLength: 1024
        original_name:
          type: string
          maxLength: 255
        size_bytes:
          type: integer
          format: int64
        mime_type:
          type: string
          maxLength: 127
        checksum:
          nullable: true
          type: string
          maxLength: 128
        is_compressed:
          type: boolean
        original_size:
          nullable: true
          type: integer
          format: int64
        compression_algorithm:
          nullable: true
          type: string
        is_scanned:
          type: boolean
        scan_result:
          nullable: true
          type: object
        threat_level:
          nullable: true
          type: string
        has_thumbnail:
          type: boolean
        thumbnail_path:
          nullable: true
          type: string
        has_video_thumbnail:
          type: boolean
        has_document_preview:
          type: boolean
        processing_status:
          nullable: true
          type: string
        content_hash_id:
          nullable: true
          type: string
          format: uuid
        cdn_url:
          nullable: true
          type: string
        cdn_url_expires_at:
          nullable: true
          type: string
          format: date-time
        owner_module:
          nullable: true
          type: string
          maxLength: 100
        owner_entity:
          nullable: true
          type: string
          maxLength: 100
        owner_entity_id:
          nullable: true
          type: string
          format: uuid
        field_name:
          nullable: true
          type: string
          maxLength: 100
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        storage_key:
          type: string
          maxLength: 1024
        version:
          type: integer
          format: int32
        previous_version_id:
          nullable: true
          type: string
          format: uuid
        download_count:
          type: integer
          format: int32
        last_accessed_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    PatchStoredFileRequest:
      type: object
      properties:
        bucket_id:
          type: string
          format: uuid
        owner_id:
          type: string
          format: uuid
        path:
          type: string
          maxLength: 1024
        original_name:
          type: string
          maxLength: 255
        size_bytes:
          type: integer
          format: int64
        mime_type:
          type: string
          maxLength: 127
        checksum:
          nullable: true
          type: string
          maxLength: 128
        is_compressed:
          type: boolean
        original_size:
          nullable: true
          type: integer
          format: int64
        compression_algorithm:
          nullable: true
          type: string
        is_scanned:
          type: boolean
        scan_result:
          nullable: true
          type: object
        threat_level:
          nullable: true
          type: string
        has_thumbnail:
          type: boolean
        thumbnail_path:
          nullable: true
          type: string
        has_video_thumbnail:
          type: boolean
        has_document_preview:
          type: boolean
        processing_status:
          nullable: true
          type: string
        content_hash_id:
          nullable: true
          type: string
          format: uuid
        cdn_url:
          nullable: true
          type: string
        cdn_url_expires_at:
          nullable: true
          type: string
          format: date-time
        owner_module:
          nullable: true
          type: string
          maxLength: 100
        owner_entity:
          nullable: true
          type: string
          maxLength: 100
        owner_entity_id:
          nullable: true
          type: string
          format: uuid
        field_name:
          nullable: true
          type: string
          maxLength: 100
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        storage_key:
          type: string
          maxLength: 1024
        version:
          type: integer
          format: int32
        previous_version_id:
          nullable: true
          type: string
          format: uuid
        download_count:
          type: integer
          format: int32
        last_accessed_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    StoredFileList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/StoredFile'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    Thumbnail:
      type: object
      required:
        - id
        - file_id
        - size
        - width
        - height
        - storage_key
        - storage_backend
        - mime_type
        - format
        - quality
        - size_bytes
        - generated_at
        - source_version
        - is_stale
        - metadata
      properties:
        id:
          type: string
          format: uuid
        file_id:
          type: string
          format: uuid
        size:
          type: string
        width:
          type: integer
          format: int32
        height:
          type: integer
          format: int32
        storage_key:
          type: string
        storage_backend:
          type: string
        mime_type:
          type: string
        format:
          type: string
        quality:
          type: integer
          format: int32
        size_bytes:
          type: integer
          format: int64
        generated_at:
          type: string
          format: date-time
        generation_time_ms:
          nullable: true
          type: integer
          format: int32
        source_version:
          type: integer
          format: int32
        cdn_url:
          nullable: true
          type: string
        cache_expires_at:
          nullable: true
          type: string
          format: date-time
        is_stale:
          type: boolean
        metadata:
          type: object

    ThumbnailBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Thumbnail'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateThumbnailRequest:
      type: object
      required:
        - file_id
        - size
        - width
        - height
        - storage_key
        - storage_backend
        - mime_type
        - format
        - quality
        - size_bytes
        - generated_at
        - source_version
        - is_stale
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        size:
          type: string
        width:
          type: integer
          format: int32
        height:
          type: integer
          format: int32
        storage_key:
          type: string
        storage_backend:
          type: string
        mime_type:
          type: string
        format:
          type: string
        quality:
          type: integer
          format: int32
        size_bytes:
          type: integer
          format: int64
        generated_at:
          type: string
          format: date-time
        generation_time_ms:
          nullable: true
          type: integer
          format: int32
        source_version:
          type: integer
          format: int32
        cdn_url:
          nullable: true
          type: string
        cache_expires_at:
          nullable: true
          type: string
          format: date-time
        is_stale:
          type: boolean
        metadata:
          type: object

    UpdateThumbnailRequest:
      type: object
      required:
        - file_id
        - size
        - width
        - height
        - storage_key
        - storage_backend
        - mime_type
        - format
        - quality
        - size_bytes
        - generated_at
        - source_version
        - is_stale
        - metadata
      properties:
        file_id:
          type: string
          format: uuid
        size:
          type: string
        width:
          type: integer
          format: int32
        height:
          type: integer
          format: int32
        storage_key:
          type: string
        storage_backend:
          type: string
        mime_type:
          type: string
        format:
          type: string
        quality:
          type: integer
          format: int32
        size_bytes:
          type: integer
          format: int64
        generated_at:
          type: string
          format: date-time
        generation_time_ms:
          nullable: true
          type: integer
          format: int32
        source_version:
          type: integer
          format: int32
        cdn_url:
          nullable: true
          type: string
        cache_expires_at:
          nullable: true
          type: string
          format: date-time
        is_stale:
          type: boolean
        metadata:
          type: object

    PatchThumbnailRequest:
      type: object
      properties:
        file_id:
          type: string
          format: uuid
        size:
          type: string
        width:
          type: integer
          format: int32
        height:
          type: integer
          format: int32
        storage_key:
          type: string
        storage_backend:
          type: string
        mime_type:
          type: string
        format:
          type: string
        quality:
          type: integer
          format: int32
        size_bytes:
          type: integer
          format: int64
        generated_at:
          type: string
          format: date-time
        generation_time_ms:
          nullable: true
          type: integer
          format: int32
        source_version:
          type: integer
          format: int32
        cdn_url:
          nullable: true
          type: string
        cache_expires_at:
          nullable: true
          type: string
          format: date-time
        is_stale:
          type: boolean
        metadata:
          type: object

    ThumbnailList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Thumbnail'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    UploadSession:
      type: object
      required:
        - id
        - bucket_id
        - user_id
        - path
        - filename
        - file_size
        - chunk_size
        - total_chunks
        - uploaded_chunks
        - status
        - storage_backend
        - completed_parts
        - expires_at
        - metadata
      properties:
        id:
          type: string
          format: uuid
        bucket_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        path:
          type: string
          maxLength: 1024
        filename:
          type: string
          maxLength: 255
        mime_type:
          nullable: true
          type: string
          maxLength: 127
        file_size:
          type: integer
          format: int64
        chunk_size:
          type: integer
          format: int32
        total_chunks:
          type: integer
          format: int32
        uploaded_chunks:
          type: integer
          format: int32
        status:
          type: string
        storage_backend:
          type: string
        completed_parts:
          type: array
        part_etags:
          nullable: true
          type: object
        expires_at:
          type: string
          format: date-time
        metadata:
          type: object

    UploadSessionBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/UploadSession'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateUploadSessionRequest:
      type: object
      required:
        - bucket_id
        - user_id
        - path
        - filename
        - file_size
        - chunk_size
        - total_chunks
        - uploaded_chunks
        - status
        - storage_backend
        - completed_parts
        - expires_at
        - metadata
      properties:
        bucket_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        path:
          type: string
          maxLength: 1024
        filename:
          type: string
          maxLength: 255
        mime_type:
          nullable: true
          type: string
          maxLength: 127
        file_size:
          type: integer
          format: int64
        chunk_size:
          type: integer
          format: int32
        total_chunks:
          type: integer
          format: int32
        uploaded_chunks:
          type: integer
          format: int32
        status:
          type: string
        storage_backend:
          type: string
        completed_parts:
          type: array
        part_etags:
          nullable: true
          type: object
        expires_at:
          type: string
          format: date-time
        metadata:
          type: object

    UpdateUploadSessionRequest:
      type: object
      required:
        - bucket_id
        - user_id
        - path
        - filename
        - file_size
        - chunk_size
        - total_chunks
        - uploaded_chunks
        - status
        - storage_backend
        - completed_parts
        - expires_at
        - metadata
      properties:
        bucket_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        path:
          type: string
          maxLength: 1024
        filename:
          type: string
          maxLength: 255
        mime_type:
          nullable: true
          type: string
          maxLength: 127
        file_size:
          type: integer
          format: int64
        chunk_size:
          type: integer
          format: int32
        total_chunks:
          type: integer
          format: int32
        uploaded_chunks:
          type: integer
          format: int32
        status:
          type: string
        storage_backend:
          type: string
        completed_parts:
          type: array
        part_etags:
          nullable: true
          type: object
        expires_at:
          type: string
          format: date-time
        metadata:
          type: object

    PatchUploadSessionRequest:
      type: object
      properties:
        bucket_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        path:
          type: string
          maxLength: 1024
        filename:
          type: string
          maxLength: 255
        mime_type:
          nullable: true
          type: string
          maxLength: 127
        file_size:
          type: integer
          format: int64
        chunk_size:
          type: integer
          format: int32
        total_chunks:
          type: integer
          format: int32
        uploaded_chunks:
          type: integer
          format: int32
        status:
          type: string
        storage_backend:
          type: string
        completed_parts:
          type: array
        part_etags:
          nullable: true
          type: object
        expires_at:
          type: string
          format: date-time
        metadata:
          type: object

    UploadSessionList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/UploadSession'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    UserQuota:
      type: object
      required:
        - id
        - user_id
        - limit_bytes
        - used_bytes
        - file_count
        - tier
        - quota_status
        - warning_threshold_percent
        - peak_usage_bytes
        - metadata
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        limit_bytes:
          type: integer
          format: int64
        used_bytes:
          type: integer
          format: int64
        file_count:
          type: integer
          format: int32
        max_file_size:
          nullable: true
          type: integer
          format: int64
        max_file_count:
          nullable: true
          type: integer
          format: int32
        tier:
          type: string
          maxLength: 50
        quota_status:
          type: string
        warning_threshold_percent:
          type: integer
          format: int32
        last_warning_sent_at:
          nullable: true
          type: string
          format: date-time
        peak_usage_bytes:
          type: integer
          format: int64
        peak_usage_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    UserQuotaBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/UserQuota'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateUserQuotaRequest:
      type: object
      required:
        - user_id
        - limit_bytes
        - used_bytes
        - file_count
        - tier
        - quota_status
        - warning_threshold_percent
        - peak_usage_bytes
        - metadata
      properties:
        user_id:
          type: string
          format: uuid
        limit_bytes:
          type: integer
          format: int64
        used_bytes:
          type: integer
          format: int64
        file_count:
          type: integer
          format: int32
        max_file_size:
          nullable: true
          type: integer
          format: int64
        max_file_count:
          nullable: true
          type: integer
          format: int32
        tier:
          type: string
          maxLength: 50
        quota_status:
          type: string
        warning_threshold_percent:
          type: integer
          format: int32
        last_warning_sent_at:
          nullable: true
          type: string
          format: date-time
        peak_usage_bytes:
          type: integer
          format: int64
        peak_usage_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    UpdateUserQuotaRequest:
      type: object
      required:
        - user_id
        - limit_bytes
        - used_bytes
        - file_count
        - tier
        - quota_status
        - warning_threshold_percent
        - peak_usage_bytes
        - metadata
      properties:
        user_id:
          type: string
          format: uuid
        limit_bytes:
          type: integer
          format: int64
        used_bytes:
          type: integer
          format: int64
        file_count:
          type: integer
          format: int32
        max_file_size:
          nullable: true
          type: integer
          format: int64
        max_file_count:
          nullable: true
          type: integer
          format: int32
        tier:
          type: string
          maxLength: 50
        quota_status:
          type: string
        warning_threshold_percent:
          type: integer
          format: int32
        last_warning_sent_at:
          nullable: true
          type: string
          format: date-time
        peak_usage_bytes:
          type: integer
          format: int64
        peak_usage_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    PatchUserQuotaRequest:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
        limit_bytes:
          type: integer
          format: int64
        used_bytes:
          type: integer
          format: int64
        file_count:
          type: integer
          format: int32
        max_file_size:
          nullable: true
          type: integer
          format: int64
        max_file_count:
          nullable: true
          type: integer
          format: int32
        tier:
          type: string
          maxLength: 50
        quota_status:
          type: string
        warning_threshold_percent:
          type: integer
          format: int32
        last_warning_sent_at:
          nullable: true
          type: string
          format: date-time
        peak_usage_bytes:
          type: integer
          format: int64
        peak_usage_at:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    UserQuotaList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/UserQuota'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          example: 100
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 20
        total_pages:
          type: integer
          example: 5

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: VALIDATION_ERROR
        message:
          type: string
          example: Invalid input data
        details:
          type: object
          additionalProperties: true

  parameters:
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid

    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1

    PerPageParam:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

    SortByParam:
      name: sort_by
      in: query
      schema:
        type: string

    SortOrderParam:
      name: sort_order
      in: query
      schema:
        type: string
        enum: [asc, desc]
        default: asc

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  requestBodies:
    BatchIds:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [ids]
            properties:
              ids:
                type: array
                items: { type: string }

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []