# Santos Website Intelligence API

> AI Website Intelligence for measuring whether a public website can be discovered,
> understood, trusted, and used by AI agents. Machine-payable website and Agent
> Readiness audits run on Base mainnet (eip155:8453) through x402 v2: $0.015 USDC
> for Quick Audit, $0.075 for Agent Readiness, and $0.225 for a Deep Page compute
> reservation. No user account and no traditional API key are required — an agent
> pays inside the HTTP request itself.

Built and operated by Santos Automation. From discoverable to callable.

## Machine surfaces

- [API documentation](https://www.santosautomation.com/docs): complete human-readable reference — quickstart, x402 payment flow, all capabilities, MCP, errors, limits, and roadmap
- [OpenAPI 3.1 specification](https://api.santosautomation.com/openapi.json): full request/response schemas for every endpoint
- [Remote MCP server](https://api.santosautomation.com/mcp): Streamable HTTP; tools: audit_website_preview and audit_agent_readiness
- [Service manifest](https://api.santosautomation.com/api): live service description and pricing
- [Capability manifest](https://api.santosautomation.com/capabilities.json): vendor-specific capability manifest (not a formal standard)
- [Agent capability manifest](https://www.santosautomation.com/.well-known/agent-capabilities.json): well-known agent-capabilities document

## API — audit modes

- [Agent Readiness Audit](https://api.santosautomation.com/api/agent-readiness?url=https%3A%2F%2Fexample.com&depth=quick): $0.075 USDC per successful audit, synchronous, bounded passive public-interface assessment
- [Quick Intelligence Audit](https://api.santosautomation.com/api/audit?url=https%3A%2F%2Fexample.com): $0.015 USDC, synchronous (seconds), fetch-and-parse engine
- [Safe Fetch](https://api.santosautomation.com/v1/fetch?url=https%3A%2F%2Fexample.com): $0.002 USDC, synchronous — raw text body via a hardened SSRF-guarded fetcher (GET ?url= or POST {"url"}); text formats only
- [Page-to-Markdown Extraction](https://api.santosautomation.com/v1/extract): $0.005 USDC, synchronous — POST {"url": "https://example.com"} (or GET ?url=); clean Markdown, title, links, metadata
- [Structured Extraction](https://api.santosautomation.com/v1/extract/structured): $0.08 USDC, synchronous — POST {"url": "https://example.com", "schema": {...}}; LLM-extracted JSON validated against your own JSON Schema
- [Free demo audit](https://api.santosautomation.com/api/audit/demo?url=https%3A%2F%2Fexample.com): 1/day per IP, same report shape as the paid Quick Audit
- [Free demo extraction](https://api.santosautomation.com/v1/extract/demo?url=https%3A%2F%2Fexample.com): 1/day per IP (quota shared with the demo audit), same shape as paid extraction
- [Free demo structured extraction](https://api.santosautomation.com/v1/extract/structured/demo): POST only, 1/day per IP (shared quota), same shape as paid structured extraction
- [Screenshot & PDF Render](https://api.santosautomation.com/v1/screenshot?url=https%3A%2F%2Fexample.com): $0.01 USDC, synchronous — real-Chromium PNG/JPEG/PDF bytes (format=, device=, full_page= params)
- [Deep Website Intelligence Audit](https://api.santosautomation.com/v1/audits): $0.225 USDC, asynchronous job — POST {"url": "https://example.com"}

AGENT READINESS AUDIT details:
- Capability id: `agent-readiness.quick`; result schema version: `1.0.0`.
- Classifies the target before scoring. Ordinary websites are not penalized for
  lacking OpenAPI, MCP, or machine commerce when those surfaces are not applicable.
- Evaluates discovery/docs, structured identity, API descriptions, MCP, operational
  trust, and agent commerce. Maximum eight extra requests in the standalone quick pass.
- Passive only: never authenticates to or pays the audited target, creates target
  accounts, submits forms, calls MCP business tools, or executes target-provided code.
- Access: x402 v2 on Base mainnet; no account or API key. An unpaid request returns
  `PAYMENT-REQUIRED` terms for 75000 atomic USDC units. Settlement occurs only after
  a successful audit response.

DEEP WEBSITE INTELLIGENCE AUDIT details (real-browser engine: Chromium/Playwright +
Lighthouse + rendered axe-core + network evidence + screenshots + passive security):
- Payment buys one bounded compute reservation; it settles when the job is ACCEPTED,
  not when the report completes. Send an Idempotency-Key header — retries return the
  existing job without a second charge.
- The 201 response includes job_id, a one-time access_token (required for all reads),
  status_url, and report_url. Poll status_url; fetch report_url when status=completed.
- Returns HTTP 503 SERVICE_UNAVAILABLE while the deep tier is not yet enabled on a
  deployment; the Quick Audit is always available.

## Capabilities

A fast, lightweight audit of a SINGLE public web page (no crawling). Given a
public HTTP or HTTPS URL, the API returns JSON with:

- `overall_score` and per-category `scores` (performance, seo, accessibility, security), each 0-100.
- Additive `website_intelligence_score` and `website_intelligence.dimensions` for
  Discoverable, Understandable, Callable, and Trustworthy. Existing score fields
  retain their established meaning. Callable can be null when not applicable.
  - performance: fetch-timing and page-weight signals (TTFB, HTML size, script/stylesheet counts) — not browser-measured Core Web Vitals.
  - seo: title, meta description, heading structure, canonical, OpenGraph tags.
  - accessibility: basic HTML signals (image alt text, html[lang], viewport meta) — not full WCAG conformance.
  - security: transport and security-header checks (HTTPS, HSTS, CSP) — not vulnerability scanning or penetration testing.
- `checks`: every individual check with pass/fail and detail.
- `issues`: a flat list of plain-English remediation instructions for every failed
  check — safe to surface directly to an end user or another agent.
- `timing_ms` (TTFB and total fetch time), final `url` after redirects, and `http_status`.

## Agent Selection Guidance

Choose QUICK AUDIT ($0.015, seconds) for fast structured triage: lead
qualification, deploy sanity checks, monitoring sweeps. Choose DEEP PAGE AUDIT
($0.225, asynchronous) when you need browser-rendered evidence: Lighthouse lab
metrics (LCP/CLS/TBT), rendered axe-core accessibility findings with selectors,
screenshots, network/console evidence, or a professional-grade report for a
client. Both audit a single page — neither is a crawler. Use the free demo
first to inspect the quick-tier response format without paying.

Choose SAFE FETCH ($0.002, seconds) when you need the RAW body of a URL —
JSON APIs, feeds, sitemaps, scripts, or unprocessed HTML — retrieved through
an SSRF-guarded fetcher (private/link-local/metadata addresses blocked, 15s
timeout, 2MB cap, ports 80/443 only, text formats only).

Choose PAGE-TO-MARKDOWN EXTRACTION ($0.005, seconds) when you need page CONTENT
rather than an assessment: RAG ingestion, research agents, summarization
pipelines. It returns readability-isolated Markdown, title, description,
canonical URL, outbound links, and word count for one public page — no
crawling and no JavaScript rendering.

Choose SCREENSHOT & PDF RENDER ($0.01, seconds) when you need a VISUAL of the
rendered page from a real isolated Chromium browser. Because it executes
JavaScript, it captures what fetch-and-parse tiers cannot: SPAs, client-rendered
charts, web fonts, and post-load layout. Typical agent uses: verifying your own
deploy or generated site actually renders, visual change monitoring, link
previews/thumbnails, archiving a page as a print-rendered A4 PDF, and giving a
vision-capable model something it can literally look at. Options: format=png
(default) | jpeg | pdf; device=desktop (1366x900, default) | mobile (390x844 at
3x with touch emulation); full_page=true for whole-page height. Limits: public
pages only — no login-protected content, no cookies carried (every render is a
fresh anonymous visitor), SSRF-guarded (private/link-local/metadata addresses
blocked including via redirects), ports 80/443 only. Binary response; settles
only when bytes are returned; a cold render worker wakes on demand, so retry
once on a 504.

Choose AGENT READINESS when the question is whether an agent can reliably discover,
understand, select, invoke, and—when explicitly applicable—transact with a public
service. Its score is separate from the established Quick Audit `overall_score`.
For paid services it compares resource-scoped pricing in public text, JSON-LD Offers,
capability manifests, and unsigned x402 challenge terms; separate product tiers may
have different prices. It never sends a payment signature or transfers funds.
The MCP server advertises `audit_agent_readiness` with strict schemas. Its call validates
the target and returns the canonical paid HTTP handoff; it does not provide a free full
audit or invoke any tool advertised by the audited target.

## Payment

- Protocol: x402 v2 (`PAYMENT-REQUIRED` response header carries base64 terms;
  pay by retrying with a `PAYMENT-SIGNATURE` request header; the settled response
  includes a base64 `PAYMENT-RESPONSE` receipt header).
- Safe Fetch price: $0.002 USDC per successful fetch (2000 atomic units).
- Page-to-Markdown Extraction price: $0.005 USDC per successful extraction (5000 atomic units).
- Structured Extraction price: $0.08 USDC per successful schema-conforming extraction (80000 atomic units).
- Quick Audit price: $0.015 USDC per successful audit (15000 atomic units).
- Screenshot & PDF Render price: $0.01 USDC per successful render (10000 atomic units).
- Agent Readiness price: $0.075 USDC per successful audit (75000 atomic units).
- Deep Page Audit price: $0.225 USDC per bounded compute reservation (225000 atomic units).
- Network: `eip155:8453` (Base mainnet). Asset: USDC at 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.
- Pay to: 0x3F8173bbb64ffAcA8793C9c46518Ba2369277E8B.
- Humans without a USDC wallet: a one-time $5 USD [Agent Readiness Report by card](https://www.santosautomation.com/agent-readiness/buy)
  (Stripe Checkout) — no account, emailed as a private tokened link. This is a human
  convenience; the machine-payable per-call price remains $0.075 USDC via x402.
  Refunds by email to info@santosautomation.com.
- Flow: request without payment returns HTTP 402; decode the `PAYMENT-REQUIRED`
  header for full terms (`accepts[0]`); sign an EIP-3009 transferWithAuthorization
  for the quoted amount; retry with `PAYMENT-SIGNATURE`. Any x402 v2 client
  (e.g. @x402/fetch with @x402/evm's ExactEvmScheme) automates this.
- The 402 also carries an x402 Bazaar discovery extension (input/output JSON
  Schemas) so catalogs can index this resource automatically.
- Payment settles only after a successful response — failed audits cost nothing.
- Legacy x402 v1 clients (X-PAYMENT header) are NOT supported as of 2026-07-17.

## Limitations

- llms.txt is a proposal, not a mandatory web standard. MCP Registry evidence is
  optional and the registry is currently preview infrastructure.
- OpenAPI assessment is bounded structural validation; it does not dereference
  remote schemas or execute examples.
- Audits a single public page per call; no crawling, no login-protected or private pages.
- No JavaScript rendering, Core Web Vitals, interaction testing, color-contrast
  analysis, full WCAG conformance, TLS analysis, or vulnerability scanning.
- Localhost, private-network, link-local, and cloud-metadata addresses are rejected
  (including via redirects). Only ports 80 and 443; no URLs with embedded credentials.
- 15-second fetch timeout, 5 redirects max, 5 MB response cap, 2048-char URL cap,
  HTML/XHTML/plain-text content only.
- Free demo and MCP preview tool: 1 audit per day per IP (shared quota).
- Structured Extraction truncates page content to 8000 characters and caps model
  output at 1024 tokens before extraction runs, regardless of the requested schema
  size — a very long page will be truncated before its later sections are seen.
  The caller's JSON Schema must also be self-contained (no external $ref) and
  under 4000 characters.
- robots.txt Disallow lines under /api/ and /v1/ target search-engine crawling of
  unlisted internals only. The audit endpoints — /api/audit, /api/audit/demo,
  /api/agent-readiness, /v1/audits, and /mcp — are explicitly Allowed and intended
  for direct agent/tool invocation.

## Roadmap

New capabilities are added as time allows, always under the same contract:
read-only, one-shot, single-page, x402 pay-per-success — no subscriptions and
no endpoints that send messages or act on a user's behalf. New endpoints appear
first in the OpenAPI specification and this file, and are indexed automatically
by x402 discovery catalogs. Capability requests: info@santosautomation.com.

## Support

- [Website](https://www.santosautomation.com): product landing and free demo audit
- [Terms, privacy, acceptable use, and retention](https://www.santosautomation.com/terms): legal and data-handling policies
- Email: info@santosautomation.com
- Operator: Santos Automation (Juan Santos) — custom x402 APIs, web apps,
  e-commerce, and automation systems for hire.