santosautomation-com Structured Extraction API

openapi: 3.2.0
info:
  title: Santos Website Intelligence Structured Extraction 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: Structured Extraction
paths:
  /v1/extract/structured:
    post:
      operationId: extractStructuredData
      tags:
      - Structured Extraction
      summary: Extract structured JSON from one page against your JSON Schema ($0.08 USDC via…
      description: 'Requires x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE); settles only when the extracted data validates against your schema — a schema that can''t be satisfied from the page costs nothing. Fetches one public page (SSRF-guarded, 15s timeout, 5MB cap), truncates readability-isolated Markdown to 8000 characters, then calls Claude with forced tool-use against your schema (max 1024 output tokens). The caller''s schema must be a self-contained JSON Schema object (type: object, no $ref, under 4000 characters) or the request 400s before any fetch or model call. No GET variant — the schema doesn''t fit cleanly in query params.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              - schema
              properties:
                url:
                  type: string
                  format: uri
                  description: Public HTTP/HTTPS page. Private-network/metadata targets rejected free of charge.
                schema:
                  type: object
                  description: 'Self-contained JSON Schema (type: object, no $ref) describing the fields to extract. Max 4000 characters.'
      responses:
        '200':
          description: Extraction complete; the extracted data conforms to the caller's schema.
          content:
            application/json:
              schema:
                type: object
                required:
                - schema_version
                - url
                - final_url
                - http_status
                - data
                - model
                - fetched_at
                - timing_ms
                properties:
                  schema_version:
                    type: string
                    const: 1.0.0
                  url:
                    type: string
                  final_url:
                    type: string
                    format: uri
                  http_status:
                    type: integer
                  data:
                    type: object
                    description: Extracted fields, matching the caller's schema.
                  model:
                    type: string
                  fetched_at:
                    type: string
                    format: date-time
                  timing_ms:
                    type: object
                    properties:
                      fetch:
                        type: integer
                      llm:
                        type: integer
                      total:
                        type: integer
        '400':
          description: Invalid or blocked target URL, or an invalid/oversized/uncompilable caller schema (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.
        '422':
          description: Model output did not validate against the caller's schema (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
        '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