santosautomation-com Agent Readiness API

openapi: 3.2.0
info:
  title: Santos Website Intelligence Agent Readiness 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: Agent Readiness
paths:
  /api/agent-readiness:
    get:
      operationId: auditAgentReadiness
      tags:
      - Agent Readiness
      summary: Assess public agent-facing interfaces ($0.075 USDC via x402)
      description: 'Requires $0.075 USDC through x402 v2 and settles only after a successful audit response. Classifies the target before scoring and evaluates only applicable surfaces: discovery/docs, structured identity, APIs, MCP, operational trust, and machine commerce. For paid surfaces it normalizes public pricing claims and compares only claims scoped to the same paid resource against an unsigned x402 challenge. The quick pass performs at most eight additional bounded public requests. It never authenticates, creates accounts, submits forms, signs target payments, transfers funds to the target, or invokes advertised MCP/business tools. llms.txt is treated as a proposal and the MCP Registry as preview infrastructure.'
      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: depth
        in: query
        required: false
        schema:
          type: string
          enum:
          - quick
          default: quick
      - name: public
        in: query
        required: false
        schema:
          type: string
          enum:
          - '1'
          - 'true'
          - 'yes'
          - 'on'
          - '0'
          - 'false'
        description: 'Opt in to the public leaderboard: the signed report replaces this domain''s listing at https://www.santosautomation.com/reports/{domain}. Off by default. The outcome is reported in the X-Santos-Public-Listing response header (not-requested | listed; url=… | failed); the signed body is unchanged. A published Agent Readiness report no longer unlocks free remediation.'
      responses:
        '200':
          description: Versioned Agent Readiness result with additive Website Intelligence presentation fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentReadinessResult'
        '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
        '402':
          description: Payment required. PAYMENT-REQUIRED contains x402 v2 terms for $0.075 USDC (75000 atomic units) on eip155:8453.
        '502':
          description: Target or required public interface was unreachable.
          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: Bounded audit timed out.
          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
  /api/audit/remediate:
    post:
      operationId: remediateAiReadiness
      tags:
      - Agent Readiness
      summary: Generate llms.txt and Organization JSON-LD for failed AI Readiness layers…
      description: 'Pure generation: the target domain is never fetched. llms.txt is returned when discoverable or callable failed, Organization JSON-LD when understandable failed. Access: include `report` (a signed, never-published /api/agent-readiness report for the same domain) for free use, 5 uses per report and 30 report attempts per IP per hour; otherwise x402 v2 payment (base64 PAYMENT-REQUIRED challenge header; retry with PAYMENT-SIGNATURE), settled only on a successful response. Unpaid requests always receive the 402 challenge before validation.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domain
              - siteDescription
              - failedLayers
              properties:
                domain:
                  type: string
                  maxLength: 253
                  description: Bare domain or origin (https://example.com). IPs, paths and credentials are rejected.
                siteDescription:
                  type: string
                  minLength: 1
                  maxLength: 1000
                failedLayers:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum:
                    - discoverable
                    - understandable
                    - callable
                existingEndpoints:
                  type: array
                  maxItems: 100
                  items:
                    type: object
                    required:
                    - path
                    - method
                    - desc
                    properties:
                      path:
                        type: string
                        maxLength: 512
                        description: Absolute path starting with /; no query, fragment, spaces or brackets.
                      method:
                        type: string
                        enum:
                        - GET
                        - POST
                      desc:
                        type: string
                        maxLength: 300
                report:
                  type: object
                  description: Optional signed, unpublished /api/agent-readiness report for the same domain.
      responses:
        '200':
          description: Remediation generated. On the x402 path the PAYMENT-RESPONSE header carries the settlement receipt.
          content:
            application/json:
              schema:
                type: object
                properties:
                  domain:
                    type: string
                  origin:
                    type: string
                  failedLayers:
                    type: array
                    items:
                      type: string
                  artifacts:
                    type: object
                    properties:
                      llmsTxt:
                        type:
                        - object
                        - 'null'
                        properties:
                          addresses:
                            type: array
                            items:
                              type: string
                          path:
                            type: string
                            const: /llms.txt
                          contentType:
                            type: string
                          content:
                            type: string
                      jsonLd:
                        type:
                        - object
                        - 'null'
                        properties:
                          addresses:
                            type: array
                            items:
                              type: string
                          placement:
                            type: string
                            const: head
                          content:
                            type: string
                          data:
                            type: object
                  warnings:
                    type: array
                    items:
                      type: string
                  access:
                    type: object
                    properties:
                      mode:
                        type: string
                        enum:
                        - x402
                        - report
        '400':
          description: Invalid JSON or request (INVALID_JSON, INVALID_REQUEST with per-field details).
          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. PAYMENT-REQUIRED contains x402 v2 terms for $0.02 USDC on eip155:8453.
        '403':
          description: 'Report rejected: INVALID_REPORT, REPORT_DOMAIN_MISMATCH, REPORT_PUBLISHED, or REPORT_ALLOWANCE_USED.'
          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
        '413':
          description: Body over 1 MB (BODY_TOO_LARGE).
          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
        '415':
          description: Content-Type must be application/json (UNSUPPORTED_MEDIA_TYPE).
          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: Report path limited to 30 attempts per IP per hour (RATE_LIMITED).
          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: Report check unavailable (REPORT_CHECK_UNAVAILABLE) or route not enabled (SERVICE_UNAVAILABLE).
          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
components:
  schemas:
    AgentReadinessResult:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: https://api.santosautomation.com/schemas/agent-readiness-result-1.0.0.json
      title: AgentReadinessResult
      type: object
      required:
      - schema_version
      - target
      - profile
      - readiness_level
      - score
      - grade
      - confidence
      - tested_coverage_percent
      - applicability
      - subscores
      - interfaces
      - findings
      - recommended_actions
      - limitations
      properties:
        schema_version:
          type: string
          const: 1.0.0
        website_intelligence_score:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        website_intelligence:
          type: object
          description: Additive AI Website Intelligence presentation with four dimensions, coverage, confidence, and prioritized fixes.
          properties:
            schema_version:
              type: string
              const: 1.0.0
            score:
              type:
              - integer
              - 'null'
              minimum: 0
              maximum: 100
            dimensions:
              type: object
              properties:
                discoverable:
                  type:
                  - integer
                  - 'null'
                  minimum: 0
                  maximum: 100
                understandable:
                  type:
                  - integer
                  - 'null'
                  minimum: 0
                  maximum: 100
                callable:
                  type:
                  - integer
                  - 'null'
                  minimum: 0
                  maximum: 100
                trustworthy:
                  type:
                  - integer
                  - 'null'
                  minimum: 0
                  maximum: 100
        target:
          type: object
          required:
          - requested_url
          - canonical_origin
          - final_url
          properties:
            requested_url:
              type: string
            canonical_origin:
              type: string
              format: uri
            final_url:
              type: string
              format: uri
          additionalProperties: false
        profile:
          type: string
          enum:
          - general_website
          - documentation_site
          - api_provider
          - mcp_provider
          - agent_commerce_provider
        readiness_level:
          type: object
          required:
          - level
          - name
          properties:
            level:
              type: integer
              minimum: 0
              maximum: 4
            name:
              type: string
          additionalProperties: false
        score:
          type: integer
          minimum: 0
          maximum: 100
        grade:
          type: string
          enum:
          - A
          - B
          - C
          - D
          - F
        confidence:
          type: number
          minimum: 0
          maximum: 1
        tested_coverage_percent:
          type: integer
          minimum: 0
          maximum: 100
        applicability:
          type: object
          additionalProperties:
            type: string
            enum:
            - tested
            - not_applicable
            - unknown
        subscores:
          type: object
          additionalProperties:
            type: integer
            minimum: 0
            maximum: 100
        interfaces:
          type: object
        findings:
          type: array
          items:
            type: object
            required:
            - id
            - category
            - severity
            - confidence
            - status
            - title
            - recommendation
            properties:
              id:
                type: string
              category:
                type: string
              severity:
                type: string
                enum:
                - info
                - low
                - moderate
                - high
              confidence:
                type: string
                enum:
                - low
                - medium
                - high
              status:
                type: string
                enum:
                - pass
                - fail
                - unknown
                - not_applicable
              title:
                type: string
              evidence:
                type: object
              recommendation:
                type: string
        recommended_actions:
          type: array
          items:
            type: object
        limitations:
          type: array
          items:
            type: string
        fetch_budget:
          type: object