API Overview

Site Health exposes four programmatic surfaces. Pick the one that matches how you want to integrate.

Surface	Audience	Protocol	Auth	Base URL
REST API	CI/CD, custom scripts, external tooling	HTTPS + JSON	Bearer API key (wsh_…)	https://sitehealth.octagramlabs.com/api/external/*
MCP server	AI clients (Claude Desktop, Claude Code, Cursor, Claude.ai)	JSON-RPC 2.0 over HTTP	Bearer API key or OAuth access token	https://sitehealth.octagramlabs.com/api/mcp
OAuth 2.1 Authorization Server	MCP clients that support Dynamic Client Registration (Claude.ai)	OAuth 2.1 + PKCE + DCR	— (issues tokens)	https://sitehealth.octagramlabs.com/.well-known/oauth-authorization-server
Inbound webhooks	Webflow → Site Health (we receive)	HTTPS POST + HMAC	HMAC-SHA256 over body	https://sitehealth.octagramlabs.com/api/webhooks/webflow

Which endpoint do I use?

I want to…	Use this	Docs
Fail a CI pipeline when perf drops below a threshold	POST /api/external/budget-check	REST API
Ask Claude "what regressed on this site since Friday?"	MCP tool get_regression_report via Claude Desktop	MCP Tools
Connect Claude.ai to Site Health with one click	OAuth 2.1 flow (auto-discovered)	OAuth
Auto-scan a site when it's published in Webflow	Register a Webflow site_publish webhook	Webhooks
Export a scan as CSV for stakeholders	GET /api/sites/{siteId}/export?format=csv	REST API
Show historical score trends in a custom dashboard	MCP tool get_trend or direct DB export	MCP Tools

Auth at a glance

Two credentials are accepted everywhere Bearer auth is required:

• wsh_… API keys — created in Settings → API Keys. Used by REST API calls and manually-configured MCP clients (Claude Desktop, Cursor). Never expire until revoked.
• at_… OAuth access tokens — issued by our Authorization Server to Claude.ai (and any RFC 7591-capable client) during the OAuth flow. 30-day lifetime, refreshable.

Both are sent identically:

Authorization: Bearer <token>

See Authentication for the full matrix, creation flow, and rate limits.

Base URL

Every path in this reference section is relative to:

https://sitehealth.octagramlabs.com

Local development uses http://localhost:3000 with the same routes.

Content types

• REST API — application/json request and response bodies.
• MCP — JSON-RPC 2.0 envelopes (application/json).
• Export — text/csv; charset=utf-8 or application/json via the format query param.
• Webhooks — application/json from Webflow (we verify raw body against x-webflow-signature).

Error model

REST endpoints return standard HTTP status codes. Error bodies share a shape:

{
  "error": "Human-readable message"
}

Zod validation failures return a flattened error map at 422:

{
  "error": {
    "formErrors": [],
    "fieldErrors": { "siteId": ["Invalid uuid"] }
  }
}

MCP errors follow JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32602, "message": "Invalid arguments: …" }
}

Versioning

Site Health is pre-1.0. The MCP server advertises version 0.1.0 via initialize. Breaking changes will be announced in the changelog and preserved on a /api/v1/* path when a stable version ships.

tip

If you are writing a CI integration, start with POST /api/external/budget-check — it's the most stable endpoint and requires zero client state.

Next steps

• Authentication → — create an API key, understand rate limits
• OAuth reference → — Authorization Server metadata, DCR, token flow
• MCP tools → — all 9 tools with request/response examples
• REST API → — budget-check and export endpoints
• Webhooks → — receiving site_publish events from Webflow