Skip to content

API.md

Latest commit

 

History

History
49 lines (37 loc) · 2.69 KB

API.md

File metadata and controls

49 lines (37 loc) · 2.69 KB
Raw

Scrutiny API

Scrutiny now documents its HTTP API from a canonical OpenAPI specification:

  • OpenAPI spec: openapi.yaml
  • Swagger UI: swagger-ui.html
  • Served Swagger UI path: /docs/api
  • Served OpenAPI path: /api/docs/openapi.yaml
  • Default auth behavior: both served docs routes require auth unless web.docs.public=true

Scope

The spec covers the current /api/* routes registered in webapp/backend/pkg/web/server.go.

That includes:

  • authentication and session login
  • health and diagnostics
  • device registration, uploads, details, self-test history, actions, and performance
  • settings, SMART overrides, and notification URLs
  • replacement-risk metadata, including consumer ATA profile usage
  • report generation and report history
  • filesystem capacity
  • ZFS pools
  • Btrfs filesystems
  • MDADM arrays
  • Prometheus metrics

Auth Model

Scrutiny uses Bearer authentication when web.auth.enabled is on.

  • Public routes: /api/health, /api/auth/status, /api/auth/login
  • Docs routes: /docs/api and /api/docs/openapi.yaml are protected by default and become public only when web.docs.public=true
  • Protected routes: all other /api/* routes
  • Metrics route: /api/metrics may accept the general auth token or the dedicated metrics token, depending on configuration

See AUTH.md for configuration and deployment details.

Notes

  • The OpenAPI document is the source of truth. Do not add new standalone API tables elsewhere in the repo.
  • Some collector payloads are intentionally documented as structured objects with representative fields because the backend accepts large collector-origin JSON models.
  • GET /api/device/{id}/selftest returns ATA SMART self-test history already recorded during normal SMART uploads. The separate POST /api/device/{id}/selftest route remains reserved for future ingestion work.
  • Notification URL endpoints cover existing Shoutrrr syntax, explicit apprise+... targets, script:// targets, and raw http(s) webhooks.
  • The replacement-risk endpoint includes ATA-specific metadata describing whether a bundled consumer-drive profile was enabled and applied for that score, plus provenance fields (source, sample count, match method, catalog version) when a profile is applied.
  • GET /api/device/{id}/drive-profile is a debug surface reporting the full consumer-drive profile match path: match method, confidence gate result, applied overrides, and fallback reason.
  • For operator-facing behavior and the global opt-out setting, see CONSUMER_DRIVE_PROFILES.md.
  • If a route is added or changed in server.go, update openapi.yaml in the same change.