REST API + MCP server

SEO Report API for
Developers and AI Agents

Create reports over REST, poll them to completion, and read the same saved report your team sees on the website. The same API key from your paid plan connects any MCP-capable agent.

Access model

Paid plan + API key

API access is account-linked and key-gated. Choose a plan, create an API key in your account, and every new site you run through the API uses your plan's credits, exactly as it would on the website. Credits reset on the first day of each month (UTC) and never roll over.

One report object

Website sessions, API calls, and agent sessions read from the same saved report state.

Straightforward flow

Create a report, poll for status, then read the full results from the same object.

See pricing

Available endpoints

POST/api/v1/reports/preview

Create a score preview for partner integrations on a paid plan.

POST/api/v1/reports

Create a new report or reuse one that already exists. Add "forceRerun": true to scan the site again instead.

GET/api/v1/reports/:id

Get the latest report status and sections.

GET/api/v1/reports/:id/result

Read the full report results.

GET/api/v1/reports/:id/download?format=json

Export the report payload as JSON for programmatic integrations.

Quickstart: an SEO report from curl

Three requests cover the whole flow, using an API key from your paid plan. The first creates the report, the second polls it until its status is no longer queued or running, and the third exports it. A new site uses one credit; running a site you already have a report for again does not use a credit.

Create, poll and export a reportBash
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

SEO monitoring API

A domain registered for monitoring is re-audited every week. When something changes, the alert address receives an email: a new critical or high-severity finding, a resolved critical finding, or a move to a different score band. A week without a change sends nothing.

PUT/api/v1/monitors

Starts weekly monitoring for a domain; "enabled": false pauses it.

GET/api/v1/monitors

Lists the domains this account monitors.

DELETE/api/v1/monitors?url=

Stops monitoring a domain and deletes its stored results.

Monitor a domainBash
# 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)

Monitoring is included with paid plans and does not spend report credits.

See pricing

Official TypeScript Client

A typed client for the REST API. Authenticate with your plan's API key, then create, poll and export reports from TypeScript.

See launch platform integrationView docs

Command Line

Run reports from your terminal with your API key. One global install.

Bash
npm install -g @seoreport/client
Get your API key

MCP server — same API, same key

Point any MCP-capable client at https://seoreport.dev/mcp and authenticate with the same Bearer API key you use for REST. The report and account tools are advertised on connect, so an agent can run an audit and read the findings without any glue code.

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

Start a report for a URL and get a job ID back.

get_report_status

Poll a job until the report is ready.

get_report

Read the finished report with its score and findings.

list_reports

List the reports on the account.

get_report_download

Get a download URL for JSON, Markdown, text, or PDF.

get_usage

Check remaining credits and the current billing period.

Checkout, cancellation, and account deletion return a browser confirmation URL instead of acting directly. An agent can start them; only a person can finish them.

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

Ready to build?

Choose a plan, create an API key, and start integrating SEO reports into your product.

Get your API keyView pricing