API Reference & Integration

The SiteScore API lets Pro and Agency accounts trigger scans and read results programmatically — for CI pipelines, internal tools, Zapier, or your own dashboard. Generate a key from your dashboard's Developer panel.

Authentication

Pass your key as a bearer token. Keys look like ssk_<48 hex chars> and are shown once, at creation.

Authorization: Bearer ssk_your_key_here

POST /api/v1/scans

Starts a scan and waits for it to complete (typically 15–45s).

curl -X POST https://your-domain.com/api/v1/scans \
  -H "Authorization: Bearer ssk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# => { "id": "...", "score": 78, "grade": "B", "reportUrl": "https://.../report/..." }

GET /api/v1/scans/:id

Fetches the full scan result (same shape used to render the report page).

curl https://your-domain.com/api/v1/scans/<id> \
  -H "Authorization: Bearer ssk_your_key_here"

Rate Limits

Same ceiling as the dashboard: 60 scans/hour on Pro, 120/hour on Agency. Exceeding it returns 429 with a Retry-After header.

Webhooks

Add an HTTPS endpoint in the Developer panel and we'll POST a scan.completed event whenever a scan you triggered — via the API, the dashboard, or a scheduled re-scan — finishes. Verify the X-SiteScore-Signatureheader: it's an HMAC-SHA256 of the raw request body, keyed with the webhook secret shown when you created it.

const expected = crypto
  .createHmac("sha256", webhookSecret)
  .update(rawRequestBody)
  .digest("hex");
// compare with the X-SiteScore-Signature header (constant-time)