Authentication

All API requests require an API key passed as a Bearer token in the Authorization header. Generate keys on your Account page.

Authorization: Bearer sg_<your_key>

Base URL

https://searchgrade.app

Endpoints

POST/audit

Run a full page audit on a single URL. Returns score, grade, and all check results.

Request body

Example

curl -X POST https://searchgrade.app/audit \
  -H "Authorization: Bearer sg_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Response

{
  "score": 74,
  "grade": "C",
  "results": [
    {
      "name": "[Technical] Cache-Control",
      "status": "fail",
      "score": 0,
      "maxScore": 100,
      "message": "No Cache-Control header found.",
      "recommendation": "Add a Cache-Control header..."
    },
    ...
  ],
  "pdfFile": "searchgrade-report-example.com-2026-04-26.pdf"
}

GET/crawl?url=<url>

Run a full site crawl audit. Returns a Server-Sent Events stream with progress updates and a final aggregated result.

Query parameters

Example

curl -N "https://searchgrade.app/crawl?url=https://example.com" \
  -H "Authorization: Bearer sg_<your_key>" \
  -H "Accept: text/event-stream"

SSE event types

Browser Extension

Audit the page you're viewing straight from your browser toolbar. Available on Pro and Agency plans; it authenticates with one of your API keys.

1. Get an API key on your Account page (API Access → Create API Key) and copy it.
2. Install the extension. Download it from your Account page (API Access → Browser Extension), unzip it, then open chrome://extensions, enable Developer mode, click Load unpacked, and select the unzipped searchgrade-extension folder.
3. Configure it. Open the extension's Options, paste your API key, and set the Server URL to https://searchgrade.app.
4. Run an audit. Click the SearchGrade icon on any page — the current tab's URL is pre-filled. You'll see the grade, score, and top issues, with a link to the full report.

Data Feed Endpoints AGENCY

JSON data feed endpoints for connecting SearchGrade data to Looker Studio, Power BI, Tableau, or any analytics platform. All require an Agency-plan API key.

GET /api/export/report-feed

Paginated audit report data with scores, grades, and category breakdowns.

Response: { data: [{ url, auditedAt, auditType, grade, score, technicalScore, contentScore, aeoScore, geoScore, passCount, warnCount, failCount }], total, hasMore }

GET /api/export/cwv-feed

Core Web Vitals time-series data.

Response: { data: [{ url, date, lcpMs, cls, inpMs, performanceScore }], total, hasMore }

GET /api/export/visibility-feed

AI visibility scan data per query.

Response: { data: [{ domain, date, platform, query, queryCategory, mentioned, sentiment, citationCount }], total, hasMore }

CI/CD Integration

Use the CI check endpoint to gate deployments on SEO score. Requires a Pro or Agency API key.

POST /api/ci-check

Returns HTTP 200 if the score meets the threshold, or 422 if it does not. Both return the full result body:

{
  "pass": true,
  "score": 82,
  "grade": "B",
  "threshold": 70,
  "failedChecks": [
    { "name": "[Technical] Missing H1", "status": "fail", "message": "No H1 tag found" }
  ]
}

GitHub Action Example

name: SEO Gate
on: [pull_request]
jobs:
  seo-check:
    runs-on: ubuntu-latest
    steps:
      - name: Run SEO audit
        run: |
          RESULT=$(curl -s -w "\n%{http_code}" \
            -X POST https://your-domain.com/api/ci-check \
            -H "Authorization: Bearer ${{ secrets.SEARCHGRADE_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"url":"https://your-site.com","threshold":70}')
          HTTP_CODE=$(echo "$RESULT" | tail -1)
          BODY=$(echo "$RESULT" | sed '$d')
          echo "$BODY" | jq .
          if [ "$HTTP_CODE" = "422" ]; then
            echo "SEO score below threshold"
            exit 1
          fi

Vercel Deploy Hook

Add a post-deploy script that calls the CI check endpoint after each Vercel deployment. If the score drops below your threshold, the script can notify your team via Slack or fail the pipeline.

Rate Limits

Exceeding the rate limit returns HTTP 429 Too Many Requests. The limit resets every hour.

Error codes

Webhook & CRM Integration

Webhooks let you push SearchGrade events to Zapier, CRMs, Slack, or any HTTP endpoint. Configure webhooks in Account Settings.

Event Types

Payload Format

Every webhook delivery is a POST request with a JSON body:

{
  "event": "audit.complete",
  "data": {
    "url": "https://example.com",
    "score": 72,
    "grade": "C",
    "catScores": { "technical": 80, "content": 65, "aeo": 70, "geo": 68 },
    "topIssues": [
      { "name": "[Technical] Missing H1", "message": "No H1 tag found" }
    ],
    "reportUrl": "/report/42",
    "pdfFile": "report-example-com-1716700800.pdf"
  },
  "timestamp": "2026-05-26T12:00:00.000Z"
}

Signature Verification

Each delivery includes an X-SearchGrade-Signature header with an HMAC-SHA256 signature of the request body, using your webhook secret:

const crypto = require('crypto')
const sig = crypto.createHmac('sha256', webhookSecret)
  .update(requestBody).digest('hex')
const valid = sig === header.replace('sha256=', '')

Zapier Integration

To connect SearchGrade to Zapier:

1. In Zapier, create a new Zap and choose "Webhooks by Zapier" as the trigger.

2. Select "Catch Hook" and copy the webhook URL.

3. In SearchGrade Account Settings, add the Zapier URL as a webhook and select your events.

4. Send a test event from the webhook settings to verify the connection.

5. Use Zapier actions to push data to HubSpot, Salesforce, Slack, Google Sheets, or 5000+ other apps.

Direct CRM Examples

HubSpot: Use the lead.captured event with a Zapier "Create Contact" action, mapping email and url fields to HubSpot contact properties.

Salesforce: Route audit.complete events through Zapier's Salesforce integration to create Tasks or update custom fields on Accounts with the latest SEO score.