santosautomation-com Safe Fetch API

openapi: 3.2.0
info:
  title: Santos Website Intelligence Safe Fetch API
  version: 2.18.0
  description: 'AI Website Intelligence for determining whether public websites can be discovered, understood, trusted, and used by agents. Twelve 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
tags:
- name: Safe Fetch
paths:
  /v1/fetch:
    get:
      operationId: safeFetchUrl
      tags:
      - Safe Fetch
      summary: Fetch one public URL through the hardened safe-fetcher ($0.002 USDC via x402…
      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