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. Plan caps still apply: starting an audit past the site cap or the monthly run cap returns 403 with code `plan_limit_hit`. 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.

Actions: GET /api/mcp/actions lists action items, filtered by `status`, `priority`, `siteId`, and `assigneeId`, with `limit` (default 50, max 200). PATCH /api/mcp/actions/{actionId} updates status, priority, assignee, due date, title, or description. POST /api/mcp/actions/{actionId}/comments adds a comment with a JSON `body`. GET /api/mcp/actions/{actionId}/brief reads an item's brief and POST to the same path queues one. POST /api/mcp/actions/handoff takes `ids` (1 to 10 action ids) and an optional `format` of `markdown` or `cursor` and returns a handoff prompt.

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. 403 with code `plan_limit_hit` means the organization hit a plan cap; the `reason` field says whether it was `site_limit_hit` or `monthly_run_limit_hit`. API and MCP access themselves are available on Foundation. 404 means the run, report, site, or action 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.