SEO Report API for
Developers and AI Agents

export SEOREPORT_API_KEY="sr__live_your_api_key"
# Send the key as a header file so it never sits in curl's argv, where ps shows
# it to every local user. printf is a shell builtin, so it spawns no process.
auth() { printf 'Authorization: Bearer %s\n' "$SEOREPORT_API_KEY"; }

# 1. Create a report and keep its job ID
JOB_ID=$(curl -s -X POST https://seoreport.dev/api/v1/reports \
  -H @<(auth) \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com"}' | jq -r '.report.jobId')

# 2. Poll until the report is no longer queued or running
while :; do
  STATUS=$(curl -s "https://seoreport.dev/api/v1/reports/$JOB_ID" \
    -H @<(auth) | jq -r '.report.status')
  case "$STATUS" in queued|running) sleep 3 ;; *) break ;; esac
done
echo "status: $STATUS"

# 3. Export the finished report (format=pdf, md and txt also work)
curl -s "https://seoreport.dev/api/v1/reports/$JOB_ID/download?format=json" \
  -H @<(auth) -o report.json

{
  "exportVersion": 1,
  "jobId": "3f6c2a1e-8d4b-4c7a-9e21-5b0d7f4a6c18",
  "targetUrl": "https://example.com",
  "status": "completed",
  "isSnapshotReady": true,
  "auditedAt": "2026-10-14T09:12:41.000Z",
  "locale": "en",
  "score": { "overall": 72, "band": "stable" },
  "areas": [
    { "id": "access_crawl", "name": "Crawl & Index", "score": 61 },
    { "id": "metadata_onpage", "name": "On-Page SEO", "score": 78 },
    { "id": "security", "name": "Security", "score": 84 }
  ],
  "pagesAnalyzed": 24,
  "openIssues": { "critical": 0, "high": 2, "medium": 5, "low": 3, "total": 10 },
  "findings": [
    {
      "rank": 1,
      "title": "Render parity mismatch",
      "status": "fail",
      "severity": "high",
      "area": { "id": "access_crawl", "name": "Crawl & Index" },
      "whyItMatters": "Raw HTML and rendered DOM should tell the same SEO story so crawlers and AI systems do not see conflicting versions of the page.",
      "fix": "Ensure raw HTML and rendered DOM contain the same critical SEO elements (title, H1, canonical, meta description, structured data). If content is injected by JavaScript, move it to server-side rendering so crawlers see it immediately.",
      "verification": [
        "Recheck these recorded examples: https://example.com/pricing. Method: compare the raw HTML with the rendered DOM. Previously observed: H1 present only after rendering",
        "Expected after the change: the same critical elements in both. Obtain a fresh capture and compare the same check and URLs; a changed sample alone does not verify a fix."
      ],
      "evidence": ["Raw HTML and rendered DOM were compared for critical elements."],
      "pages": ["https://example.com/pricing"]
    }
  ]
}

# Uses the auth() helper from the quickstart above.
# Re-audit a domain every week and email [email protected] when it changes
curl -X PUT https://seoreport.dev/api/v1/monitors \
  -H @<(auth) \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com", "alertEmail": "[email protected]"}'

# List monitored domains
curl https://seoreport.dev/api/v1/monitors \
  -H @<(auth)

# Stop monitoring (pass the host the list returns)
curl -X DELETE "https://seoreport.dev/api/v1/monitors?url=example.com" \
  -H @<(auth)

{
  "mcpServers": {
    "seoreport": {
      "url": "https://seoreport.dev/mcp",
      "headers": {
        "Authorization": "Bearer sr__live_your_api_key"
      }
    }
  }
}