API reference

Submit a public page, receive an accepted run, then read its report with the short-lived capability returned for guest access.

POST/api/analyze

Validate a public HTTP(S) target and start the requested device audits. With the database configured, the response queues durable work. Without it, the configured provider calls complete in the request and still return 202.

urlstring · requiredPublic HTTP(S) URL without credentials or private-network targets.

strategiesarray · default bothOne or both of mobile and desktop.

cloudflareConsentboolean · default falseWhen true, submit the target URL to Cloudflare URL Scanner. This is a public third-party submission. It is unavailable when this deployment has not configured Cloudflare access.

observatoryConsentboolean · default falseWhen true, submit the target URL to Mozilla HTTP Observatory. This is a public third-party submission; the report marks it unavailable if the provider cannot respond.

About consent flags. false keeps both optional scans off. true sends only the target URL to that provider; it does not send WebGrade credentials or grant the provider access to your site. Use these flags only for public pages, and never include secrets, signed query strings, private staging URLs, or personal data in the target URL. A disabled or unavailable provider never blocks the other report evidence.

curl -X POST https://webgrade.chames.tn/api/analyze   -H 'content-type: application/json'   -d '{
    "url": "https://example.com",
    "strategies": ["mobile", "desktop"],
    "cloudflareConsent": false,
    "observatoryConsent": false
  }'

GET/api/analyze/:runId

Read a guest run while it is queued, running, completed, or failed. Send the capability from the POST response as a header; it is never placed in the URL.

x-webgrade-capability: <capability returned by POST>

GET/api/health

Check WebGrade application infrastructure. This endpoint does not call PageSpeed, CrUX, Cloudflare, or Observatory, and it does not prove that a target website or provider is available.

{
  "status": "ok",
  "service": "webgrade",
  "version": "1",
  "database": "not_configured"
}

Onlinedatabase ok · worker ok

The web service, database, and recent worker heartbeat are all healthy.

Limitedstatus ok · dependency not ready

The public scanner can be reachable while the database is not configured or the worker heartbeat is stale. The local response above is this state.

Unavailable503 · request failure

The health route cannot confirm the service or its database connection. A dev-server restart can cause this briefly.

The navigation badge starts at Checking, then shows Ready when the public scanner works without persistence, or Online, Limited, and Unavailable for infrastructure states. It refreshes every 30 seconds and keeps these separate from provider results.

GET/api/capabilities

Read which optional features are configured for this deployment. This endpoint does not expose credentials and does not contact third-party providers.

{
  "cloudflareScan": false,
  "observatoryScan": true,
  "cloudShare": false
}

cloudflareScanbooleanConsent can be enabled only when Cloudflare URL Scanner access is configured.

observatoryScanbooleanWhether the Mozilla HTTP Observatory integration is enabled; the provider may still return an unavailable result.

cloudSharebooleanWhether immutable public report snapshots can be stored. Browser share/copy remains separate.

Response states

202Accepted. The body includes a run ID; durable runs may still be queued.

400Invalid JSON, target URL, device strategy, or request values.

401 / 404Missing, invalid, or expired guest capability.

413 / 415 / 429Payload, media type, rate limit, or provider budget limit.

502 / 503Provider failure or durable analysis configuration unavailable.

Feature availability. The scanner labels optional providers as unavailable when this deployment has not configured them. Browser sharing can share or copy the current report URL; a public cloud snapshot requires the owner workspace storage.

Back to scanner PageSpeed documentation