API Documentation

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer sc_live_...

Generate API keys in Settings under the API tab. Keys are available on Pro and Studio plans.

Rate limits

Every response includes rate limit headers:

• X-RateLimit-Limit: maximum requests per hour
• X-RateLimit-Remaining: requests left in the current window
• X-RateLimit-Reset: Unix timestamp when the window resets

Sites

List sites

GET /api/v1/sites

Returns all sites for the authenticated account.

Query parameters: page (default 1), per_page (default 25, max 100).

{
  "data": [
    {
      "id": "uuid",
      "name": "example.com",
      "url": "https://example.com/",
      "status": "active",
      "scan_frequency": "weekly",
      "last_scanned_at": "2026-03-18T12:00:00Z",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "has_more": false }
}

Get site

GET /api/v1/sites/:id

Returns a single site with its latest scan summary.

Scans

List scans

GET /api/v1/sites/:site_id/scans

Get scan

GET /api/v1/scans/:id

Response fields: id, site_id, status, score, checks_total, passed_count, critical_count, warning_count, pages_scanned, delta_fixed_count, delta_regressed_count, started_at, completed_at.

Trigger scan

POST /api/v1/sites/:site_id/scans

Returns 202 Accepted. The scan runs asynchronously. Poll the scan endpoint or use webhooks to know when it completes.

Returns 409 if a scan is already in progress. Returns 429 if the daily quota is exceeded.

Findings

List findings for a scan

GET /api/v1/scans/:scan_id/findings

Optional filters:

• category: one of the API filter keys listed below

• severity: critical, warning, info
• passed: true or false
• check_key: filter by specific check key
• page_url: filter by page URL
• page (default 1), per_page (default 50, max 200)

Response fields: id, category, check_key, severity, passed, message, remediation, page_url, value, evidence.

Reports

Get report

GET /api/v1/reports/:token

Returns report metadata: token, site_id, scan_id, token_expires_at, created_at.

Intelligence

Historical analysis that one-shot scans cannot replicate.

Score trends

GET /api/v1/sites/:id/intelligence/trends?limit=20

Returns score history for completed scans, oldest first.

Regressions

GET /api/v1/sites/:id/intelligence/regressions

Findings that regressed (passed to failed) or are new issues between the latest two scans.

Improvements

GET /api/v1/sites/:id/intelligence/improvements

Check keys that were fixed between the latest two scans.

Priority inbox

GET /api/v1/intelligence/priority

Up to 5 prioritized action items across all sites: critical regressions, score drops, persistent critical issues, quick wins, and stale scans.

Webhooks

Endpoints

Create request body

{ "url": "https://...", "events": ["scan_completed"] }

Available events: scan_completed, score_dropped, critical_regression.

Payload headers

• X-SiteCurl-Event: event type
• X-SiteCurl-Signature: HMAC-SHA256 signature (v1=<hex>)
• X-SiteCurl-Timestamp: Unix timestamp

Verify the signature: HMAC-SHA256(secret, "#{timestamp}.#{body}")

Example: scan_completed

{
  "event": "scan_completed",
  "site_id": "uuid",
  "scan_id": "uuid",
  "score": 85,
  "checks_total": 80,
  "passed_count": 68,
  "critical_count": 2,
  "warning_count": 10,
  "report_token": "abc123..."
}

Example: score_dropped

{
  "event": "score_dropped",
  "site_id": "uuid",
  "scan_id": "uuid",
  "current_score": 72,
  "previous_score": 85,
  "drop": 13
}

Example: critical_regression

{
  "event": "critical_regression",
  "site_id": "uuid",
  "scan_id": "uuid",
  "critical_checks": ["https_redirect", "mixed_content"]
}

MCP (AI tools)

SiteCurl provides a remote MCP server for AI coding tools like Claude Code, Cursor, and Windsurf. It uses the same API key as the REST API.

Endpoint

POST /api/v1/mcp

Protocol: JSON-RPC 2.0. Methods: initialize, tools/list, tools/call.

Setup

Add to your Claude Code or Cursor settings:

{
  "mcpServers": {
    "sitecurl": {
      "url": "https://sitecurl.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer sc_live_..."
      }
    }
  }
}

Available tools

Error responses

All errors return JSON:

{ "error": "Description of the error" }

Machine-readable spec

The full OpenAPI 3.1.0 specification is available at /openapi.yaml.

Questions?

Get in touch if anything is unclear.