gallery-organizer-web/specs/001-archive-curator/contracts/openapi.yaml

openapi: 3.0.3
info:
  title: Archive Curator API
  version: 0.1.0
servers:
  - url: http://localhost:8080
paths:
  /health:
    get:
      summary: Service health check
      responses:
        '200':
          description: OK
  /config:
    get:
      summary: Get current configuration
      responses:
        '200':
          description: Configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'
    put:
      summary: Update configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Configuration'
      responses:
        '200':
          description: Updated configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'
        '400':
          description: Invalid or unsafe configuration
  /directories/untagged/next:
    get:
      summary: Get next untagged directory for review
      responses:
        '200':
          description: Untagged directory collage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UntaggedCollage'
        '404':
          description: No untagged directories available
  /directories/untagged/{directoryId}/resample:
    post:
      summary: Resample collage for current untagged directory
      parameters:
        - name: directoryId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated collage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UntaggedCollage'
  /directories/untagged/{directoryId}/keep:
    post:
      summary: Keep an untagged directory
      parameters:
        - name: directoryId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Keep decision recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionResult'
        '409':
          description: Read-only mode enabled
  /directories/untagged/{directoryId}/preview-delete:
    post:
      summary: Preview deletion for an untagged directory
      parameters:
        - name: directoryId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Preview of deletion and list-file changes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePreview'
        '409':
          description: Read-only mode enabled
  /directories/untagged/{directoryId}/confirm-delete:
    post:
      summary: Confirm deletion for an untagged directory
      parameters:
        - name: directoryId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteConfirm'
      responses:
        '200':
          description: Deletion executed and audited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionResult'
        '409':
          description: Read-only mode enabled
  /triage/whitelist/next:
    get:
      summary: Get next whitelisted media item for triage
      parameters:
        - name: scope
          in: query
          required: false
          schema:
            type: string
            description: all or specific user id
        - name: order
          in: query
          required: false
          schema:
            type: string
            enum: [random, largest]
      responses:
        '200':
          description: Triage item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriageItem'
        '404':
          description: No items available
  /triage/whitelist/{itemId}/keep:
    post:
      summary: Keep current triage item
      parameters:
        - name: itemId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Keep recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionResult'
  /triage/whitelist/{itemId}/preview-delete:
    post:
      summary: Preview deletion for a whitelisted media item
      parameters:
        - name: itemId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Preview of file deletion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePreview'
        '409':
          description: Read-only mode enabled
  /triage/whitelist/{itemId}/confirm-delete:
    post:
      summary: Confirm deletion for a whitelisted media item
      parameters:
        - name: itemId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteConfirm'
      responses:
        '200':
          description: Deletion executed and audited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionResult'
        '409':
          description: Read-only mode enabled
  /audit/recent:
    get:
      summary: Get recent audit entries
      responses:
        '200':
          description: Recent audit log
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuditEntry'

components:
  schemas:
    Configuration:
      type: object
      required:
        - untagged_root
        - whitelisted_root
        - kept_root
        - trash_root
        - download_list_path
        - audit_log_path
        - state_db_path
        - read_only_mode
        - hard_delete_enabled
      properties:
        untagged_root:
          type: string
        whitelisted_root:
          type: string
        kept_root:
          type: string
        trash_root:
          type: string
        download_list_path:
          type: string
        audit_log_path:
          type: string
        state_db_path:
          type: string
        read_only_mode:
          type: boolean
        hard_delete_enabled:
          type: boolean
        excluded_patterns:
          type: array
          items:
            type: string
    UntaggedCollage:
      type: object
      properties:
        directory_id:
          type: string
        directory_name:
          type: string
        total_size_bytes:
          type: integer
        file_count:
          type: integer
        samples:
          type: array
          items:
            $ref: '#/components/schemas/MediaItem'
    MediaItem:
      type: object
      properties:
        id:
          type: string
        user_directory_id:
          type: string
        relative_path:
          type: string
        size_bytes:
          type: integer
        media_type:
          type: string
    TriageItem:
      type: object
      properties:
        media_item:
          $ref: '#/components/schemas/MediaItem'
        user_name:
          type: string
    DeletePreview:
      type: object
      properties:
        preview_id:
          type: string
        target_paths:
          type: array
          items:
            type: string
        list_file_changes_preview:
          type: array
          items:
            type: string
        can_proceed:
          type: boolean
        read_only_mode:
          type: boolean
    DeleteConfirm:
      type: object
      required:
        - preview_id
        - remove_from_list_file
      properties:
        preview_id:
          type: string
        remove_from_list_file:
          type: boolean
    DecisionResult:
      type: object
      properties:
        outcome:
          type: string
        audit_entry_id:
          type: string
    AuditEntry:
      type: object
      properties:
        id:
          type: string
        timestamp:
          type: string
        action_type:
          type: string
        affected_paths:
          type: array
          items:
            type: string
        list_file_changes:
          type: array
          items:
            type: string
        outcome:
          type: string
        preview_id:
          type: string