{ "openapi": "3.0.3", "info": { "title": "SiteVerdict API", "version": "1.1.1", "description": "One API behind every SiteVerdict storefront (RapidAPI, Zapier/Make/n8n, Google Sheets, Shopify, WordPress, agency reports, MCP).\n\n**Auth**: `X-API-Key: sv_live_...` (or `Authorization: Bearer`). `sv_test_...` keys return clearly-labelled sample data, cost nothing and never touch the network.\n\n**Results** share one shape: `score` (0-100, null where not applicable), `grade` (A-F), `summary`, `findings[]` ({id, severity, title, detail, fix}) ordered by severity, and tool-specific `data`.\n\n**Credits**: 1 per scan (privacy-policy 2, full-audit 5), charged only when a result is returned; failed, blocked and timed-out scans are free. Identical scans within 10 minutes may be served from cache (`cached: true`; pass `fresh: true` to force a new scan).\n\n**Fair use**: only public websites (private/internal addresses are refused); robots.txt is respected for the token `SiteVerdictBot`; User-Agent `SiteVerdictBot/1.0 (+https://tools.webrevenuescan.com/bot)`; bot protection, logins and paywalls are never bypassed.\n\nResults are automated technical checks, not legal advice. Operated by BharatFare Travel and Technologies Ltd (UK). Contact: aman.thakran@bharatfare.com." }, "servers": [ { "url": "https://api.webrevenuescan.com" } ], "paths": { "/v1/tools": { "get": { "operationId": "listTools", "summary": "List tools", "description": "All scan tools with their input JSON Schema and credit price. No authentication required.", "tags": [ "Meta" ], "responses": { "200": { "description": "Tools" } } } }, "/v1/scan/tech-stack": { "post": { "operationId": "scanTechStack", "summary": "Tech stack detector", "description": "Detects the CMS, e-commerce platform, analytics, advertising pixels, CDN, hosting, JavaScript frameworks, email provider and DNS provider of a website (900+ signatures), with versions and confidence. HTTP mode, fast.\n\nCost: **1 credit** (charged only on success). Typical time: ~3 s. If the scan is not finished after the sync timeout (default 55 s, or `timeout_secs`), the API answers **202** with a `job_id` and the scan continues as an async job.", "tags": [ "Scans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Public page URL (https:// is added if missing).", "example": "https://example.com" }, "check_dns": { "type": "boolean", "default": true, "description": "Look up MX/NS/SPF/DMARC to detect email + DNS providers." }, "check_tls": { "type": "boolean", "default": true, "description": "Read the TLS certificate issuer/expiry." }, "min_confidence": { "type": "integer", "minimum": 0, "maximum": 100, "default": 50, "description": "Drop detections below this confidence." }, "include_evidence": { "type": "boolean", "default": false, "description": "Include the matched evidence strings per technology." }, "fresh": { "type": "boolean", "default": false, "description": "Bypass the short-lived result cache." }, "timeout_secs": { "type": "integer", "minimum": 1, "maximum": 60, "description": "How long to wait synchronously before the scan continues as an async job (default and max 55-60)." }, "webhook_url": { "type": "string", "format": "uri", "description": "Called (signed) when a scan that fell back to an async job finishes." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com" } } } }, "responses": { "200": { "description": "Scan result" }, "202": { "description": "Still running: continues as an async job (poll GET /v1/jobs/{job_id} or use webhook_url)." }, "400": { "description": "Invalid request or URL not allowed (private/internal address, bad port)." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Not enough credits." }, "409": { "description": "Idempotency-Key conflict." }, "422": { "description": "The target could not be scanned (unreachable, the page returned an HTTP 4xx/5xx error [target_http_error, details.status + details.final_url], blocked by bot protection, robots.txt disallows SiteVerdictBot). Not charged." }, "429": { "description": "Rate limit or concurrency limit exceeded." }, "503": { "description": "Server busy (memory/queue protection). Retry later." }, "504": { "description": "Scan exceeded its time budget. Not charged." } } } }, "/v1/scan/consent-tracking": { "post": { "operationId": "scanConsentTracking", "summary": "Tracking & cookie-consent audit (GDPR / PECR / Consent Mode v2)", "description": "Loads the site in a real browser (no click, \"Reject all\", \"Accept all\") and reports tags that fire before consent or after Reject, tracking cookies set without consent, Google Consent Mode v2 signals, the consent banner (CMP) and broken GA4/GTM tags. \"quick\" = one visit (pre-consent only).\n\nCost: **1 credit** (charged only on success). Typical time: ~50 s. If the scan is not finished after the sync timeout (default 55 s, or `timeout_secs`), the API answers **202** with a `job_id` and the scan continues as an async job.", "tags": [ "Scans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Public page URL (https:// is added if missing).", "example": "https://example.com" }, "scan_mode": { "type": "string", "enum": [ "full", "quick" ], "default": "full", "description": "\"full\" = 3 visits (no click / Reject / Accept). \"quick\" = 1 visit." }, "internal_pages": { "type": "integer", "minimum": 0, "maximum": 3, "default": 0, "description": "Extra internal pages checked per scenario." }, "locale": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "default": "en-GB", "description": "Browser language (banners are often localised)." }, "timezone": { "type": "string", "pattern": "^[A-Za-z_]+(/[A-Za-z_+-]+)*$", "default": "Europe/London", "description": "IANA time zone." }, "fresh": { "type": "boolean", "default": false, "description": "Bypass the short-lived result cache." }, "timeout_secs": { "type": "integer", "minimum": 1, "maximum": 60, "description": "How long to wait synchronously before the scan continues as an async job (default and max 55-60)." }, "webhook_url": { "type": "string", "format": "uri", "description": "Called (signed) when a scan that fell back to an async job finishes." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com" } } } }, "responses": { "200": { "description": "Scan result" }, "202": { "description": "Still running: continues as an async job (poll GET /v1/jobs/{job_id} or use webhook_url)." }, "400": { "description": "Invalid request or URL not allowed (private/internal address, bad port)." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Not enough credits." }, "409": { "description": "Idempotency-Key conflict." }, "422": { "description": "The target could not be scanned (unreachable, the page returned an HTTP 4xx/5xx error [target_http_error, details.status + details.final_url], blocked by bot protection, robots.txt disallows SiteVerdictBot). Not charged." }, "429": { "description": "Rate limit or concurrency limit exceeded." }, "503": { "description": "Server busy (memory/queue protection). Retry later." }, "504": { "description": "Scan exceeded its time budget. Not charged." } } } }, "/v1/scan/speed": { "post": { "operationId": "scanSpeed", "summary": "Speed, UX & revenue scanner (Core Web Vitals)", "description": "Measures lab Core Web Vitals (LCP, CLS, TBT/INP proxy, TTFB, FCP) on mobile (throttled 4G) and desktop in a real browser, finds bottlenecks (images, render-blocking and third-party scripts), dead clicks and small tap targets, and estimates revenue lost to slowness when traffic and order value are given. On-page SEO and broken-link findings come from seo-basics (raw SEO/link data is still under data.seo / data.links).\n\nCost: **1 credit** (charged only on success). Typical time: ~35 s. If the scan is not finished after the sync timeout (default 55 s, or `timeout_secs`), the API answers **202** with a `job_id` and the scan continues as an async job.", "tags": [ "Scans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Public page URL (https:// is added if missing).", "example": "https://example.com" }, "devices": { "type": "string", "enum": [ "both", "mobile", "desktop" ], "default": "both" }, "throttling": { "type": "string", "enum": [ "fast-4g", "slow-4g", "none" ], "default": "fast-4g", "description": "Mobile network/CPU throttling profile." }, "broken_link_sample": { "type": "integer", "minimum": 0, "maximum": 30, "default": 10, "description": "Internal links to check for 4xx/5xx (0 = skip)." }, "monthly_visitors": { "type": "number", "minimum": 0, "maximum": 1000000000, "description": "Optional, for the revenue estimate." }, "conversion_rate_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "average_order_value": { "type": "number", "minimum": 0, "maximum": 1000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "GBP" }, "fresh": { "type": "boolean", "default": false, "description": "Bypass the short-lived result cache." }, "timeout_secs": { "type": "integer", "minimum": 1, "maximum": 60, "description": "How long to wait synchronously before the scan continues as an async job (default and max 55-60)." }, "webhook_url": { "type": "string", "format": "uri", "description": "Called (signed) when a scan that fell back to an async job finishes." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com" } } } }, "responses": { "200": { "description": "Scan result" }, "202": { "description": "Still running: continues as an async job (poll GET /v1/jobs/{job_id} or use webhook_url)." }, "400": { "description": "Invalid request or URL not allowed (private/internal address, bad port)." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Not enough credits." }, "409": { "description": "Idempotency-Key conflict." }, "422": { "description": "The target could not be scanned (unreachable, the page returned an HTTP 4xx/5xx error [target_http_error, details.status + details.final_url], blocked by bot protection, robots.txt disallows SiteVerdictBot). Not charged." }, "429": { "description": "Rate limit or concurrency limit exceeded." }, "503": { "description": "Server busy (memory/queue protection). Retry later." }, "504": { "description": "Scan exceeded its time budget. Not charged." } } } }, "/v1/scan/accessibility": { "post": { "operationId": "scanAccessibility", "summary": "Accessibility audit (WCAG 2.2 / European Accessibility Act)", "description": "Runs axe-core WCAG 2.2 A/AA/AAA checks plus keyboard, focus, reflow (320 px), motion and target-size tests on desktop and mobile in a real browser. Issues are mapped to WCAG success criteria and EN 301 549 / European Accessibility Act relevance, with code-level fixes. Automated testing finds only part of WCAG failures.\n\nCost: **1 credit** (charged only on success). Typical time: ~30 s. If the scan is not finished after the sync timeout (default 55 s, or `timeout_secs`), the API answers **202** with a `job_id` and the scan continues as an async job.", "tags": [ "Scans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Public page URL (https:// is added if missing).", "example": "https://example.com" }, "devices": { "type": "array", "items": { "type": "string", "enum": [ "desktop", "mobile" ] }, "default": [ "desktop", "mobile" ] }, "wcag_level": { "type": "string", "enum": [ "A", "AA", "AAA" ], "default": "AA" }, "include_best_practices": { "type": "boolean", "default": true }, "include_needs_review": { "type": "boolean", "default": true, "description": "Include items that need a human decision (severity \"info\")." }, "max_nodes_per_rule": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "fresh": { "type": "boolean", "default": false, "description": "Bypass the short-lived result cache." }, "timeout_secs": { "type": "integer", "minimum": 1, "maximum": 60, "description": "How long to wait synchronously before the scan continues as an async job (default and max 55-60)." }, "webhook_url": { "type": "string", "format": "uri", "description": "Called (signed) when a scan that fell back to an async job finishes." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com" } } } }, "responses": { "200": { "description": "Scan result" }, "202": { "description": "Still running: continues as an async job (poll GET /v1/jobs/{job_id} or use webhook_url)." }, "400": { "description": "Invalid request or URL not allowed (private/internal address, bad port)." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Not enough credits." }, "409": { "description": "Idempotency-Key conflict." }, "422": { "description": "The target could not be scanned (unreachable, the page returned an HTTP 4xx/5xx error [target_http_error, details.status + details.final_url], blocked by bot protection, robots.txt disallows SiteVerdictBot). Not charged." }, "429": { "description": "Rate limit or concurrency limit exceeded." }, "503": { "description": "Server busy (memory/queue protection). Retry later." }, "504": { "description": "Scan exceeded its time budget. Not charged." } } } }, "/v1/scan/ai-readiness": { "post": { "operationId": "scanAiReadiness", "summary": "AI-search readiness (ChatGPT, Claude, Perplexity, Google AI Overviews)", "description": "Checks whether AI assistants and AI search engines can find, read and cite a site: robots.txt rules for 30+ AI crawlers (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended...), llms.txt, sitemap, server-rendered text, headings, schema.org JSON-LD, canonical/meta directives and entity/trust signals. Returns a readiness score, a bot matrix and copy-paste fixes (robots.txt, llms.txt, Organization JSON-LD).\n\nCost: **1 credit** (charged only on success). Typical time: ~6 s. If the scan is not finished after the sync timeout (default 55 s, or `timeout_secs`), the API answers **202** with a `job_id` and the scan continues as an async job.", "tags": [ "Scans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Public page URL (https:// is added if missing).", "example": "https://example.com" }, "policy": { "type": "string", "enum": [ "search-only", "allow-all", "block-all" ], "default": "search-only", "description": "Which AI-crawler policy the generated robots.txt snippet should implement." }, "fresh": { "type": "boolean", "default": false, "description": "Bypass the short-lived result cache." }, "timeout_secs": { "type": "integer", "minimum": 1, "maximum": 60, "description": "How long to wait synchronously before the scan continues as an async job (default and max 55-60)." }, "webhook_url": { "type": "string", "format": "uri", "description": "Called (signed) when a scan that fell back to an async job finishes." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com" } } } }, "responses": { "200": { "description": "Scan result" }, "202": { "description": "Still running: continues as an async job (poll GET /v1/jobs/{job_id} or use webhook_url)." }, "400": { "description": "Invalid request or URL not allowed (private/internal address, bad port)." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Not enough credits." }, "409": { "description": "Idempotency-Key conflict." }, "422": { "description": "The target could not be scanned (unreachable, the page returned an HTTP 4xx/5xx error [target_http_error, details.status + details.final_url], blocked by bot protection, robots.txt disallows SiteVerdictBot). Not charged." }, "429": { "description": "Rate limit or concurrency limit exceeded." }, "503": { "description": "Server busy (memory/queue protection). Retry later." }, "504": { "description": "Scan exceeded its time budget. Not charged." } } } }, "/v1/scan/domain-health": { "post": { "operationId": "scanDomainHealth", "summary": "Domain & email health (SPF, DKIM, DMARC, MTA-STS, TLS, DNSSEC)", "description": "Checks a domain's email authentication and deliverability (MX, SPF incl. lookup count, DMARC policy, DKIM on common selectors, MTA-STS, TLS-RPT, BIMI), Gmail/Yahoo bulk-sender readiness, DNS hygiene (DNSSEC, CAA, nameservers) and web security (TLS certificate expiry, HTTPS redirect, HSTS, security headers). Returns exact DNS records to add. Body: {\"domain\": \"example.com\"} (or \"url\").\n\nCost: **1 credit** (charged only on success). Typical time: ~6 s. If the scan is not finished after the sync timeout (default 55 s, or `timeout_secs`), the API answers **202** with a `job_id` and the scan continues as an async job.", "tags": [ "Scans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 253, "description": "Domain to check, e.g. \"example.com\" (an email address or URL is reduced to its domain).", "example": "example.com" }, "url": { "type": "string", "maxLength": 2048, "description": "Alternative to \"domain\": any URL on the domain." }, "dkim_selectors": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,63}$" }, "maxItems": 10, "description": "Extra DKIM selectors to try (60 common ones are always tried)." }, "check_blocklists": { "type": "boolean", "default": false, "description": "Query 3 free DNS blocklists for the MX hosts." }, "check_www": { "type": "boolean", "default": true, "description": "Also check the www. TLS certificate." }, "fresh": { "type": "boolean", "default": false, "description": "Bypass the short-lived result cache." }, "timeout_secs": { "type": "integer", "minimum": 1, "maximum": 60, "description": "How long to wait synchronously before the scan continues as an async job (default and max 55-60)." }, "webhook_url": { "type": "string", "format": "uri", "description": "Called (signed) when a scan that fell back to an async job finishes." } }, "required": [], "additionalProperties": false }, "example": { "domain": "example.com" } } } }, "responses": { "200": { "description": "Scan result" }, "202": { "description": "Still running: continues as an async job (poll GET /v1/jobs/{job_id} or use webhook_url)." }, "400": { "description": "Invalid request or URL not allowed (private/internal address, bad port)." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Not enough credits." }, "409": { "description": "Idempotency-Key conflict." }, "422": { "description": "The target could not be scanned (unreachable, the page returned an HTTP 4xx/5xx error [target_http_error, details.status + details.final_url], blocked by bot protection, robots.txt disallows SiteVerdictBot). Not charged." }, "429": { "description": "Rate limit or concurrency limit exceeded." }, "503": { "description": "Server busy (memory/queue protection). Retry later." }, "504": { "description": "Scan exceeded its time budget. Not charged." } } } }, "/v1/scan/seo-basics": { "post": { "operationId": "scanSeoBasics", "summary": "On-page SEO basics", "description": "Fast HTTP check of on-page SEO essentials: indexability (noindex, robots.txt), HTTP status, HTTPS, title and meta description length, canonical, H1, lang, structured data, Open Graph, image alt coverage, hreflang, XML sitemap and a broken-link sample. No browser (raw HTML, as most crawlers first see it).\n\nCost: **1 credit** (charged only on success). Typical time: ~3 s. If the scan is not finished after the sync timeout (default 55 s, or `timeout_secs`), the API answers **202** with a `job_id` and the scan continues as an async job.", "tags": [ "Scans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Public page URL (https:// is added if missing).", "example": "https://example.com" }, "broken_link_sample": { "type": "integer", "minimum": 0, "maximum": 30, "default": 10, "description": "Internal links to check (0 = skip)." }, "fresh": { "type": "boolean", "default": false, "description": "Bypass the short-lived result cache." }, "timeout_secs": { "type": "integer", "minimum": 1, "maximum": 60, "description": "How long to wait synchronously before the scan continues as an async job (default and max 55-60)." }, "webhook_url": { "type": "string", "format": "uri", "description": "Called (signed) when a scan that fell back to an async job finishes." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com" } } } }, "responses": { "200": { "description": "Scan result" }, "202": { "description": "Still running: continues as an async job (poll GET /v1/jobs/{job_id} or use webhook_url)." }, "400": { "description": "Invalid request or URL not allowed (private/internal address, bad port)." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Not enough credits." }, "409": { "description": "Idempotency-Key conflict." }, "422": { "description": "The target could not be scanned (unreachable, the page returned an HTTP 4xx/5xx error [target_http_error, details.status + details.final_url], blocked by bot protection, robots.txt disallows SiteVerdictBot). Not charged." }, "429": { "description": "Rate limit or concurrency limit exceeded." }, "503": { "description": "Server busy (memory/queue protection). Retry later." }, "504": { "description": "Scan exceeded its time budget. Not charged." } } } }, "/v1/scan/privacy-policy": { "post": { "operationId": "scanPrivacyPolicy", "summary": "Cookie & privacy-policy checker (UK GDPR / PECR / ePrivacy)", "description": "Visits the site three ways (no click, Reject, Accept), inventories every cookie and storage item with purpose and expiry, finds the privacy and cookie policies, checks the privacy notice against UK GDPR Art. 13 elements, and reports cookies or vendors missing from the policy, non-essential cookies before consent or after Reject, and reject-on-first-layer issues. Optional draft cookie policy (Markdown). Heavy: usually completes as an async job.\n\nCost: **2 credits** (charged only on success). Typical time: ~80 s. If the scan is not finished after the sync timeout (default 55 s, or `timeout_secs`), the API answers **202** with a `job_id` and the scan continues as an async job.", "tags": [ "Scans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Public page URL (https:// is added if missing).", "example": "https://example.com" }, "privacy_policy_url": { "type": "string", "format": "uri", "description": "Optional: the privacy policy URL if it cannot be found from the home page." }, "cookie_policy_url": { "type": "string", "format": "uri", "description": "Optional: the cookie policy URL." }, "internal_pages": { "type": "integer", "minimum": 0, "maximum": 2, "default": 0 }, "generate_drafts": { "type": "boolean", "default": false, "description": "Include a DRAFT cookie policy and cookie table (Markdown) built from the observed cookies. Not legal advice." }, "locale": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "default": "en-GB" }, "timezone": { "type": "string", "pattern": "^[A-Za-z_]+(/[A-Za-z_+-]+)*$", "default": "Europe/London" }, "fresh": { "type": "boolean", "default": false, "description": "Bypass the short-lived result cache." }, "timeout_secs": { "type": "integer", "minimum": 1, "maximum": 60, "description": "How long to wait synchronously before the scan continues as an async job (default and max 55-60)." }, "webhook_url": { "type": "string", "format": "uri", "description": "Called (signed) when a scan that fell back to an async job finishes." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com" } } } }, "responses": { "200": { "description": "Scan result" }, "202": { "description": "Still running: continues as an async job (poll GET /v1/jobs/{job_id} or use webhook_url)." }, "400": { "description": "Invalid request or URL not allowed (private/internal address, bad port)." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Not enough credits." }, "409": { "description": "Idempotency-Key conflict." }, "422": { "description": "The target could not be scanned (unreachable, the page returned an HTTP 4xx/5xx error [target_http_error, details.status + details.final_url], blocked by bot protection, robots.txt disallows SiteVerdictBot). Not charged." }, "429": { "description": "Rate limit or concurrency limit exceeded." }, "503": { "description": "Server busy (memory/queue protection). Retry later." }, "504": { "description": "Scan exceeded its time budget. Not charged." } } } }, "/v1/scan/web-to-markdown": { "post": { "operationId": "scanWebToMarkdown", "summary": "Web page to clean Markdown (for LLMs / RAG)", "description": "Fetches one page (robots.txt respected, honest UA, never bypasses paywalls, logins or bot protection), removes navigation, cookie banners and boilerplate (Readability), and returns clean Markdown plus metadata (title, author, dates, canonical, language, JSON-LD), headings, links, word and token counts, and optional RAG chunks. JavaScript-built pages are rendered in a browser when needed (\"auto\").\n\nCost: **1 credit** (charged only on success). Typical time: ~3 s. If the scan is not finished after the sync timeout (default 55 s, or `timeout_secs`), the API answers **202** with a `job_id` and the scan continues as an async job.", "tags": [ "Scans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Public page URL (https:// is added if missing).", "example": "https://example.com" }, "rendering": { "type": "string", "enum": [ "auto", "http", "browser" ], "default": "auto", "description": "\"auto\" renders in a browser only when the HTML looks like a JavaScript app shell." }, "extraction": { "type": "string", "enum": [ "auto", "readability", "main-element", "full-page" ], "default": "auto" }, "include_links": { "type": "boolean", "default": true }, "include_images": { "type": "boolean", "default": false }, "include_text": { "type": "boolean", "default": false, "description": "Also return plain text." }, "chunking": { "type": "boolean", "default": false, "description": "Split into heading-aware chunks for embeddings." }, "chunk_size": { "type": "integer", "minimum": 64, "maximum": 8192, "default": 512, "description": "Approximate tokens per chunk." }, "max_chars": { "type": "integer", "minimum": 1000, "maximum": 2000000, "default": 500000, "description": "Truncate the Markdown in the response to this many characters." }, "fresh": { "type": "boolean", "default": false, "description": "Bypass the short-lived result cache." }, "timeout_secs": { "type": "integer", "minimum": 1, "maximum": 60, "description": "How long to wait synchronously before the scan continues as an async job (default and max 55-60)." }, "webhook_url": { "type": "string", "format": "uri", "description": "Called (signed) when a scan that fell back to an async job finishes." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com" } } } }, "responses": { "200": { "description": "Scan result" }, "202": { "description": "Still running: continues as an async job (poll GET /v1/jobs/{job_id} or use webhook_url)." }, "400": { "description": "Invalid request or URL not allowed (private/internal address, bad port)." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Not enough credits." }, "409": { "description": "Idempotency-Key conflict." }, "422": { "description": "The target could not be scanned (unreachable, the page returned an HTTP 4xx/5xx error [target_http_error, details.status + details.final_url], blocked by bot protection, robots.txt disallows SiteVerdictBot). Not charged." }, "429": { "description": "Rate limit or concurrency limit exceeded." }, "503": { "description": "Server busy (memory/queue protection). Retry later." }, "504": { "description": "Scan exceeded its time budget. Not charged." } } } }, "/v1/scan/full-audit": { "post": { "operationId": "scanFullAudit", "summary": "Full website audit (all checks, one prioritised fix list)", "description": "Runs speed (mobile), accessibility (desktop), tracking & consent (quick), SEO basics, AI-search readiness, domain & email health and tech-stack detection, then returns an overall weighted score, per-section scores and one de-duplicated fix list ordered by severity (speed is weighted on performance + UX only; SEO is the seo-basics section). Usually completes as an async job (60-150 s).\n\nCost: **5 credits** (charged only on success). Typical time: ~90 s. If the scan is not finished after the sync timeout (default 55 s, or `timeout_secs`), the API answers **202** with a `job_id` and the scan continues as an async job.", "tags": [ "Scans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Public page URL (https:// is added if missing).", "example": "https://example.com" }, "sections": { "type": "array", "items": { "type": "string", "enum": [ "speed", "accessibility", "consent-tracking", "seo-basics", "ai-readiness", "domain-health", "tech-stack" ] }, "default": [ "speed", "accessibility", "consent-tracking", "seo-basics", "ai-readiness", "domain-health", "tech-stack" ], "description": "Subset of sections to run." }, "max_findings": { "type": "integer", "minimum": 5, "maximum": 200, "default": 40 }, "fresh": { "type": "boolean", "default": false, "description": "Bypass the short-lived result cache." }, "timeout_secs": { "type": "integer", "minimum": 1, "maximum": 60, "description": "How long to wait synchronously before the scan continues as an async job (default and max 55-60)." }, "webhook_url": { "type": "string", "format": "uri", "description": "Called (signed) when a scan that fell back to an async job finishes." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com" } } } }, "responses": { "200": { "description": "Scan result" }, "202": { "description": "Still running: continues as an async job (poll GET /v1/jobs/{job_id} or use webhook_url)." }, "400": { "description": "Invalid request or URL not allowed (private/internal address, bad port)." }, "401": { "description": "Missing or invalid API key." }, "402": { "description": "Not enough credits." }, "409": { "description": "Idempotency-Key conflict." }, "422": { "description": "The target could not be scanned (unreachable, the page returned an HTTP 4xx/5xx error [target_http_error, details.status + details.final_url], blocked by bot protection, robots.txt disallows SiteVerdictBot). Not charged." }, "429": { "description": "Rate limit or concurrency limit exceeded." }, "503": { "description": "Server busy (memory/queue protection). Retry later." }, "504": { "description": "Scan exceeded its time budget. Not charged." } } } }, "/v1/jobs/tech-stack": { "post": { "operationId": "createJobTechStack", "summary": "Async job: Tech stack detector", "description": "Queues a scan and returns 202 with a `job_id` immediately. Send `url` (or `domain`) for one target, or `urls` (array, max 50 by default) for a batch; credits are reserved per URL and charged only for URLs that succeed. Optional `webhook_url` receives a signed POST when the job finishes (header `X-SiteVerdict-Signature: t=,v1=.\")>`). Body fields are otherwise the same as POST /v1/scan/{tool}.", "tags": [ "Jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "domain": { "type": "string", "description": "domain-health only" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Batch of targets (URLs, or domains for domain-health)." }, "webhook_url": { "type": "string", "format": "uri" }, "fresh": { "type": "boolean" } }, "additionalProperties": true, "description": "Plus the options of tech-stack: check_dns, check_tls, min_confidence, include_evidence (see POST /v1/scan/tech-stack)." }, "example": { "urls": [ "https://example.com", "https://example.org" ], "webhook_url": "https://hooks.example.net/siteverdict" } } } }, "responses": { "202": { "description": "Job accepted" }, "400": { "description": "Invalid request." }, "401": { "description": "Unauthorized." }, "402": { "description": "Not enough credits for all URLs in the batch." }, "429": { "description": "Rate limited." }, "503": { "description": "Job queue full." } } } }, "/v1/jobs/consent-tracking": { "post": { "operationId": "createJobConsentTracking", "summary": "Async job: Tracking & cookie-consent audit (GDPR / PECR / Consent Mode v2)", "description": "Queues a scan and returns 202 with a `job_id` immediately. Send `url` (or `domain`) for one target, or `urls` (array, max 50 by default) for a batch; credits are reserved per URL and charged only for URLs that succeed. Optional `webhook_url` receives a signed POST when the job finishes (header `X-SiteVerdict-Signature: t=,v1=.\")>`). Body fields are otherwise the same as POST /v1/scan/{tool}.", "tags": [ "Jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "domain": { "type": "string", "description": "domain-health only" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Batch of targets (URLs, or domains for domain-health)." }, "webhook_url": { "type": "string", "format": "uri" }, "fresh": { "type": "boolean" } }, "additionalProperties": true, "description": "Plus the options of consent-tracking: scan_mode, internal_pages, locale, timezone (see POST /v1/scan/consent-tracking)." }, "example": { "urls": [ "https://example.com", "https://example.org" ], "webhook_url": "https://hooks.example.net/siteverdict" } } } }, "responses": { "202": { "description": "Job accepted" }, "400": { "description": "Invalid request." }, "401": { "description": "Unauthorized." }, "402": { "description": "Not enough credits for all URLs in the batch." }, "429": { "description": "Rate limited." }, "503": { "description": "Job queue full." } } } }, "/v1/jobs/speed": { "post": { "operationId": "createJobSpeed", "summary": "Async job: Speed, UX & revenue scanner (Core Web Vitals)", "description": "Queues a scan and returns 202 with a `job_id` immediately. Send `url` (or `domain`) for one target, or `urls` (array, max 50 by default) for a batch; credits are reserved per URL and charged only for URLs that succeed. Optional `webhook_url` receives a signed POST when the job finishes (header `X-SiteVerdict-Signature: t=,v1=.\")>`). Body fields are otherwise the same as POST /v1/scan/{tool}.", "tags": [ "Jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "domain": { "type": "string", "description": "domain-health only" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Batch of targets (URLs, or domains for domain-health)." }, "webhook_url": { "type": "string", "format": "uri" }, "fresh": { "type": "boolean" } }, "additionalProperties": true, "description": "Plus the options of speed: devices, throttling, broken_link_sample, monthly_visitors, conversion_rate_pct, average_order_value, currency (see POST /v1/scan/speed)." }, "example": { "urls": [ "https://example.com", "https://example.org" ], "webhook_url": "https://hooks.example.net/siteverdict" } } } }, "responses": { "202": { "description": "Job accepted" }, "400": { "description": "Invalid request." }, "401": { "description": "Unauthorized." }, "402": { "description": "Not enough credits for all URLs in the batch." }, "429": { "description": "Rate limited." }, "503": { "description": "Job queue full." } } } }, "/v1/jobs/accessibility": { "post": { "operationId": "createJobAccessibility", "summary": "Async job: Accessibility audit (WCAG 2.2 / European Accessibility Act)", "description": "Queues a scan and returns 202 with a `job_id` immediately. Send `url` (or `domain`) for one target, or `urls` (array, max 50 by default) for a batch; credits are reserved per URL and charged only for URLs that succeed. Optional `webhook_url` receives a signed POST when the job finishes (header `X-SiteVerdict-Signature: t=,v1=.\")>`). Body fields are otherwise the same as POST /v1/scan/{tool}.", "tags": [ "Jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "domain": { "type": "string", "description": "domain-health only" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Batch of targets (URLs, or domains for domain-health)." }, "webhook_url": { "type": "string", "format": "uri" }, "fresh": { "type": "boolean" } }, "additionalProperties": true, "description": "Plus the options of accessibility: devices, wcag_level, include_best_practices, include_needs_review, max_nodes_per_rule (see POST /v1/scan/accessibility)." }, "example": { "urls": [ "https://example.com", "https://example.org" ], "webhook_url": "https://hooks.example.net/siteverdict" } } } }, "responses": { "202": { "description": "Job accepted" }, "400": { "description": "Invalid request." }, "401": { "description": "Unauthorized." }, "402": { "description": "Not enough credits for all URLs in the batch." }, "429": { "description": "Rate limited." }, "503": { "description": "Job queue full." } } } }, "/v1/jobs/ai-readiness": { "post": { "operationId": "createJobAiReadiness", "summary": "Async job: AI-search readiness (ChatGPT, Claude, Perplexity, Google AI Overviews)", "description": "Queues a scan and returns 202 with a `job_id` immediately. Send `url` (or `domain`) for one target, or `urls` (array, max 50 by default) for a batch; credits are reserved per URL and charged only for URLs that succeed. Optional `webhook_url` receives a signed POST when the job finishes (header `X-SiteVerdict-Signature: t=,v1=.\")>`). Body fields are otherwise the same as POST /v1/scan/{tool}.", "tags": [ "Jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "domain": { "type": "string", "description": "domain-health only" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Batch of targets (URLs, or domains for domain-health)." }, "webhook_url": { "type": "string", "format": "uri" }, "fresh": { "type": "boolean" } }, "additionalProperties": true, "description": "Plus the options of ai-readiness: policy (see POST /v1/scan/ai-readiness)." }, "example": { "urls": [ "https://example.com", "https://example.org" ], "webhook_url": "https://hooks.example.net/siteverdict" } } } }, "responses": { "202": { "description": "Job accepted" }, "400": { "description": "Invalid request." }, "401": { "description": "Unauthorized." }, "402": { "description": "Not enough credits for all URLs in the batch." }, "429": { "description": "Rate limited." }, "503": { "description": "Job queue full." } } } }, "/v1/jobs/domain-health": { "post": { "operationId": "createJobDomainHealth", "summary": "Async job: Domain & email health (SPF, DKIM, DMARC, MTA-STS, TLS, DNSSEC)", "description": "Queues a scan and returns 202 with a `job_id` immediately. Send `url` (or `domain`) for one target, or `urls` (array, max 50 by default) for a batch; credits are reserved per URL and charged only for URLs that succeed. Optional `webhook_url` receives a signed POST when the job finishes (header `X-SiteVerdict-Signature: t=,v1=.\")>`). Body fields are otherwise the same as POST /v1/scan/{tool}.", "tags": [ "Jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "domain": { "type": "string", "description": "domain-health only" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Batch of targets (URLs, or domains for domain-health)." }, "webhook_url": { "type": "string", "format": "uri" }, "fresh": { "type": "boolean" } }, "additionalProperties": true, "description": "Plus the options of domain-health: dkim_selectors, check_blocklists, check_www (see POST /v1/scan/domain-health)." }, "example": { "urls": [ "https://example.com", "https://example.org" ], "webhook_url": "https://hooks.example.net/siteverdict" } } } }, "responses": { "202": { "description": "Job accepted" }, "400": { "description": "Invalid request." }, "401": { "description": "Unauthorized." }, "402": { "description": "Not enough credits for all URLs in the batch." }, "429": { "description": "Rate limited." }, "503": { "description": "Job queue full." } } } }, "/v1/jobs/seo-basics": { "post": { "operationId": "createJobSeoBasics", "summary": "Async job: On-page SEO basics", "description": "Queues a scan and returns 202 with a `job_id` immediately. Send `url` (or `domain`) for one target, or `urls` (array, max 50 by default) for a batch; credits are reserved per URL and charged only for URLs that succeed. Optional `webhook_url` receives a signed POST when the job finishes (header `X-SiteVerdict-Signature: t=,v1=.\")>`). Body fields are otherwise the same as POST /v1/scan/{tool}.", "tags": [ "Jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "domain": { "type": "string", "description": "domain-health only" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Batch of targets (URLs, or domains for domain-health)." }, "webhook_url": { "type": "string", "format": "uri" }, "fresh": { "type": "boolean" } }, "additionalProperties": true, "description": "Plus the options of seo-basics: broken_link_sample (see POST /v1/scan/seo-basics)." }, "example": { "urls": [ "https://example.com", "https://example.org" ], "webhook_url": "https://hooks.example.net/siteverdict" } } } }, "responses": { "202": { "description": "Job accepted" }, "400": { "description": "Invalid request." }, "401": { "description": "Unauthorized." }, "402": { "description": "Not enough credits for all URLs in the batch." }, "429": { "description": "Rate limited." }, "503": { "description": "Job queue full." } } } }, "/v1/jobs/privacy-policy": { "post": { "operationId": "createJobPrivacyPolicy", "summary": "Async job: Cookie & privacy-policy checker (UK GDPR / PECR / ePrivacy)", "description": "Queues a scan and returns 202 with a `job_id` immediately. Send `url` (or `domain`) for one target, or `urls` (array, max 50 by default) for a batch; credits are reserved per URL and charged only for URLs that succeed. Optional `webhook_url` receives a signed POST when the job finishes (header `X-SiteVerdict-Signature: t=,v1=.\")>`). Body fields are otherwise the same as POST /v1/scan/{tool}.", "tags": [ "Jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "domain": { "type": "string", "description": "domain-health only" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Batch of targets (URLs, or domains for domain-health)." }, "webhook_url": { "type": "string", "format": "uri" }, "fresh": { "type": "boolean" } }, "additionalProperties": true, "description": "Plus the options of privacy-policy: privacy_policy_url, cookie_policy_url, internal_pages, generate_drafts, locale, timezone (see POST /v1/scan/privacy-policy)." }, "example": { "urls": [ "https://example.com", "https://example.org" ], "webhook_url": "https://hooks.example.net/siteverdict" } } } }, "responses": { "202": { "description": "Job accepted" }, "400": { "description": "Invalid request." }, "401": { "description": "Unauthorized." }, "402": { "description": "Not enough credits for all URLs in the batch." }, "429": { "description": "Rate limited." }, "503": { "description": "Job queue full." } } } }, "/v1/jobs/web-to-markdown": { "post": { "operationId": "createJobWebToMarkdown", "summary": "Async job: Web page to clean Markdown (for LLMs / RAG)", "description": "Queues a scan and returns 202 with a `job_id` immediately. Send `url` (or `domain`) for one target, or `urls` (array, max 50 by default) for a batch; credits are reserved per URL and charged only for URLs that succeed. Optional `webhook_url` receives a signed POST when the job finishes (header `X-SiteVerdict-Signature: t=,v1=.\")>`). Body fields are otherwise the same as POST /v1/scan/{tool}.", "tags": [ "Jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "domain": { "type": "string", "description": "domain-health only" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Batch of targets (URLs, or domains for domain-health)." }, "webhook_url": { "type": "string", "format": "uri" }, "fresh": { "type": "boolean" } }, "additionalProperties": true, "description": "Plus the options of web-to-markdown: rendering, extraction, include_links, include_images, include_text, chunking, chunk_size, max_chars (see POST /v1/scan/web-to-markdown)." }, "example": { "urls": [ "https://example.com", "https://example.org" ], "webhook_url": "https://hooks.example.net/siteverdict" } } } }, "responses": { "202": { "description": "Job accepted" }, "400": { "description": "Invalid request." }, "401": { "description": "Unauthorized." }, "402": { "description": "Not enough credits for all URLs in the batch." }, "429": { "description": "Rate limited." }, "503": { "description": "Job queue full." } } } }, "/v1/jobs/full-audit": { "post": { "operationId": "createJobFullAudit", "summary": "Async job: Full website audit (all checks, one prioritised fix list)", "description": "Queues a scan and returns 202 with a `job_id` immediately. Send `url` (or `domain`) for one target, or `urls` (array, max 50 by default) for a batch; credits are reserved per URL and charged only for URLs that succeed. Optional `webhook_url` receives a signed POST when the job finishes (header `X-SiteVerdict-Signature: t=,v1=.\")>`). Body fields are otherwise the same as POST /v1/scan/{tool}.", "tags": [ "Jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "domain": { "type": "string", "description": "domain-health only" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Batch of targets (URLs, or domains for domain-health)." }, "webhook_url": { "type": "string", "format": "uri" }, "fresh": { "type": "boolean" } }, "additionalProperties": true, "description": "Plus the options of full-audit: sections, max_findings (see POST /v1/scan/full-audit)." }, "example": { "urls": [ "https://example.com", "https://example.org" ], "webhook_url": "https://hooks.example.net/siteverdict" } } } }, "responses": { "202": { "description": "Job accepted" }, "400": { "description": "Invalid request." }, "401": { "description": "Unauthorized." }, "402": { "description": "Not enough credits for all URLs in the batch." }, "429": { "description": "Rate limited." }, "503": { "description": "Job queue full." } } } }, "/v1/jobs/{job_id}": { "get": { "operationId": "getJob", "summary": "Get job status and result", "tags": [ "Jobs" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^job_[A-Za-z0-9]{20}$" } } ], "responses": { "200": { "description": "Job" }, "404": { "description": "Not found." } } }, "delete": { "operationId": "cancelJob", "summary": "Cancel a queued job (reserved credits are released)", "tags": [ "Jobs" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled" }, "404": { "description": "Not found." }, "409": { "description": "Job is not queued." } } } }, "/v1/jobs": { "get": { "operationId": "listJobs", "summary": "List recent jobs", "tags": [ "Jobs" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Jobs" } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "summary": "Plan, credits used/left this period", "tags": [ "Account" ], "responses": { "200": { "description": "Usage" } } } } } }