{"openapi":"3.1.0","info":{"title":"Santos Website Intelligence API","version":"2.16.0","description":"AI Website Intelligence for determining whether public websites can be discovered, understood, trusted, and used by agents. Eleven paid capabilities use USDC on Base mainnet (eip155:8453) via x402 v2 with no account or traditional API key. QUICK INTELLIGENCE (GET /api/audit, $0.015, synchronous): lightweight single-page fetch-and-parse audit. AGENT READINESS (GET /api/agent-readiness, $0.075, synchronous): bounded passive discovery and applicability-aware assessment of agent-facing interfaces. DEEP WEBSITE INTELLIGENCE (POST /v1/audits, $0.225, asynchronous): real Chromium via Playwright, Lighthouse, rendered axe-core, browser evidence, screenshots, and passive security checks. The other eight paid capabilities — SAFE FETCH (GET /v1/fetch, $0.002), CONTENT EXTRACTION (POST /v1/extract, $0.005), FEED PARSER (GET /v1/feed, $0.003), LINK MAP (GET /v1/links, $0.003), SUMMARIZER (POST /v1/summarize, $0.033), SCREENSHOT & PDF RENDER (GET /v1/screenshot, $0.01), STRUCTURED EXTRACTION (POST /v1/extract/structured, $0.08), and BATCH QUICK INTELLIGENCE (POST /api/audit/batch, $0.50 flat for up to 50 URLs) — are documented per-path below. Quick and Agent Readiness payments settle only on a successful response; Deep payment purchases a bounded compute reservation and settles when the job is accepted.","contact":{"name":"Santos Automation","email":"info@santosautomation.com","url":"https://www.santosautomation.com"}},"servers":[{"url":"https://api.santosautomation.com"}],"paths":{"/api/agent-readiness":{"get":{"operationId":"auditAgentReadiness","tags":["Agent Readiness"],"summary":"Assess public agent-facing interfaces ($0.075 USDC via x402)","description":"Requires $0.075 USDC through x402 v2 and settles only after a successful audit response. Classifies the target before scoring and evaluates only applicable surfaces: discovery/docs, structured identity, APIs, MCP, operational trust, and machine commerce. For paid surfaces it normalizes public pricing claims and compares only claims scoped to the same paid resource against an unsigned x402 challenge. The quick pass performs at most eight additional bounded public requests. It never authenticates, creates accounts, submits forms, signs target payments, transfers funds to the target, or invokes advertised MCP/business tools. llms.txt is treated as a proposal and the MCP Registry as preview infrastructure.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"Publicly reachable HTTP or HTTPS website URL. Bare domains are accepted (https:// is assumed). Localhost, private-network, and cloud-metadata addresses are rejected.","example":"https://example.com"},{"name":"depth","in":"query","required":false,"schema":{"type":"string","enum":["quick"],"default":"quick"}}],"responses":{"200":{"description":"Versioned Agent Readiness result with additive Website Intelligence presentation fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentReadinessResult"}}}},"400":{"description":"Invalid or blocked target URL.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"402":{"description":"Payment required. PAYMENT-REQUIRED contains x402 v2 terms for $0.075 USDC (75000 atomic units) on eip155:8453."},"502":{"description":"Target or required public interface was unreachable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"504":{"description":"Bounded audit timed out.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/api/audit":{"get":{"operationId":"auditWebsite","tags":["Quick Intelligence"],"summary":"Run a Quick Intelligence Audit ($0.015 USDC via x402)","description":"Requires x402 v2 payment. An unpaid request returns HTTP 402 with machine-readable terms in the base64 `PAYMENT-REQUIRED` response header (`accepts[0]`: $0.015 USDC as amount \"15000\", network eip155:8453, scheme `exact`), including an x402 Bazaar discovery extension with input/output JSON Schemas. Sign an EIP-3009 transferWithAuthorization for the quoted amount and retry with the `PAYMENT-SIGNATURE` request header. Any x402 v2 client (e.g. @x402/fetch) automates this. Payment settles only after a successful (2xx) response — failed audits cost nothing. Rejected payments and audit failures return structured errors.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"Publicly reachable HTTP or HTTPS website URL. Bare domains are accepted (https:// is assumed). Localhost, private-network, and cloud-metadata addresses are rejected.","example":"https://example.com"}],"responses":{"200":{"description":"Audit complete; payment settled. The PAYMENT-RESPONSE header carries a base64 on-chain receipt (transaction hash, network, payer).","headers":{"PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Base64-encoded JSON settlement receipt: { success, transaction, network, payer }."}},"content":{"application/json":{"schema":{"type":"object","required":["tier","url","fetched_at","http_status","timing_ms","overall_score","scores","checks","issues"],"properties":{"schema_version":{"type":"string","enum":["2.1.0"]},"tier":{"type":"string","enum":["paid"]},"url":{"type":"string","format":"uri","description":"The final URL audited, after redirects."},"fetched_at":{"type":"string","format":"date-time"},"http_status":{"type":"integer","description":"HTTP status returned by the audited site."},"timing_ms":{"type":"object","properties":{"ttfb":{"type":"integer"},"total":{"type":"integer"}},"description":"Time-to-first-byte and total fetch time in milliseconds."},"overall_score":{"type":"integer","minimum":0,"maximum":100},"website_intelligence_score":{"type":["integer","null"],"minimum":0,"maximum":100},"website_intelligence":{"$ref":"#/components/schemas/WebsiteIntelligence"},"scores":{"type":"object","required":["performance","seo","accessibility","security"],"properties":{"performance":{"type":"integer","minimum":0,"maximum":100},"seo":{"type":"integer","minimum":0,"maximum":100},"accessibility":{"type":"integer","minimum":0,"maximum":100},"security":{"type":"integer","minimum":0,"maximum":100}}},"checks":{"type":"object","description":"Per-category check results. Each entry has pass, detail, and (on failure) fix.","additionalProperties":{"type":"array","items":{"type":"object","required":["pass","detail"],"properties":{"pass":{"type":"boolean"},"detail":{"type":"string"},"fix":{"type":"string"}}}}},"issues":{"type":"array","items":{"type":"string"},"description":"Plain-English remediation instructions for every failed check."},"agent_readiness":{"$ref":"#/components/schemas/AgentReadinessResult"},"audited_by":{"type":"string"}}}}}},"400":{"description":"Invalid or blocked target URL.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"402":{"description":"Payment required, invalid, or failed verification. Full terms are in the base64 PAYMENT-REQUIRED response header (x402Version 2, accepts[], extensions.bazaar); the JSON body is a short agent-readable hint.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded JSON: { x402Version: 2, resource, accepts: [{ scheme, network, amount, asset, payTo, maxTimeoutSeconds }], extensions }. amount \"15000\" = $0.015 USDC."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["PAYMENT_REQUIRED"]},"hint":{"type":"string"}}}}}},"502":{"description":"Target site unreachable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"504":{"description":"Target site timed out (15s limit).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/api/audit/batch":{"post":{"operationId":"auditWebsiteBatch","tags":["Quick Intelligence"],"summary":"Batch Quick Intelligence Audits ($0.50 USDC flat via x402, up to 50 URLs)","description":"Requires x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE). Audits up to 50 public URLs for one flat payment — the same report shape as GET /api/audit per URL, with a Website Intelligence score. Duplicates are removed; at most 8 targets are fetched concurrently. Per-URL failures are isolated and returned as error entries; payment settles only when at least one audit succeeds — a batch where every URL fails returns 502 and is never charged. Synchronous; typical batches finish in seconds, worst-case is a few minutes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","format":"uri"},"description":"Public HTTP or HTTPS URLs to audit."}}}}}},"responses":{"200":{"description":"Batch complete; payment settled. The PAYMENT-RESPONSE header carries a base64 on-chain receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","enum":["paid"]},"batch_size":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"ok":{"type":"boolean"},"report":{"type":"object","required":["tier","url","fetched_at","http_status","timing_ms","overall_score","scores","checks","issues"],"properties":{"schema_version":{"type":"string","enum":["2.1.0"]},"tier":{"type":"string","enum":["paid"]},"url":{"type":"string","format":"uri","description":"The final URL audited, after redirects."},"fetched_at":{"type":"string","format":"date-time"},"http_status":{"type":"integer","description":"HTTP status returned by the audited site."},"timing_ms":{"type":"object","properties":{"ttfb":{"type":"integer"},"total":{"type":"integer"}},"description":"Time-to-first-byte and total fetch time in milliseconds."},"overall_score":{"type":"integer","minimum":0,"maximum":100},"website_intelligence_score":{"type":["integer","null"],"minimum":0,"maximum":100},"website_intelligence":{"$ref":"#/components/schemas/WebsiteIntelligence"},"scores":{"type":"object","required":["performance","seo","accessibility","security"],"properties":{"performance":{"type":"integer","minimum":0,"maximum":100},"seo":{"type":"integer","minimum":0,"maximum":100},"accessibility":{"type":"integer","minimum":0,"maximum":100},"security":{"type":"integer","minimum":0,"maximum":100}}},"checks":{"type":"object","description":"Per-category check results. Each entry has pass, detail, and (on failure) fix.","additionalProperties":{"type":"array","items":{"type":"object","required":["pass","detail"],"properties":{"pass":{"type":"boolean"},"detail":{"type":"string"},"fix":{"type":"string"}}}}},"issues":{"type":"array","items":{"type":"string"},"description":"Plain-English remediation instructions for every failed check."},"agent_readiness":{"$ref":"#/components/schemas/AgentReadinessResult"},"audited_by":{"type":"string"}}},"error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}}}},"400":{"description":"Malformed body, empty urls array, or more than 50 URLs.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"402":{"description":"Payment required. PAYMENT-REQUIRED contains x402 v2 terms for $0.50 USDC on eip155:8453."},"502":{"description":"Every URL in the batch failed; no charge settled.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/fetch":{"get":{"operationId":"safeFetchUrl","tags":["Safe Fetch"],"summary":"Fetch one public URL through the hardened safe-fetcher ($0.002 USDC via x402, synchronous)","description":"Requires x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE); settles only on a successful fetch. Returns the raw text body plus response metadata: final URL after redirects, HTTP status, selected response headers, byte count, and timing. SSRF-guarded (private/link-local/cloud-metadata addresses blocked including via redirects), 15s timeout, 5 redirects max, 2MB cap, ports 80/443 only. Text formats only: HTML, JSON, XML, feeds, plain text, JavaScript, SVG. A POST variant with a JSON {url} body is paywalled identically.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"Publicly reachable HTTP or HTTPS website URL. Bare domains are accepted (https:// is assumed). Localhost, private-network, and cloud-metadata addresses are rejected.","example":"https://example.com"}],"responses":{"200":{"description":"Fetch complete.","content":{"application/json":{"schema":{"type":"object","required":["schema_version","url","final_url","http_status","body","body_bytes"],"properties":{"schema_version":{"type":"string","const":"1.0.0"},"url":{"type":"string"},"final_url":{"type":"string","format":"uri"},"http_status":{"type":"integer"},"content_type":{"type":["string","null"]},"headers":{"type":"object","additionalProperties":{"type":"string"}},"body":{"type":"string"},"body_bytes":{"type":"integer"},"fetched_at":{"type":"string","format":"date-time"},"timing_ms":{"type":"object","properties":{"ttfb":{"type":"integer"},"total":{"type":"integer"}}}}}}}},"400":{"description":"Invalid or blocked target URL (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"402":{"description":"Payment required/invalid. Terms in the PAYMENT-REQUIRED header; body is an agent-readable hint."},"502":{"description":"Target site unreachable (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"504":{"description":"Target site timed out (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/extract":{"post":{"operationId":"extractPageMarkdown","tags":["Content Extraction"],"summary":"Extract one page as clean Markdown ($0.005 USDC via x402, synchronous)","description":"Requires x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE); settles only on a successful extraction. Fetches one public page (SSRF-guarded, 15s timeout, 5MB cap) and returns readability-isolated main content as Markdown plus title, description, canonical URL, outbound links (max 200), and word count. Single page only — no crawling, no JavaScript rendering. A GET variant with ?url= is also paywalled identically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public HTTP/HTTPS page. Private-network/metadata targets rejected free of charge."}}}}}},"responses":{"200":{"description":"Extraction complete.","content":{"application/json":{"schema":{"type":"object","required":["schema_version","url","final_url","http_status","markdown","word_count"],"properties":{"schema_version":{"type":"string","const":"1.0.0"},"url":{"type":"string"},"final_url":{"type":"string","format":"uri"},"http_status":{"type":"integer"},"title":{"type":["string","null"]},"byline":{"type":["string","null"]},"description":{"type":["string","null"]},"canonical_url":{"type":["string","null"]},"markdown":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"text":{"type":"string"}},"required":["url"]}},"word_count":{"type":"integer"},"fetched_at":{"type":"string","format":"date-time"},"timing_ms":{"type":"object","properties":{"ttfb":{"type":"integer"},"total":{"type":"integer"}}}}}}}},"400":{"description":"Invalid or blocked target URL (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"402":{"description":"Payment required/invalid. Terms in the PAYMENT-REQUIRED header; body is an agent-readable hint."},"502":{"description":"Target site unreachable (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"504":{"description":"Target site timed out (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/extract/structured":{"post":{"operationId":"extractStructuredData","tags":["Structured Extraction"],"summary":"Extract structured JSON from one page against your JSON Schema ($0.08 USDC via x402, synchronous)","description":"Requires x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE); settles only when the extracted data validates against your schema — a schema that can't be satisfied from the page costs nothing. Fetches one public page (SSRF-guarded, 15s timeout, 5MB cap), truncates readability-isolated Markdown to 8000 characters, then calls Claude with forced tool-use against your schema (max 1024 output tokens). The caller's schema must be a self-contained JSON Schema object (type: object, no $ref, under 4000 characters) or the request 400s before any fetch or model call. No GET variant — the schema doesn't fit cleanly in query params.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","schema"],"properties":{"url":{"type":"string","format":"uri","description":"Public HTTP/HTTPS page. Private-network/metadata targets rejected free of charge."},"schema":{"type":"object","description":"Self-contained JSON Schema (type: object, no $ref) describing the fields to extract. Max 4000 characters."}}}}}},"responses":{"200":{"description":"Extraction complete; the extracted data conforms to the caller's schema.","content":{"application/json":{"schema":{"type":"object","required":["schema_version","url","final_url","http_status","data","model","fetched_at","timing_ms"],"properties":{"schema_version":{"type":"string","const":"1.0.0"},"url":{"type":"string"},"final_url":{"type":"string","format":"uri"},"http_status":{"type":"integer"},"data":{"type":"object","description":"Extracted fields, matching the caller's schema."},"model":{"type":"string"},"fetched_at":{"type":"string","format":"date-time"},"timing_ms":{"type":"object","properties":{"fetch":{"type":"integer"},"llm":{"type":"integer"},"total":{"type":"integer"}}}}}}}},"400":{"description":"Invalid or blocked target URL, or an invalid/oversized/uncompilable caller schema (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"402":{"description":"Payment required/invalid. Terms in the PAYMENT-REQUIRED header; body is an agent-readable hint."},"422":{"description":"Model output did not validate against the caller's schema (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"502":{"description":"Target site unreachable (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"504":{"description":"Target site timed out (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/feed":{"get":{"operationId":"parseFeed","tags":["Feed Parser"],"summary":"Parse one public feed URL into normalized JSON ($0.003 USDC via x402, synchronous)","description":"Requires x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE); settles only on a successful parse. Fetches one public feed URL through the same hardened SSRF-guarded fetcher as /v1/fetch (private/link-local/cloud-metadata addresses blocked including via redirects, 15s timeout, 2MB cap, ports 80/443 only), detects RSS 2.0, Atom, or JSON Feed, and returns normalized JSON: feed metadata (title, link, description, feed_url) plus up to 50 items with id, title, url, published, summary, and author. A target that is not a recognized feed returns 422 and never settles. A POST variant with a JSON {url} body is paywalled identically.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"Publicly reachable HTTP or HTTPS website URL. Bare domains are accepted (https:// is assumed). Localhost, private-network, and cloud-metadata addresses are rejected.","example":"https://example.com"}],"responses":{"200":{"description":"Feed parsed.","content":{"application/json":{"schema":{"type":"object","required":["schema_version","url","final_url","format","feed","item_count","items"],"properties":{"schema_version":{"type":"string","const":"1.0.0"},"url":{"type":"string"},"final_url":{"type":"string","format":"uri"},"format":{"type":"string","enum":["rss2","atom","json"]},"feed":{"type":"object","properties":{"title":{"type":["string","null"]},"link":{"type":["string","null"]},"description":{"type":["string","null"]},"feed_url":{"type":["string","null"]}}},"item_count":{"type":"integer","maximum":50},"items":{"type":"array","maxItems":50,"items":{"type":"object","properties":{"id":{"type":["string","null"]},"title":{"type":["string","null"]},"url":{"type":["string","null"]},"published":{"type":["string","null"]},"summary":{"type":["string","null"]},"author":{"type":["string","null"]}}}}}}}}},"400":{"description":"Invalid or blocked target URL (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"402":{"description":"Payment required/invalid. Terms in the PAYMENT-REQUIRED header; body is an agent-readable hint."},"422":{"description":"Target is not a recognized RSS 2.0, Atom, or JSON Feed (not charged — never settles).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"502":{"description":"Target site unreachable (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"504":{"description":"Target site timed out (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/links":{"get":{"operationId":"mapPageLinks","tags":["Link Map"],"summary":"Map one page's links into a categorized link map ($0.003 USDC via x402, synchronous)","description":"Requires x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE); settles only on a successful response. Fetches one public HTML page (SSRF-guarded, 15s timeout, 5MB cap) and returns a categorized link map: every link resolved, deduped, and classified by kind (internal or external) plus topic tags (docs, pricing, api, careers, social, feed), with counts for each kind and topic — up to 200 links. Built for site-structure discovery: finding a target's docs, pricing, API, careers, social profiles, or feed URLs in one call. A POST variant with a JSON {url} body is paywalled identically.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"Publicly reachable HTTP or HTTPS website URL. Bare domains are accepted (https:// is assumed). Localhost, private-network, and cloud-metadata addresses are rejected.","example":"https://example.com"}],"responses":{"200":{"description":"Link map complete.","content":{"application/json":{"schema":{"type":"object","required":["schema_version","url","final_url","http_status","total_links","counts","links"],"properties":{"schema_version":{"type":"string","const":"1.0.0"},"url":{"type":"string"},"final_url":{"type":"string","format":"uri"},"http_status":{"type":"integer"},"total_links":{"type":"integer","maximum":200},"counts":{"type":"object","properties":{"internal":{"type":"integer"},"external":{"type":"integer"},"docs":{"type":"integer"},"pricing":{"type":"integer"},"api":{"type":"integer"},"careers":{"type":"integer"},"social":{"type":"integer"},"feed":{"type":"integer"}}},"links":{"type":"array","maxItems":200,"items":{"type":"object","required":["url","kind"],"properties":{"url":{"type":"string"},"text":{"type":"string"},"kind":{"type":"string","enum":["internal","external"]},"topics":{"type":"array","items":{"type":"string","enum":["docs","pricing","api","careers","social","feed"]}}}}}}}}}},"400":{"description":"Invalid or blocked target URL (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"402":{"description":"Payment required/invalid. Terms in the PAYMENT-REQUIRED header; body is an agent-readable hint."},"502":{"description":"Target site unreachable (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"504":{"description":"Target site timed out (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/summarize":{"post":{"operationId":"summarizePage","tags":["Summarizer"],"summary":"Summarize one page into structured JSON with Claude ($0.033 USDC via x402, synchronous)","description":"Requires x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE); settles only on a successful summary. Fetches one public HTML page (SSRF-guarded, 15s timeout, 5MB cap) and returns a Claude-generated structured summary: title, summary, key_facts, entities, and word_count. An optional focus string steers the summary (e.g. \"pricing plans\"). Non-HTML targets return 422 and never settle. A GET variant with ?url=&focus= is paywalled identically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public HTTP/HTTPS page. Private-network/metadata targets rejected free of charge."},"focus":{"type":"string","description":"Optional steering prompt for the summary, e.g. \"pricing plans\"."}}}}}},"responses":{"200":{"description":"Summary complete.","content":{"application/json":{"schema":{"type":"object","required":["schema_version","url","final_url","http_status","summary","model"],"properties":{"schema_version":{"type":"string","const":"1.0.0"},"url":{"type":"string"},"final_url":{"type":"string","format":"uri"},"http_status":{"type":"integer"},"title":{"type":["string","null"]},"summary":{"type":"string"},"key_facts":{"type":"array","items":{"type":"string"}},"entities":{"type":"array","items":{"type":"string"}},"word_count":{"type":"integer"},"focus":{"type":["string","null"]},"model":{"type":"string"}}}}}},"400":{"description":"Invalid or blocked target URL (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"402":{"description":"Payment required/invalid. Terms in the PAYMENT-REQUIRED header; body is an agent-readable hint."},"422":{"description":"Target returned non-HTML content (not charged — never settles).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"502":{"description":"Target site unreachable (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"504":{"description":"Target site timed out (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/screenshot":{"get":{"operationId":"renderScreenshot","tags":["Screenshot & PDF Render"],"summary":"Render one page as PNG/JPEG/PDF in a real browser ($0.01 USDC via x402, synchronous)","description":"Requires x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE); settles only when render bytes are returned — timeouts (504) and failures (502/503) are free. Renders in an isolated SSRF-guarded Chromium session with request/byte budgets, executing JavaScript so SPAs, client-rendered charts, and post-load layout are captured as a real visitor sees them; the binary returns directly with an X-Render-Job header. Common agent uses: verifying a deployed page renders correctly, visual change monitoring, link previews, print-rendered A4 PDF archival, and producing input for vision-capable models. Every render is a fresh anonymous visitor: no login-protected content, no cookies carried. Typical latency: seconds when a worker is warm; a cold worker wakes on demand and may 504 the first try — retry.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"Publicly reachable HTTP or HTTPS website URL. Bare domains are accepted (https:// is assumed). Localhost, private-network, and cloud-metadata addresses are rejected.","example":"https://example.com"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["png","jpeg","pdf"],"default":"png"}},{"name":"device","in":"query","required":false,"schema":{"type":"string","enum":["desktop","mobile"],"default":"desktop"}},{"name":"full_page","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Capture the entire page height instead of the viewport (ignored for pdf)."}],"responses":{"200":{"description":"Render bytes.","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid or blocked target/parameters (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"402":{"description":"Payment required/invalid. Terms in the PAYMENT-REQUIRED header; body is an agent-readable hint."},"502":{"description":"Render failed (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"503":{"description":"No render worker available (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"504":{"description":"Render did not finish in time (not charged) — retry.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/badge":{"get":{"operationId":"getAgentReadyBadge","security":[],"tags":["Free Tools"],"summary":"Agent-Ready badge (free SVG, no quota)","description":"Returns an SVG shield with the site's latest public Agent Readiness score and verification date — gold/green by grade, gray 'unverified' when no public report exists, and a re-verify state when the latest report is over 30 days old. Free, no quota (it is an image); Cache-Control: public, max-age=3600. Embed: [![Agent-Ready badge](https://api.santosautomation.com/v1/badge?url=example.com)](https://www.santosautomation.com/reports/example.com).","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"Publicly reachable HTTP or HTTPS website URL. Bare domains are accepted (https:// is assumed). Localhost, private-network, and cloud-metadata addresses are rejected.","example":"https://example.com"}],"responses":{"200":{"description":"SVG badge image.","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"description":"Invalid or blocked target URL.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/verify":{"post":{"operationId":"verifyReportSignature","security":[],"tags":["Free Tools"],"summary":"Verify a signed audit report (free, 30/hour per IP)","description":"Verifies the HMAC-SHA256 signature on a Santos audit report. POST the full report JSON exactly as returned by any audit endpoint (including its signature_alg, signed_at, and signature fields). Returns whether the signature is valid for the unmodified report. Rate-limited to 30 verifications per hour per IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The full report JSON, including signature fields."}}}},"responses":{"200":{"description":"Verification result.","content":{"application/json":{"schema":{"type":"object","required":["valid"],"properties":{"valid":{"type":"boolean"},"url":{"type":"string"},"score":{"type":["integer","null"]},"signed_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Malformed body or missing signature fields.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"429":{"description":"Hourly verification limit reached.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/audits":{"post":{"operationId":"createDeepAudit","tags":["Deep Website Intelligence"],"summary":"Create a Deep Website Intelligence job ($0.225 USDC via x402, asynchronous)","description":"Requires x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE). The payment purchases one bounded compute reservation — it settles when the job is ACCEPTED (201), not when the report completes. Runs a real Chromium browser (Playwright) against the page: Lighthouse (mobile lab metrics), rendered axe-core accessibility checks (WCAG 2.x A/AA tags), browser network/console evidence, screenshots, and passive security checks. Send an Idempotency-Key header so retries return the existing job (409 IDEMPOTENT_REPLAY, not charged) instead of purchasing a duplicate. Typical completion: tens of seconds to a few minutes; poll status_url.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Strongly recommended. Same key + same body returns the existing job without a second charge; same key + different body is rejected (422 IDEMPOTENCY_KEY_REUSED)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public HTTP/HTTPS page. Private-network/metadata targets rejected free of charge."},"devices":{"type":"array","items":{"type":"string","enum":["mobile","desktop"]},"default":["mobile"]},"modules":{"type":"array","items":{"type":"string","enum":["lighthouse","accessibility","browser-network","security-passive","agent-readiness","ai-summary"]}},"artifacts":{"type":"object","properties":{"screenshots":{"type":"boolean","default":true},"lighthouse_json":{"type":"boolean","default":true},"lighthouse_html":{"type":"boolean","default":false}}}}}}}},"responses":{"201":{"description":"Job accepted and queued; payment settles on this response. Save access_token — it is shown only once.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Unguessable job id (aud_...)."},"status":{"type":"string","enum":["queued","running","aggregating","completed","failed","expired","cancelled"]},"stage":{"type":["string","null"]},"progress":{"type":"integer","minimum":0,"maximum":100},"access_token":{"type":"string","description":"Returned ONCE at creation; required (Bearer or ?token=) for every status/report/events/cancel call. Job ids alone are never authorization."},"status_url":{"type":"string","format":"uri"},"report_url":{"type":"string","format":"uri"},"events_url":{"type":"string","format":"uri"},"artifacts_url":{"type":"string","format":"uri"},"payment_contract":{"type":"string"},"error_code":{"type":"string"},"error_message":{"type":"string"}}}}}},"400":{"description":"Invalid or blocked target/request (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"402":{"description":"Payment required/invalid. Terms in the PAYMENT-REQUIRED header; body is an agent-readable hint."},"409":{"description":"Idempotent replay: the existing job for this Idempotency-Key (not charged).","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Unguessable job id (aud_...)."},"status":{"type":"string","enum":["queued","running","aggregating","completed","failed","expired","cancelled"]},"stage":{"type":["string","null"]},"progress":{"type":"integer","minimum":0,"maximum":100},"access_token":{"type":"string","description":"Returned ONCE at creation; required (Bearer or ?token=) for every status/report/events/cancel call. Job ids alone are never authorization."},"status_url":{"type":"string","format":"uri"},"report_url":{"type":"string","format":"uri"},"events_url":{"type":"string","format":"uri"},"artifacts_url":{"type":"string","format":"uri"},"payment_contract":{"type":"string"},"error_code":{"type":"string"},"error_message":{"type":"string"}}}}}},"422":{"description":"Idempotency-Key reused with a different body.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"503":{"description":"Deep tier not enabled or storage unavailable (not charged).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/audits/{job_id}":{"get":{"operationId":"getDeepAuditStatus","security":[],"tags":["Deep Page Audit"],"summary":"Job status (requires access token)","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"token","in":"query","required":false,"schema":{"type":"string"},"description":"Job access token (alternative to Authorization: Bearer)."}],"responses":{"200":{"description":"Job state.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Unguessable job id (aud_...)."},"status":{"type":"string","enum":["queued","running","aggregating","completed","failed","expired","cancelled"]},"stage":{"type":["string","null"]},"progress":{"type":"integer","minimum":0,"maximum":100},"access_token":{"type":"string","description":"Returned ONCE at creation; required (Bearer or ?token=) for every status/report/events/cancel call. Job ids alone are never authorization."},"status_url":{"type":"string","format":"uri"},"report_url":{"type":"string","format":"uri"},"events_url":{"type":"string","format":"uri"},"artifacts_url":{"type":"string","format":"uri"},"payment_contract":{"type":"string"},"error_code":{"type":"string"},"error_message":{"type":"string"}}}}}},"401":{"description":"Missing/invalid access token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"404":{"description":"Unknown job.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/audits/{job_id}/report":{"get":{"operationId":"getDeepAuditReport","security":[],"tags":["Deep Page Audit"],"summary":"Completed report (versioned JSON, requires access token)","description":"schema_version 3.0.0. Sections: target, engines (Chromium/Lighthouse/axe versions), module_status, deterministic scores + scoring_method, lab metrics (labeled laboratory data), network metrics, normalized findings (stable id, engine, category, severity, confidence, status, evidence, standards, recommendation), optional ai_summary (model-generated narrative, clearly labeled), artifacts with short-lived signed download URLs, and explicit limitations.","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"token","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string","const":"3.0.0"},"scores":{"type":"object"},"website_intelligence_score":{"type":["integer","null"]},"website_intelligence":{"$ref":"#/components/schemas/WebsiteIntelligence"},"agent_readiness":{"$ref":"#/components/schemas/AgentReadinessResult"},"findings":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Missing/invalid access token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"404":{"description":"Unknown job or expired report.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}},"409":{"description":"Job not completed yet (code REPORT_NOT_READY, includes status/stage/progress).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["INVALID_URL","UNSUPPORTED_SCHEME","PRIVATE_ADDRESS_BLOCKED","RATE_LIMITED","FREE_TIER_RETIRED","AUDIT_TIMEOUT","TARGET_UNREACHABLE","AUDIT_FAILED","INVALID_EXTRACTION_SCHEMA","STRUCTURED_OUTPUT_INVALID"]}}}}}}}}},"/v1/audits/{job_id}/cancel":{"post":{"operationId":"cancelDeepAudit","security":[],"tags":["Deep Page Audit"],"summary":"Cancel a queued job (requires access token)","description":"Only queued jobs can be cancelled; running/terminal jobs return 409 NOT_CANCELLABLE. The compute reservation is spent either way.","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled."},"401":{"description":"Missing/invalid access token."},"409":{"description":"Not cancellable."}}}}},"components":{"schemas":{"AgentReadinessResult":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.santosautomation.com/schemas/agent-readiness-result-1.0.0.json","title":"AgentReadinessResult","type":"object","required":["schema_version","target","profile","readiness_level","score","grade","confidence","tested_coverage_percent","applicability","subscores","interfaces","findings","recommended_actions","limitations"],"properties":{"schema_version":{"type":"string","const":"1.0.0"},"website_intelligence_score":{"type":["integer","null"],"minimum":0,"maximum":100},"website_intelligence":{"type":"object","description":"Additive AI Website Intelligence presentation with four dimensions, coverage, confidence, and prioritized fixes.","properties":{"schema_version":{"type":"string","const":"1.0.0"},"score":{"type":["integer","null"],"minimum":0,"maximum":100},"dimensions":{"type":"object","properties":{"discoverable":{"type":["integer","null"],"minimum":0,"maximum":100},"understandable":{"type":["integer","null"],"minimum":0,"maximum":100},"callable":{"type":["integer","null"],"minimum":0,"maximum":100},"trustworthy":{"type":["integer","null"],"minimum":0,"maximum":100}}}}},"target":{"type":"object","required":["requested_url","canonical_origin","final_url"],"properties":{"requested_url":{"type":"string"},"canonical_origin":{"type":"string","format":"uri"},"final_url":{"type":"string","format":"uri"}},"additionalProperties":false},"profile":{"type":"string","enum":["general_website","documentation_site","api_provider","mcp_provider","agent_commerce_provider"]},"readiness_level":{"type":"object","required":["level","name"],"properties":{"level":{"type":"integer","minimum":0,"maximum":4},"name":{"type":"string"}},"additionalProperties":false},"score":{"type":"integer","minimum":0,"maximum":100},"grade":{"type":"string","enum":["A","B","C","D","F"]},"confidence":{"type":"number","minimum":0,"maximum":1},"tested_coverage_percent":{"type":"integer","minimum":0,"maximum":100},"applicability":{"type":"object","additionalProperties":{"type":"string","enum":["tested","not_applicable","unknown"]}},"subscores":{"type":"object","additionalProperties":{"type":"integer","minimum":0,"maximum":100}},"interfaces":{"type":"object"},"findings":{"type":"array","items":{"type":"object","required":["id","category","severity","confidence","status","title","recommendation"],"properties":{"id":{"type":"string"},"category":{"type":"string"},"severity":{"type":"string","enum":["info","low","moderate","high"]},"confidence":{"type":"string","enum":["low","medium","high"]},"status":{"type":"string","enum":["pass","fail","unknown","not_applicable"]},"title":{"type":"string"},"evidence":{"type":"object"},"recommendation":{"type":"string"}}}},"recommended_actions":{"type":"array","items":{"type":"object"}},"limitations":{"type":"array","items":{"type":"string"}},"fetch_budget":{"type":"object"}}},"WebsiteIntelligence":{"type":"object","description":"Additive presentation-layer synthesis. Historical score fields retain their established semantics.","required":["schema_version","score","dimensions","applicability","coverage","scoring_note"],"properties":{"schema_version":{"type":"string","const":"1.0.0"},"score":{"type":["integer","null"],"minimum":0,"maximum":100},"dimensions":{"type":"object","required":["discoverable","understandable","callable","trustworthy"],"properties":{"discoverable":{"type":["integer","null"],"minimum":0,"maximum":100},"understandable":{"type":["integer","null"],"minimum":0,"maximum":100},"callable":{"type":["integer","null"],"minimum":0,"maximum":100},"trustworthy":{"type":["integer","null"],"minimum":0,"maximum":100}}},"applicability":{"type":"object","properties":{"callable":{"type":"string","enum":["tested","not_applicable"]}}},"coverage":{"type":"object","properties":{"tests_available":{"type":"integer","minimum":0},"tests_executed":{"type":"integer","minimum":0},"tests_not_applicable":{"type":"integer","minimum":0},"tests_skipped":{"type":"integer","minimum":0},"tested_percent":{"type":"integer","minimum":0,"maximum":100}}},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"priority_fixes":{"type":"array","items":{"type":"object"}},"scoring_note":{"type":"string"}}}}},"tags":[{"name":"Quick Intelligence"},{"name":"Agent Readiness"},{"name":"Deep Website Intelligence"},{"name":"Free Tools"}]}