API reference

API overview

The Sift Health API lets you queue scans, read reports, register and verify sites, list findings, and configure monitoring. It's a JSON REST API consistent with the FastAPI OpenAPI spec.

Base URL & versioning

All public endpoints live under a versioned prefix. The base URL below is illustrative for these docs; use the host shown in your dashboard.

text

https://api.sifthealth.app

Authentication

Authenticate with a bearer token (an API key created in Settings → API keys). Send it in the Authorization header on every request. The one-off free scan endpoints are rate-limited and can be called without a key; everything site- and monitoring-related requires one.

bash

Authorization: Bearer sift_live_xxxxxxxxxxxxxxxxxxxx

Errors

Errors use standard HTTP status codes and a JSON body with a detail field.

json

{
  "detail": "Site not found"
}

Field	Type	Description
400	Bad Request	Malformed body or invalid URL.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Authenticated, but not permitted (e.g. unverified domain for monitoring).
404	Not Found	No such scan, site, or finding.
429	Too Many Requests	Rate limit exceeded — back off and retry.
5xx	Server Error	Transient; retry with backoff.

Rate limits

Limits scale with your plan and are returned on each response. Free/anonymous one-off scans are tightly limited; authenticated plan endpoints get higher quotas. Treat a 429 as a signal to back off exponentially.

The disclaimer contract

Every report payload — from GET /v1/scans/{id}/report — includes a structured disclaimer field. It is part of the data contract, not a footnote: if you render or forward a report, keep the disclaimer with it.

json

{
  "disclaimer": "This automated scan identifies publicly observable risk indicators ... It is not a HIPAA compliance audit or legal determination ...",
  "overall_score": 72,
  "grade": "C",
  "categories": { "tracking": 61, "privacy_policy": 80, "forms": 75, "transport": 90, "headers": 70, "infrastructure": 100 },
  "findings": [ /* ... */ ]
}

Vocabulary in responses

The API speaks the same careful language as the product: scores, indicators, observations, and recommendations — never “compliant”, “certified”, or “pass/fail”.

Create a scan

POST /v1/scans.

Get a report

GET /v1/scans/{id}/report.

POST /v1/sites.

Monitoring

Cadence and alert rules.