santosautomation-com Free Tools API

openapi: 3.2.0
info:
  title: Santos Website Intelligence Free Tools 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: Free Tools
paths:
  /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://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