Page Lookout API

The Page Lookout API lets your own systems - a CI job, a script, a back office - start scans of your organization's sites and read what they found, with an API key instead of a person's sign-in. Webhooks work the other way round: Page Lookout sends a signed request to your own HTTPS endpoint whenever a scan finishes.

• Getting started - create a key, find your ids, start a scan and read its findings with three curl calls; pagination.
• Errors and limits - the error body, every details.reason an API key can receive, rate limits, and replacing a key.
• Webhooks - the events, their headers, verifying the signature (Node.js and Python), retries and switching off, rotating the signing secret.
• Versioning - what a version number promises, and how a breaking change is announced.
• Changelog - every published version of the API contract.
• API reference - every operation below, its parameters and its responses, and the two webhook events, generated from the service's own schemas. The machine-readable OpenAPI 3.1 document is published next to it as openapi.json, and the API serves the same document at GET /openapi.json on your API base URL - no key needed.

What an API key can do

An organization admin creates keys on the Integrations screen of the dashboard. A key belongs to one organization and holds one or more scopes; each operation needs one of the scopes listed for it. Scopes are independent: scans:write does not include scans:read.

The paths call a site a domain: {domainId} is a site id. A key can call nothing else - not the key management operations, not team, site, tag or webhook settings - and a request for another organization's id answers 404, exactly as an id that names nothing. The two site operations return each site's tags (id, name and colour, by name); a key reads them and cannot change them. downloadArtifact serves report PDFs only. readScanRunReportSnapshot always returns a report.snapshot/1 document, whatever the dashboard holds for that run; a newer snapshot format is announced in the changelog before it reaches keys.

A key sees every site of its organization. If your organization limits what each member sees to their access groups, that limit applies to people signed in to the dashboard and not to API keys: a key reads every site and starts a scan of any of them, whoever created it. Only organization admins create keys, so give each key the scopes it needs and no more.

Conventions

• Base URL. Every path above is relative to your API base URL, shown on the Integrations screen. The guides write it as $PAGE_LOOKOUT_API_URL.
• JSON. Requests and responses are JSON (application/json), in UTF-8. Timestamps are ISO 8601 in UTC, ids are UUIDs.
• Unknown fields. A response may gain fields in a minor version. Ignore the fields you do not know - see Versioning.
• Correlation ids. Every response carries an x-correlation-id header, and every error body the same value as correlationId. Send your own (1-128 characters of A-Z a-z 0-9 . _ : -) to find a request in both systems; quote it when you contact support.