Authentication

The API uses org-scoped keys. Generate one under Settings → API & MCP (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 and MCP access are available on every plan, including Foundation. Some product features (for example schedules) still return 402 until the organization is on a paid plan. The base URL is your PageReflect instance; the MCP server and CLI call this same surface.

HTTP

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 six 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 a paid-only feature (for example schedules) requires an upgrade — API and MCP access themselves are available on Foundation. 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.