API Documentation

Integrate StoreVitals health scans into your tools and workflows.

Authentication

API keys via Bearer token. Generate keys in Settings.

Rate Limits

Agency plan: 200 pages/scan, unlimited scans.

Agency Only

API access requires an active Agency plan ($49/mo).

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your Settings page.

Authorization: Bearer sv_your_api_key_here

Endpoints

POST/api/v1/scan

Run a health scan on a store URL. Returns a full report with score, issues, and page-level details.

Request

curl -X POST https://store-vitals.com/api/v1/scan \
  -H "Authorization: Bearer sv_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-store.com",
    "maxPages": 50
  }'

Response

{
  "url": "https://your-store.com",
  "score": 74,
  "pagesCrawled": 18,
  "platform": "shopify",
  "scanDurationMs": 12340,
  "summary": {
    "total": 8,
    "critical": 2,
    "warnings": 4,
    "info": 2,
    "byCategory": {
      "broken_link": 2,
      "missing_alt": 3,
      "slow_page": 1,
      "missing_meta": 2
    }
  },
  "issues": [
    {
      "category": "broken_link",
      "severity": "critical",
      "page": "https://your-store.com/products/item",
      "detail": "Broken external link: ... (HTTP 404)"
    }
  ],
  "pages": [
    {
      "url": "https://your-store.com/",
      "status": 200,
      "loadTimeMs": 1800,
      "title": "Your Store",
      "issues": 2
    }
  ]
}

Parameters: url (required) — the store URL to scan. maxPages (optional, default 200, max 200) — maximum pages to crawl.

GET/api/v1/report

Generate a white-label HTML report for a specific scan. Returns unbranded HTML suitable for emailing to clients.

Request

curl "https://store-vitals.com/api/v1/report?scanId=<uuid>&agencyName=My+Agency" \
  -H "Authorization: Bearer sv_your_key"

Parameters: scanId (required) — UUID of the scan. agencyName (optional) — your agency name for the report header.

Returns text/html. The report uses a clean light theme with no StoreVitals branding.

Error Codes

401Missing or invalid API key

403Invalid key, expired key, or not on Agency plan

400Missing required fields or invalid input

404Resource not found (scan, store, etc.)

500Server error — target site may be unreachable

Ready to integrate?

Upgrade to the Agency plan to get API access, white-label reports, and more.

View Plans