API Documentation

Run 20 SEO checks on any URL with a single API call. Get a score, grade, and actionable recommendations in under 2 seconds.

Base URL

https://seopeek.web.app

All API endpoints live under /api/v1/. All requests and responses use JSON.

Authentication

The free-tier audit endpoint (GET) requires no authentication and is rate-limited. For higher limits, create an API key and include it in the x-api-key header:

curl -H "x-api-key: seo_your_key_here" \
  "https://seopeek.web.app/api/v1/audit?url=https://example.com"

API keys are prefixed with seo_ and tied to the email address used during registration. Keep your key secret and never expose it in client-side code.

Audit Endpoint

Run a full SEO audit on any publicly accessible URL. Returns a score (0-100), letter grade (A-F), summary counts, and all 20 individual check results.

Query Parameters

Restrictions: Private, internal, and localhost URLs are blocked (127.0.0.1, 192.168.*, 10.*, 172.*, *.local). Target URLs have a 10-second fetch timeout.

Get an API Key

Register for an API key using your email address. You start on the free plan with 50 audits per day.

Request Body

curl -X POST "https://seopeek.web.app/api/v1/keys" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Response:

{
  "apiKey": "seo_abc123def456...",
  "plan": "free",
  "limit": "50 audits/day"
}

Health Check

Returns the service status, name, and version. Useful for monitoring uptime.

{
  "status": "ok",
  "service": "seopeek",
  "version": "1.0.0"
}

Response Format

A successful audit returns a JSON object with the following structure:

{
  "url": "https://example.com",
  "score": 82,
  "grade": "B",
  "summary": {
    "passed": 15,
    "warnings": 4,
    "failed": 1,
    "total": 20
  },
  "checks": [
    {
      "id": "title",
      "status": "pass",
      "message": "Title is good (52 chars)",
      "detail": "Example Domain - The Best Example Site"
    },
    {
      "id": "meta-description",
      "status": "fail",
      "message": "Missing meta description",
      "detail": "Add a compelling meta description (120-160 characters)."
    },
    // ... 18 more checks
  ],
  "meta": {
    "scanDuration": "847ms",
    "timestamp": "2026-03-28T14:22:01.000Z"
  }
}

Check Object Fields

The 20 SEO Checks

Every audit runs these 20 checks against the target page. Each check returns pass, warn, or fail.

Scoring Methodology

The overall score is calculated from the results of all 20 checks using a weighted formula:

// Score calculation
const score = Math.round(
  ((passed + warnings * 0.5) / total) * 100
);

• Pass = 1.0 point (full credit)
• Warning = 0.5 points (half credit -- the check is not wrong but could be improved)
• Fail = 0.0 points (no credit)

With 20 checks, a perfect score of 100 requires all 20 to pass. A page with 15 passes, 4 warnings, and 1 fail scores ((15 + 4*0.5) / 20) * 100 = 85.

Grade Scale

Code Examples

# Basic audit (free tier, no auth)
curl "https://seopeek.web.app/api/v1/audit?url=https://example.com"

# With API key for higher limits
curl -H "x-api-key: seo_your_key_here" \
  "https://seopeek.web.app/api/v1/audit?url=https://example.com"

# Pretty-print the JSON output
curl -s "https://seopeek.web.app/api/v1/audit?url=https://example.com" | jq .

# Register for an API key
curl -X POST "https://seopeek.web.app/api/v1/keys" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

// Node.js (native fetch, v18+)
const auditUrl = async (url, apiKey) => {
  const endpoint = `https://seopeek.web.app/api/v1/audit?url=${encodeURIComponent(url)}`;
  const headers = apiKey ? { 'x-api-key': apiKey } : {};

  const res = await fetch(endpoint, { headers });
  const data = await res.json();

  console.log(`Score: ${data.score}/100 (Grade: ${data.grade})`);
  console.log(`Passed: ${data.summary.passed} | Warnings: ${data.summary.warnings} | Failed: ${data.summary.failed}`);

  // Log any failing checks
  data.checks
    .filter(c => c.status === 'fail')
    .forEach(c => console.log(`  FAIL: ${c.message}`));

  return data;
};

auditUrl('https://example.com', 'seo_your_key_here');

# Python 3 with requests
import requests

def audit_url(url, api_key=None):
    endpoint = "https://seopeek.web.app/api/v1/audit"
    headers = {"x-api-key": api_key} if api_key else {}
    params = {"url": url}

    resp = requests.get(endpoint, headers=headers, params=params)
    resp.raise_for_status()
    data = resp.json()

    print(f"Score: {data['score']}/100 (Grade: {data['grade']})")
    print(f"Passed: {data['summary']['passed']} | "
          f"Warnings: {data['summary']['warnings']} | "
          f"Failed: {data['summary']['failed']}")

    # Show failing checks
    for check in data["checks"]:
        if check["status"] == "fail":
            print(f"  FAIL: {check['message']}")

    return data

result = audit_url("https://example.com", api_key="seo_your_key_here")

Pricing Tiers

Rate Limits

Limits reset daily at midnight UTC and monthly on the 1st. When you exceed a limit, the API returns a 429 status code.

Error Codes

All error responses return JSON with an error field:

{
  "error": "Missing required parameter: url",
  "example": "/api/v1/audit?url=https://example.com"
}