santosautomation-com Screenshot & PDF Render API

openapi: 3.2.0
info:
  title: Santos Website Intelligence Screenshot & PDF Render 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: Screenshot & PDF Render
paths:
  /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…
      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