SEOIQ API & MCP
Run SEO, answer-engine (AEO) and generative-engine (GEO) audits and competitor analyses from your own code or your AI assistant. Read full reports, every finding and the ready-made fixes, so an AI can make the changes for you.
Getting accessAuthenticationCredits & limits How it worksEndpointsErrorsMCP for AI assistantsOpenAPI
Getting access
- Create a SEOIQ account (or log in).
- Open the API page in your account and click Request API access. Tell us briefly what you'll use it for.
- We review each request and email you when it's approved.
- Create an API key on the same page. It is shown once, so copy it somewhere safe.
Authentication
Send your key as a bearer token on every request:
Authorization: Bearer seoiq_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- Keep keys secret: anyone with a key can spend your credits. Never put one in a public repository or in browser code.
- Rotate a key on the API page to get a new one. The old key stops at once, or after 24 hours or 7 days so you can update your systems.
- Revoke a key to stop it immediately. You can have up to 5 active keys.
Credits & limits
- The API uses your account's credits at the same prices as the website: a full scan is 10 credits, single sections cost less, a competitor analysis is 20 credits and a competitor suggestion 2 credits. See pricing;
GET /mereturns current prices. - Free accounts can scan Technical SEO, Core Web Vitals and Accessibility. The other sections and competitor analysis need a paid account (any credit pack).
- Competitor analyses and suggestions that fail on our side refund their credits automatically. If a scan fails, email us.
- Rate limit: 60 requests a minute per key. Only one scan of the same site runs at a time; starting another returns the one already running.
How it works
Scans take about 3–10 minutes and competitor analyses 4–8 minutes, so they run in the background:
- Start one:
POST /scansreturns ascan_id. - Poll
GET /scans/{id}every 20–30 seconds untilstatusiscompleted(orfailed). - Read the results:
/scans/{id}/report(Markdown) or/scans/{id}/findings(JSON).
# 1. Start a full scan
curl -X POST https://www.seoiq.co.uk/api/v1/scans \
-H "Authorization: Bearer $SEOIQ_KEY" -H "Content-Type: application/json" \
-d '{"url": "https://example.co.uk"}'
# → {"scan_id": 512, "status": "pending", "sections": "full", "credits_charged": 10, ...}
# 2. Check progress
curl https://www.seoiq.co.uk/api/v1/scans/512 -H "Authorization: Bearer $SEOIQ_KEY"
# 3. Get the full report (Markdown) or the findings with fixes (JSON)
curl https://www.seoiq.co.uk/api/v1/scans/512/report -H "Authorization: Bearer $SEOIQ_KEY"
curl "https://www.seoiq.co.uk/api/v1/scans/512/findings?severity=critical" -H "Authorization: Bearer $SEOIQ_KEY"
To scan only some sections, pass their keys:
{"url": "example.co.uk", "sections": ["technical", "performance"]}
| Section key | Section |
|---|---|
technical | Technical SEO |
onpage | Content & On-Page |
content_quality | Content Quality & E-E-A-T |
aeo | Answer-Engine (AEO) |
geo | GEO / Local Presence |
ai | Generative-Engine Readiness |
performance | Core Web Vitals |
accessibility | Accessibility |
A finding with a ready-made fix
{
"section": "aeo",
"section_name": "Answer-Engine (AEO)",
"severity": "high",
"title": "No Organization node anywhere on the site",
"detail": "No node tells answer engines who the business is…",
"recommendation": "Add the Organization block below to the site-wide header…",
"evidence": "jsonld types found: WebSite",
"fixable": true,
"fix": {
"type": "schema",
"how": "Structured data (JSON-LD): add inside the <head> of the target page",
"target": "https://example.co.uk/",
"content": "<script type=\"application/ld+json\">{…}</script>"
}
}
Endpoints
Base URL: https://www.seoiq.co.uk/api/v1. Responses are JSON unless noted.
| Method | Path | What it does |
|---|---|---|
| GET | /me | Your account: credit balance, free or paid tier, whether competitor analysis is available, and prices. |
| GET | /sites | Websites you have scanned, each with its latest scan. |
| GET | /scans | Your scans, newest first. Query: site, status, page. |
| POST | /scans | Start a scan. Body: url, optional sections. Spends credits. |
| GET | /scans/{id} | Status, progress, overall score, and each section's score and summary. |
| GET | /scans/{id}/findings | Every finding as JSON with recommendation, evidence and ready-made fix content. Query: severity, section. |
| GET | /scans/{id}/report | The full report as Markdown, ideal to hand to an AI assistant. |
| GET | /competitors | Your competitor analyses. |
| POST | /competitors | Start a competitor analysis (paid accounts). Body: url, optional keywords, location, competitors, auto_discover, client_type. |
| GET | /competitors/{id} | Analysis status and results: leaderboard, gaps, actions, keyword targeting. |
| GET | /competitors/{id}/report | The full competitor report as Markdown. |
| POST | /competitors/suggest | AI suggestion of keywords, location and competitors for a site (paid accounts). |
| GET | /competitors/suggest/{id} | The suggestion's status and result. |
Competitor analysis
curl -X POST https://www.seoiq.co.uk/api/v1/competitors \
-H "Authorization: Bearer $SEOIQ_KEY" -H "Content-Type: application/json" \
-d '{"url": "example.co.uk", "location": "Leeds, UK",
"keywords": ["house clearance leeds"], "competitors": ["rival-one.co.uk"]}'
Leave out keywords, location and competitors and SEOIQ works them out from the site. Set client_type to platform for directories and marketplaces so they're compared with other platforms rather than with the businesses they list.
Errors
Errors return JSON: {"error": "message"}.
| Status | Meaning |
|---|---|
| 401 | Missing, invalid, expired or revoked API key. |
| 402 | Not enough credits. Top up. |
| 403 | API access not approved (or revoked), or the feature needs a paid account. |
| 404 | Not found, or it belongs to another account. |
| 409 | Not ready yet (the scan is still running or failed), or someone else is scanning that site right now. |
| 422 | Invalid input; the message says what to fix. |
| 429 | Rate limit or too many analyses running at once. |
MCP for AI assistants
SEOIQ is also a Model Context Protocol server, so AI assistants can run audits and read reports and fixes directly, then apply the fixes in your codebase or CMS. Use the same API key.
Server URL: https://www.seoiq.co.uk/mcp (Streamable HTTP, bearer-token auth).
Claude Code
claude mcp add --transport http seoiq https://www.seoiq.co.uk/mcp \
--header "Authorization: Bearer seoiq_your_key"
Cursor (~/.cursor/mcp.json)
{
"mcpServers": {
"seoiq": {
"url": "https://www.seoiq.co.uk/mcp",
"headers": { "Authorization": "Bearer seoiq_your_key" }
}
}
}
VS Code (.vscode/mcp.json)
{
"servers": {
"seoiq": {
"type": "http",
"url": "https://www.seoiq.co.uk/mcp",
"headers": { "Authorization": "Bearer seoiq_your_key" }
}
}
}
Claude Desktop and other stdio-only clients
Use the mcp-remote bridge (needs Node.js). In claude_desktop_config.json:
{
"mcpServers": {
"seoiq": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://www.seoiq.co.uk/mcp", "--header", "Authorization:${SEOIQ_AUTH}"],
"env": { "SEOIQ_AUTH": "Bearer seoiq_your_key" }
}
}
}
Code Mode (beta)
A second MCP server built on Cloudflare Code Mode. Instead of one tool per action, your assistant gets two tools: search to explore this API's OpenAPI spec, and execute to write a short JavaScript function that calls the API as many times as it needs and returns only the answer. Multi-step jobs, such as "list my sites and give me every critical finding with its fix", take one step and use far fewer tokens.
Server URL: https://mcp.seoiq.co.uk/mcp (Streamable HTTP, same API key). The code runs in a Cloudflare sandbox with no internet access: it can only call the SEOIQ API, your key is added outside the sandbox, and every call follows the same rules, credits and rate limits as the REST API. Scans still take minutes, so the assistant should start one and check back rather than wait inside one execution.
claude mcp add --transport http seoiq-code https://mcp.seoiq.co.uk/mcp \
--header "Authorization: Bearer seoiq_your_key"
For Cursor, VS Code or Claude Desktop, use the same configuration as above with this URL. Code Mode is built on an experimental Cloudflare feature and may change.
Try asking your assistant: "Scan example.co.uk with SEOIQ, then apply every critical and high fix to this site." Tools that spend credits are labelled so your assistant asks you first.
Tools
| Tool | What it does |
|---|---|
get_account | Credit balance, account tier (free/paid), whether competitor analysis is available, and credit prices for scans and analyses. |
list_sites | Websites this account has scanned, with each one's latest scan. |
list_scans | This account's scans, newest first. Filter by site (URL or name fragment) and status. |
start_scan | Start an SEO / AEO / GEO audit of a website. SPENDS CREDITS (see get_account; full scan or chosen sections). Runs in the background for ~3-10 minutes: poll get_scan with the returned scan_id. Sections: technical, onpage, content_quality, aeo, geo, ai, performance, accessibility (omit for a full scan). Free accounts run technical, performance and accessibility only. |
get_scan | Status, progress, overall score and per-section scores and summaries of a scan. |
get_scan_report | The complete audit report as Markdown: summary, scores, live Google presence, and every finding with its recommendation, evidence and ready-made fix content. Best single source for implementing the fixes. |
get_findings | Every finding of a completed scan as structured data, including fix content (type, target, exact content) for fixable ones. Filter by severity or section key. |
list_competitor_analyses | This account's competitor analyses, newest first. |
start_competitor_analysis | Compare a website with its search competitors (live Google rankings, map pack, reviews, AI-answer citations, site crawls) and get a plan to outrank them. PAID ACCOUNTS ONLY, SPENDS CREDITS. Runs ~4-8 minutes: poll get_competitor_analysis. |
get_competitor_analysis | Status, progress and (when completed) leaderboard, gaps, actions and keyword targeting of a competitor analysis. |
get_competitor_report | The complete competitor analysis report as Markdown. |
suggest_competitors | Quick AI read of a website that proposes target keywords, its market location and competitor websites (input for start_competitor_analysis). PAID ACCOUNTS ONLY, SPENDS A FEW CREDITS. Takes 1-3 minutes: poll get_competitor_suggestion. |
get_competitor_suggestion | Status and result of suggest_competitors. |
OpenAPI
The full machine-readable spec is at https://www.seoiq.co.uk/api/v1/openapi.json. Import it into Postman, Insomnia or a code generator, or into a ChatGPT custom GPT as an Action (authentication: API key, Bearer).
Without an API key
Every report can also be shared as a link from the app. Add .md to a share link to get the plain Markdown version that any AI assistant can read.
Questions? Email hello@seoiq.co.uk. Use of the API is covered by our terms.