Public API

Every page on HeaderLens has a JSON equivalent. The full contract is in openapi.yaml (also JSON). No key is required; fresh checks are rate-limited per client.

Endpoints
Method	Path	Operation
`POST`	`/api/v1/check`	runWebsiteCheck Run a fresh observation against a public hostname
`GET`	`/api/v1/status/{hostname}`	getLatestStatus Get the latest stored observation for a hostname
`GET`	`/api/v1/status/{hostname}/history`	getStatusHistory Historical observations and availability rollups
`GET`	`/api/v1/recent`	listRecentChecks Recently checked hostnames (hostnames only, never paths)
`GET`	`/api/v1/methodology`	getMethodology Machine-readable status semantics
`GET`	`/api/v1/schema`	getSchemaInfo Schema and API version information
`GET`	`/api/v1/health`	getHealth Service health (of HeaderLens itself, not of any target)

Example

curl -s -X POST https://headerlens.usefulweb.site/api/v1/check \
  -H 'content-type: application/json' \
  -d '{"target":"example.com"}'

Semantics that matter

A target being down is still 200 OK with observation.classification = "down". Errors are reserved for problems with your request or our infrastructure.
400 malformed body · 422 invalid or non-public target · 429 rate-limited (see Retry-After) · 503 probe capacity unavailable.
Errors use application/problem+json (RFC 9457).
Every result carries observedAt, vantage.region, checkerVersion and methodologyVersion. Treat results as timestamped observations, not timeless facts.
Human pages also answer Accept: application/json with the same document.