santosautomation-com Link Map API

openapi: 3.2.0
info:
  title: Santos Website Intelligence Link Map 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: Link Map
paths:
  /v1/links:
    get:
      operationId: mapPageLinks
      tags:
      - Link Map
      summary: Map one page's links into a categorized link map ($0.003 USDC via x402…
      description: 'Requires x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE); settles only on a successful response. Fetches one public HTML page (SSRF-guarded, 15s timeout, 5MB cap) and returns a categorized link map: every link resolved, deduped, and classified by kind (internal or external) plus topic tags (docs, pricing, api, careers, social, feed), with counts for each kind and topic — up to 200 links. Built for site-structure discovery: finding a target''s docs, pricing, API, careers, social profiles, or feed URLs in one call. 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: Link map complete.
          content:
            application/json:
              schema:
                type: object
                required:
                - schema_version
                - url
                - final_url
                - http_status
                - total_links
                - counts
                - links
                properties:
                  schema_version:
                    type: string
                    const: 1.0.0
                  url:
                    type: string
                  final_url:
                    type: string
                    format: uri
                  http_status:
                    type: integer
                  total_links:
                    type: integer
                    maximum: 200
                  counts:
                    type: object
                    properties:
                      internal:
                        type: integer
                      external:
                        type: integer
                      docs:
                        type: integer
                      pricing:
                        type: integer
                      api:
                        type: integer
                      careers:
                        type: integer
                      social:
                        type: integer
                      feed:
                        type: integer
                  links:
                    type: array
                    maxItems: 200
                    items:
                      type: object
                      required:
                      - url
                      - kind
                      properties:
                        url:
                          type: string
                        text:
                          type: string
                        kind:
                          type: string
                          enum:
                          - internal
                          - external
                        topics:
                          type: array
                          items:
                            type: string
                            enum:
                            - docs
                            - pricing
                            - api
                            - careers
                            - social
                            - feed
        '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