santos-audit-api

# 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, audit_agent_readiness, extract_page_markdown, extract_structured_data, feed_parse, link_map, summarize
- [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
- [MCP integration hub](https://www.santosautomation.com/integrations): one Remote MCP endpoint, seven tools, setup for every supported client
- [Grok & xAI integration](https://www.santosautomation.com/integrations/grok): register this MCP server as a Grok Remote MCP tool in one line — free previews, paid x402 handoff
- [Claude integration](https://www.santosautomation.com/integrations/claude): add this MCP server to Claude as a custom connector — same endpoint as the Grok integration

## MCP clients

This server is a standard Remote MCP server over Streamable HTTP and works with any
MCP-capable client. One endpoint and one registry listing serve every client — there is no
client-specific server. Published in the official MCP Registry as com.santosautomation/site-audit
(verify: https://registry.modelcontextprotocol.io/v0/servers?search=com.santosautomation/site-audit).

Claude — Claude.ai and Claude Code are configured separately; a connector added in one is
not visible to the other.
  Claude.ai:   Settings > Connectors > Add custom connector > https://api.santosautomation.com/mcp
  Claude Code: claude mcp add -s user --transport http santos https://api.santosautomation.com/mcp
No OAuth, no token, no key. Setup guide:
https://www.santosautomation.com/integrations/claude

Grok / xAI Remote MCP Tools:

    from xai_sdk.tools import mcp
    tools = [mcp(server_url="https://api.santosautomation.com/mcp", server_label="santos")]

Also usable from Claude, ChatGPT, and any custom MCP client. One tool is free:
audit_website_preview executes inline and returns a real audit, 1 call per day per calling IP
and no wallet required. Hosted agents share one egress address between all their users, so
treat it as a sample of the output rather than as capacity. Every other tool
(audit_agent_readiness, extract_page_markdown, extract_structured_data, feed_parse, link_map,
summarize) validates the target and returns the canonical x402 HTTP request; the calling agent
settles it in USDC on Base mainnet. MCP never moves funds.
Integration guide: https://www.santosautomation.com/integrations/grok

## 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
- [Batch Quick Intelligence Audit](https://api.santosautomation.com/api/audit/batch): $0.50 USDC flat per batch, synchronous — POST {"urls": ["https://example.com", ...]} with up to 50 URLs ($0.01/URL at full capacity); settles only when at least one audit succeeds
- [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
- [Santos Feed Parser](https://api.santosautomation.com/v1/feed?url=https%3A%2F%2Fexample.com%2Ffeed.xml): $0.003 USDC, synchronous — one feed URL (RSS 2.0, Atom, or JSON Feed) to normalized JSON with feed metadata and up to 50 items (GET ?url= or POST {"url"}); non-feed targets return 422 and never settle
- [Santos Link Map](https://api.santosautomation.com/v1/links?url=https%3A%2F%2Fexample.com): $0.003 USDC, synchronous — one HTML page to a categorized link map: every link (max 200) with kind internal/external plus topic tags (docs, pricing, api, careers, social, feed) and per-category counts
- [Santos Summarizer](https://api.santosautomation.com/v1/summarize): $0.033 USDC, synchronous — POST {"url": "https://example.com", "focus": "optional steering"} (or GET ?url=); Claude-generated structured summary with key facts, entities, and word count; non-HTML targets return 422 and never settle
- [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"}

## Free tools (no payment)

The free HTTP tier is RETIRED. The old /demo endpoints, the verified-email token flow, and
the llms.txt generator no longer serve results: the demo endpoints answer 402 naming the paid
successor, its price, and the exact URL to call, so an x402 client can pay and continue without
a human. The single remaining free surface is the MCP tool audit_website_preview, 1 call per
day per calling IP.

These stay free and unmetered — they cost nothing to serve and they make paid output verifiable:

- [Agent-Ready badge](https://api.santosautomation.com/v1/badge?url=https%3A%2F%2Fexample.com): free SVG shield of a site's latest public score — no quota; embed `[![badge](https://api.santosautomation.com/v1/badge?url=example.com)](https://www.santosautomation.com/reports/example.com)`
- [Report signature verification](https://api.santosautomation.com/v1/verify): free — POST a full report JSON, get {valid, url, score, signed_at}; 30/hour per IP
- [Public report archive](https://www.santosautomation.com/reports): every scored domain, full reports, no quota — read one before buying

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. To inspect the response
format before paying, read a completed report at
https://www.santosautomation.com/reports or call the free MCP tool
audit_website_preview.

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 FEED PARSER ($0.003, seconds) when you have a feed URL and need its
content as clean JSON rather than raw XML: monitoring blogs, news sources,
release feeds, or podcast feeds. It detects RSS 2.0, Atom, and JSON Feed and
returns normalized feed metadata plus up to 50 items with id, title, url,
published, summary, and author — through the same SSRF-guarded fetcher as
Safe Fetch. A target that is not a recognized feed returns 422 and is never
charged.

Choose LINK MAP ($0.003, seconds) when you need to understand a site's link
structure from one page: finding a target's docs, pricing, API reference,
careers page, social profiles, or feed URL before deciding what to fetch
next. It returns every link (max 200) with a kind (internal or external) and
topic tags (docs, pricing, api, careers, social, feed), plus counts for each
kind and topic — a site discovery step, not a crawler.

Choose SUMMARIZER ($0.033, seconds) when you need the gist of one page as
structured JSON rather than full content: triage before deeper extraction,
digest pipelines, or answering "what is this page about". It returns a
Claude-generated summary with title, key_facts, entities, and word_count; an
optional focus string steers the summary (e.g. "pricing plans"). Non-HTML
targets return 422 and are never charged.

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).
- Feed Parser price: $0.003 USDC per successful parse (3000 atomic units).
- Link Map price: $0.003 USDC per successful link map (3000 atomic units).
- Summarizer price: $0.033 USDC per successful summary (33000 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: one-time human reports by card — $9 USD Quick
  (Agent Readiness, fetch-based) or $29 USD Deep (Website Intelligence,
  browser-rendered) — [buy at /agent-readiness/buy](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.
- Humans can also subscribe to [Santos Monitoring](https://www.santosautomation.com/monitoring)
  by card — $9 USD/month: weekly re-audit of one URL with the same engine, an email
  alert when the score moves 5+ points, and a monthly digest. Cancel anytime via the
  manage link in every monitoring email.
- 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 MCP preview tool (audit_website_preview): 1 audit per day per calling IP.
- 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/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 the public report archive
- [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.