openapi: 3.0.3
info:
  title: VETS Coin Transparency API Supplement
  version: 2026-02-16
  description: >-
    Supplemental OpenAPI document for public transparency endpoints used by dashboards,
    reconciliation jobs, and audit exports.
servers:
  - url: https://vets-coin.com
paths:
  /transparency/audit-anomalies/summary.json:
    get:
      summary: Get selected run anomaly summary
      operationId: getTransparencyAnomalySummary
      parameters:
        - in: query
          name: run
          schema:
            type: string
          description: latest or historical run token (YYYYMMDDTHHMMSSZ)
        - in: query
          name: include_top_anomalies
          schema:
            type: boolean
          description: Include bounded top anomalies array from summary payload
        - in: query
          name: top_limit
          schema:
            type: integer
            minimum: 1
            maximum: 50
          description: Max top anomalies to include when include_top_anomalies is true
      responses:
        '200':
          description: Summary payload
          content:
            application/json:
              example:
                success: true
                selected_run: latest
                selected_label: Latest (rolling)
                summary_available: true
                compare_with_latest: null
                include_top_anomalies: true
                top_limit: 5
                top_anomalies_count: 2
                top_anomalies:
                  - severity: bad
                    signature: abc123
                    anomaly_types: outlier_delta
                    max_abs_delta: 1200
  /transparency/audit-anomalies/runs.json:
    get:
      summary: List available anomaly runs
      operationId: getTransparencyAnomalyRuns
      parameters:
        - in: query
          name: run
          schema:
            type: string
          description: Optional selected run value
      responses:
        '200':
          description: Run inventory payload
          content:
            application/json:
              example:
                success: true
                selected_run: latest
                count: 2
                runs:
                  - run: latest
                    label: Latest (rolling files)
                    is_complete: true
                    is_selected: true
                  - run: '20260215T113203Z'
                    label: '2026-02-15 11:32:03 UTC'
                    is_complete: true
                    is_selected: false
  /transparency/audit-anomalies/trend.json:
    get:
      summary: Get anomaly trend points
      operationId: getTransparencyAnomalyTrend
      parameters:
        - in: query
          name: run
          schema:
            type: string
          description: Optional selected run value
        - in: query
          name: metric
          schema:
            type: string
            enum: [sigs, rows]
          description: Trend metric projection
        - in: query
          name: include_status_counts
          schema:
            type: boolean
          description: Return compact ok/warn/bad/other counts
        - in: query
          name: severity
          schema:
            type: string
            enum: [bad, warn]
        - in: query
          name: signature
          schema:
            type: string
        - in: query
          name: types
          schema:
            type: string
        - in: query
          name: min_abs_delta
          schema:
            type: number
            format: double
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 25
            maximum: 2000
      responses:
        '200':
          description: Trend payload
          content:
            application/json:
              example:
                success: true
                selected_run: latest
                selected_metric: rows
                include_status_counts: true
                status_counts:
                  ok: 1
                  warn: 1
                  bad: 1
                  other: 0
                count: 3
                points:
                  - run_id: '20260214T100000Z'
                    label: '2026-02-14 10:00:00 UTC'
                    rows_total: 9
                    metric: rows
                    metric_value: 9
                    metric_delta: null
                    metric_delta_pct: null
  /transparency/audit-anomalies/alerts.json:
    get:
      summary: Evaluate selected run against configurable alert thresholds
      operationId: getTransparencyAnomalyAlerts
      parameters:
        - in: query
          name: run
          schema:
            type: string
          description: latest or historical run token (YYYYMMDDTHHMMSSZ)
        - in: query
          name: sigs_increase_threshold_pct
          schema:
            type: number
            format: float
            minimum: 0
          description: Minimum run-over-run signatures percent increase required to emit spike alert
        - in: query
          name: rows_increase_threshold_pct
          schema:
            type: number
            format: float
            minimum: 0
          description: Minimum run-over-run rows percent increase required to emit spike alert
        - in: query
          name: include_recommendations
          schema:
            type: boolean
          description: Include next-step recommendations in payload
      responses:
        '200':
          description: Alert snapshot payload
          content:
            application/json:
              example:
                success: true
                selected_run: latest
                selected_label: Latest (rolling)
                evaluated_at: '2026-02-16T08:00:00Z'
                snapshot:
                  alert_level: bad
                  should_alert: true
                  thresholds:
                    sigs_increase_threshold_pct: 50.0
                    rows_increase_threshold_pct: 50.0
                  points_available: 5
                  current:
                    run_id: latest
                    overall: bad
                    signatures_with_anomalies: 4
                    rows_total: 12
                    sig_delta: 3
                    sig_delta_pct: 300.0
                    rows_delta: 3
                    rows_delta_pct: 33.3
                  baseline:
                    run_id: '20260215T100000Z'
                    overall: warn
                    signatures_with_anomalies: 1
                    rows_total: 9
                  alerts:
                    - code: overall_bad
                      severity: bad
                      message: Current run overall status is bad.
                    - code: sigs_spike_pct
                      severity: bad
                      message: Signatures-with-anomalies rose by +300.0% vs previous run.
                  recommendations:
                    - Export compare JSON and CSV for selected run against latest baseline.
                    - Review top anomaly types and drill into largest delta signatures first.
  /transparency/audit-anomalies/alerts.csv:
    get:
      summary: Download current alert snapshot as CSV
      operationId: getTransparencyAnomalyAlertsCsv
      parameters:
        - in: query
          name: run
          schema:
            type: string
          description: latest or historical run token (YYYYMMDDTHHMMSSZ)
        - in: query
          name: sigs_increase_threshold_pct
          schema:
            type: number
            format: float
            minimum: 0
        - in: query
          name: rows_increase_threshold_pct
          schema:
            type: number
            format: float
            minimum: 0
      responses:
        '200':
          description: CSV download
  /transparency/audit-anomalies/diff/export.json:
    get:
      summary: Get selected-vs-latest anomaly type diff as JSON
      operationId: getTransparencyAnomalyDiffExportJson
      parameters:
        - in: query
          name: run
          required: true
          schema:
            type: string
          description: Historical run token (YYYYMMDDTHHMMSSZ)
        - in: query
          name: include_rows
          schema:
            type: boolean
          description: Include row-level context arrays
        - in: query
          name: row_limit
          schema:
            type: integer
            minimum: 1
            maximum: 250
      responses:
        '200':
          description: Diff payload
          content:
            application/json:
              example:
                success: true
                selected_run: '20260215T113203Z'
                latest_generated_at: '2026-02-16T00:00:00Z'
                selected_total: 5
                latest_total: 3
                total_delta: 2
                include_rows: true
                row_limit: 1
                selected_rows_count: 1
                latest_rows_count: 1
                rows:
                  - type: outlier_delta
                    selected: 4
                    latest: 1
                    delta: 3
                    pct_delta: 300.0
        '400':
          description: run missing or invalid
        '404':
          description: run not found
  /transparency/audit-anomalies/diff/compare.json:
    get:
      summary: Compare anomaly type deltas between any two runs
      operationId: getTransparencyAnomalyCompareJson
      parameters:
        - in: query
          name: run_a
          required: true
          schema:
            type: string
          description: latest or historical run token (YYYYMMDDTHHMMSSZ)
        - in: query
          name: run_b
          required: true
          schema:
            type: string
          description: latest or historical run token (YYYYMMDDTHHMMSSZ)
        - in: query
          name: include_rows
          schema:
            type: boolean
          description: Include row-level context arrays
        - in: query
          name: row_limit
          schema:
            type: integer
            minimum: 1
            maximum: 250
      responses:
        '200':
          description: Compare payload
          content:
            application/json:
              example:
                success: true
                run_a:
                  selector: '20260215T113203Z'
                  resolved_run: '20260215T113203Z'
                run_b:
                  selector: latest
                  resolved_run: latest
                total_delta: 2
                include_rows: false
                rows:
                  - type: outlier_delta
                    selected: 4
                    latest: 1
                    delta: 3
        '400':
          description: args missing or invalid
        '404':
          description: run not found
  /transparency/audit-anomalies/diff/compare.csv:
    get:
      summary: Download anomaly type deltas between any two runs as CSV
      operationId: getTransparencyAnomalyCompareCsv
      parameters:
        - in: query
          name: run_a
          required: true
          schema:
            type: string
        - in: query
          name: run_b
          required: true
          schema:
            type: string
        - in: query
          name: include_rows
          schema:
            type: boolean
          description: Append run row context sections below the main CSV table
        - in: query
          name: row_limit
          schema:
            type: integer
            minimum: 1
            maximum: 250
      responses:
        '200':
          description: CSV download
        '400':
          description: args missing or invalid
        '404':
          description: run not found
