Agent-friendly API

Ask whether a component changed materially and receive structured evidence.

Authentication and discovery

Create a short-lived CLI token in the console and send Authorization: Bearer TOKEN. OpenAPI JSON schemas are at /api/reference and /openapi.json. Browser sessions use secure HTTP-only cookies, an exact-origin check and a session-bound CSRF token.

scan_component

POST /api/scans with kind and target queues a public target scan. For a pasted manifest, send kind: manifest and content containing a JSON string. Poll GET /api/scans/{id} until completed or failed. Requests never accept executable instructions.

{"kind":"npm","target":"@scope/package"}

compare_baseline

POST /api/compare with baseline_scan_id and current_scan_id compares two scans you own. The deterministic response includes old/new values, severity, evidence location, confidence, rationale and recommendation.

check_component and get_drift_status

GET /api/dashboard returns your watches, scan history, drift events and alert deliveries. The latest checked time distinguishes stale observations from fresh evidence. POST /api/monitors with scan_id approves a watch; creating or changing monitoring requires an owner session and server-side entitlement.

explain_finding

Every finding is self-contained: type, old_value, new_value, affected_path, evidence, severity, why_it_matters, confidence, recommendation and references. No LLM explanation is required. DriftSeal exposes this documented HTTP API; a separate MCP transport is not required in v0.1.

Signed webhooks

PRO and TEAM can register up to five public HTTPS destinations. Delivery includes X-DriftSeal-Event, X-DriftSeal-Timestamp and X-DriftSeal-Signature. Verify HMAC-SHA256 over timestamp + '.' + the exact body using the displayed signing secret. Reject timestamps outside five minutes and persist event IDs to reject replay. Use constant-time comparison. Never parse and reserialize the body before verification.

The same event ID is reused across at most five attempts. Delivery is at least once: receivers must deduplicate. Redirects are rejected. DNS and public-IP checks run for every delivery, and the connection is pinned to the validated address.