Documentation

Reference for Agents, MCP & API

Run AI SEO reports from your website, REST API, or MCP, with one key for everything on any paid plan.

New here? The developer overview walks through the access model before you reach the endpoint reference. Read the SEO report API overview

Authentication

All requests require a Bearer token. API keys are available on paid plans; create one in your account settings. Each new site uses one of your plan's credits, which reset on the first day of each month (UTC) and never roll over.

Header· http

Authorization: Bearer sr__live_your_api_key

Example Request

curl· bash

curl -X POST https://seoreport.dev/api/v1/reports \
  -H "Authorization: Bearer sr__live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com"}'

REST API Endpoints

Base URL: https://seoreport.dev

POST/api/v1/reportsCreate a new report or reuse an existing one. Add "forceRerun": true to scan the site again instead.

GET/api/v1/reports/:idGet report status and sections.

GET/api/v1/reports/:id/resultRead the full result payload.

GET/api/v1/reports/:id/download?format=pdf|md|txt|jsonDownload the rendered report as PDF, Markdown, text, or JSON.

PUT/api/v1/monitorsStarts weekly monitoring for a domain; "enabled": false pauses it.

GET/api/v1/monitorsLists the domains this account monitors.

DELETE/api/v1/monitors?url=Stops monitoring a domain and deletes its stored results.

Example Response

response.json· json

{
  "success": true,
  "report": {
    "jobId": "3f6c2a1e-8d4b-4c7a-9e21-5b0d7f4a6c18",
    "status": "completed",
    "targetUrl": "https://example.com"
  },
  "pollAfterMs": 0
}

Reading the Result

When report.status is completed, the result endpoint returns the whole report. The findings are in the report.view.sections entry whose key is full_findings, under detail.findings. Text fields are written in the report's language.

result.json· json

{
  "success": true,
  "report": {
    "jobId": "3f6c2a1e-8d4b-4c7a-9e21-5b0d7f4a6c18",
    "status": "completed",
    "targetUrl": "https://www.example.com/",
    "auditedAt": "2026-10-11T09:14:03.000Z",
    "score": { "overall": 72 },
    "view": {
      "sections": [
        {
          "key": "full_findings",
          "state": "ready",
          "detail": {
            "findings": [
              {
                "status": "fail",
                "areaLabel": "URL signals",
                "title": "Canonical tag missing",
                "whyItMatters": "Canonical tags tell search engines which version of a page should appear in results.",
                "fix": "Add a canonical link element or Link HTTP header pointing to the preferred URL for this page."
              }
            ]
          }
        }
      ]
    }
  }
}

report.targetUrl: The address that was audited. A redirect within the same domain is followed, so it can differ from the URL you sent.
report.auditedAt: When the audit ran, as an ISO 8601 timestamp.
report.score.overall: The overall score, from 0 to 100.
report.view.sections[].state: Whether the section's content is available. Its detail is null until the state is ready.
findings[].status: The finding's result: fail, warn, pass, info.
findings[].areaLabel: The part of the site the finding concerns.
findings[].title: The finding, in one line.
findings[].whyItMatters: Why the finding matters for search and AI visibility.
findings[].fix: What to change. Filled in for failing and warning findings, empty for the others.

The result carries more fields than these. Build on the fields listed here; the others are not documented and may change.