HTTP API · Docs — BlockAlt

Endpoints #

Method and path	Called by	Purpose
`POST /v1/siteverify`	Your server	Verify a token; see server verification
`GET /v1/keys`	You, at install time	Configuration public keys to pin (current Ed25519 and P-256, then standby)
`GET /v1/script-manifest`	You, at install time	Current script path, size and integrity hash
`GET /v1/assets/blockalt.<sha256>.js`	Browsers	Immutable, content-addressed script, cached for a year
`GET /v1/blockalt.js`	Browsers	Alias of the newest script, cached for five minutes
`GET /v1/browser/config/{siteKey}`	The script	Signed site configuration for the page's origin
`POST /v1/browser/challenge`	The script	A proof-of-work challenge for an action
`POST /v1/browser/token`	The script	Exchanges a solved challenge for a token
`GET /healthz`, `GET /readyz`	Monitoring	Liveness and readiness

The /v1/browser/* endpoints check the page's Origin against the site's origins and are meant for the script only; their request format may change within the compatibility promise of the script.

The machine-readable description is the OpenAPI document (OpenAPI 3.0): the public endpoints with their request and response schemas and every status, and the console and management routes with their summaries and the API key scope each one needs.

Errors #

API errors are JSON with success: false, a reason and an id:

JSON

{ "success": false, "reason": "rate_limited", "id": "e3b9a1d4-2c7f-4a0b-9d6e-8f1a2b3c4d5e" }

Status	When
400	Invalid JSON, missing or unknown fields
401	Missing or invalid secret key on `/v1/siteverify`
403	Browser endpoints: origin, hostname, action or rule refused
413	Body larger than 8 KiB
415	Body not sent as JSON (`application/json`; the browser endpoints also take `text/plain`)
429	Rate limited
503	Temporary failure

Versioning #

The /v1 contract is stable: fields and reasons may be added, never removed or changed in meaning without a new version and a migration window announced on the changelog. Write clients that ignore unknown fields and treat unknown refusal reasons as refusals.

Base URL: https://blockalt.click.