init

specs/001-archive-curator/contracts/openapi.yaml

@@ -0,0 +1,351 @@
+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