openapi: 3.0.3
info:
  title: Admin Findings API (Internal)
  version: 0.1.0
  description: |
    Internal contracts for the generic Findings pipeline.
    Drift MVP is the first generator (finding_type=drift).

servers:
  - url: /admin/api

paths:
  /findings:
    get:
      summary: List findings
      parameters:
        - in: query
          name: finding_type
          schema:
            type: string
            enum: [drift, audit, compare]
        - in: query
          name: status
          schema:
            type: string
            enum: [new, acknowledged]
        - in: query
          name: scope_key
          schema:
            type: string
        - in: query
          name: current_run_id
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Finding'

  /findings/{id}:
    get:
      summary: Get finding detail
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Finding'

  /findings/{id}/acknowledge:
    post:
      summary: Acknowledge a finding
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Finding'

  /drift/generate:
    post:
      summary: Generate drift findings (async)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scope_key:
                  type: string
                  description: Inventory selection hash
              required: [scope_key]
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DriftGenerateAccepted'

components:
  schemas:
    DriftGenerateAccepted:
      type: object
      properties:
        bulk_operation_run_id:
          type: integer
          description: Canonical async run record (status/errors/idempotency)
        scope_key:
          type: string
        baseline_run_id:
          type: integer
        current_run_id:
          type: integer
      required: [bulk_operation_run_id, scope_key, baseline_run_id, current_run_id]

    Finding:
      type: object
      properties:
        id:
          type: integer
        finding_type:
          type: string
          enum: [drift, audit, compare]
        tenant_id:
          type: integer
        scope_key:
          type: string
        baseline_run_id:
          type: integer
          nullable: true
        current_run_id:
          type: integer
          nullable: true
        fingerprint:
          type: string
        subject_type:
          type: string
        subject_external_id:
          type: string
        severity:
          type: string
          enum: [low, medium, high]
        status:
          type: string
          enum: [new, acknowledged]
        acknowledged_at:
          type: string
          nullable: true
        acknowledged_by_user_id:
          type: integer
          nullable: true
        evidence_jsonb:
          type: object
          additionalProperties: true