API reference
API reference
Authentication
The API uses org-scoped keys. Generate one under Settings, API keys (see API keys), then send it as a bearer token on every request. Keys start with `sk_pageref_` and are stored hashed, so a leaked key should be revoked and replaced rather than recovered.
API access is a paid-plan feature. Calls from an organization without a paid plan return 402. The base URL is your PageReflect instance; the MCP server and CLI call this same surface.
POST /api/mcp/start-audit HTTP/1.1
Host: app.pagereflect.com
Authorization: Bearer sk_pageref_...
Content-Type: application/json
{ "url": "https://example.com" }Endpoints
Start an audit: POST /api/mcp/start-audit with a JSON body of `url` (required) and optional `siteId` to attach the run to an existing site. Returns a `runId`.
Poll a run: GET /api/mcp/runs/{runId}. Returns the run status and, once scoring finishes, the linked report id.
Fetch a report: GET /api/mcp/reports/{reportId}. Add `?format=pdf_url` to get a 5-minute signed PDF link instead of the default JSON payload.
List sites: GET /api/mcp/sites. Recent runs for a site: GET /api/mcp/sites/{siteId}/history (default 10, max 100). Current schedule: GET /api/mcp/sites/{siteId}/schedule. Verify the key: GET /api/mcp/account.
Response shapes
`start_audit` returns a `runId`. Poll `get_run` until status is `completed`; the response then includes the report id.
`get_report` in the default JSON form returns the overall score, the five dimension subscores, summaries, and issues. With `format=pdf_url` it returns a short-lived signed URL you can stream to a download.
Errors
401 means the key is missing, mistyped, or revoked. 402 means the organization is not on a paid plan and needs to upgrade for API access. 404 means the run, report, or site id does not belong to your organization.
Poll `get_run` on a sensible interval (a few seconds) rather than in a tight loop; an audit takes from tens of seconds to a couple of minutes depending on site size.