openapi: 3.2.0
info:
  title: DomScan Agent Readiness API
  description: DomScan is a domain intelligence API providing domain analysis tools.
  version: 2.15.0
  contact:
    name: DomScan Support
    url: https://domscan.net
    email: support@domscan.net
  termsOfService: https://domscan.net/legal/terms
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://domscan.net
  description: Production server
security:
- apiKey: []
tags:
- name: Agent Readiness
paths:
  /v1/agent-readiness:
    get:
      tags:
      - Agent Readiness
      summary: Score website agent readiness across four evidence dimensions
      description: Score a public website from 0 to 100 across discoverability, content, access policy, and capabilities. The bounded audit covers more than 35 checks, including sitemaps, Markdown delivery, crawler policy, WebMCP, remote MCP, OpenAPI, API catalogs, OAuth metadata, Agent Skills, and page structure. Unknown evidence is excluded from the score and lowers confidence. The audit does not execute discovered tools and is not an SEO ranking.
      operationId: checkAgentReadiness
      x-required-any-of:
      - - url
      - - domain
      parameters:
      - name: url
        description: Full public HTTP(S) URL to check. Takes precedence over domain.
        in: query
        schema:
          type: string
          format: uri
          maxLength: 2048
        example: https://example.com
      - name: domain
        description: Public domain or hostname to check when url is omitted.
        in: query
        schema:
          type: string
          maxLength: 253
        example: example.com
      - name: skip_cache
        in: query
        description: Set to 1 to bypass cached readiness evidence.
        schema:
          type: string
          enum:
          - '1'
      responses:
        '200':
          description: Transparent agent readiness score, dimension scores, checks, evidence, caveats, and recommendations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentReadinessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/BadGateway'
      x-domscan-credits:
        model: per_request
        default: 3
components:
  responses:
    RateLimited:
      description: Rate limit exceeded. Free accounts can sustain 120 requests per minute per account with a burst capacity of 60. Free bulk traffic is additionally limited to 20 requests per minute per account across all bulk endpoints and 100 per minute per IPv4 address or IPv6 /56 network. Paid accounts can sustain 600 requests per minute with a burst capacity of 120.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        X-RateLimit-Plan:
          schema:
            type: string
            enum:
            - free
            - paid
          description: The account plan whose policy was applied.
        X-RateLimit-Limit:
          schema:
            type: integer
          description: The immediate burst capacity, or the active bulk fixed-window limit when a bulk-specific limit is exceeded.
        X-RateLimit-Remaining:
          schema:
            type: integer
            example: 0
          description: Immediate burst tokens remaining, or requests remaining in the active bulk fixed window.
        X-RateLimit-Policy:
          schema:
            type: string
          description: Machine-readable summary of the active tier and limit policy.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: RATE_LIMITED
              message: Rate limit exceeded. Please wait before making more requests.
    BadGateway:
      description: The public website could not be fetched or returned an unusable response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: FETCH_ERROR
              message: Failed to fetch website
    PaymentRequired:
      description: Insufficient credits for this request
      headers:
        X-Credits-Remaining:
          schema:
            type: integer
          description: Credits remaining on your API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: INSUFFICIENT_CREDITS
              message: Insufficient credits. This endpoint costs 2 credits but you have 0. Purchase more at https://domscan.net/billing or wait for your monthly reset.
              credits_remaining: 0
              credits_required: 2
              purchase_url: https://domscan.net/billing
    Unauthorized:
      description: 'Authentication required. All API endpoints require a valid API key (x-api-key header or Authorization: Bearer) or an active session cookie.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: AUTH_REQUIRED
              message: 'Authentication required. Provide an API key via x-api-key header or Authorization: Bearer header.'
              docs: https://domscan.net/docs/authentication
              get_key: https://domscan.net/login
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: BAD_REQUEST
              message: Invalid domain format
              suggestion: Domain must be a valid format like example.com
  schemas:
    AgentReadinessCheck:
      type: object
      required:
      - id
      - dimension
      - state
      - weight
      - method
      - checked_url
      - http_status
      - evidence
      - caveats
      - reference
      - maturity
      properties:
        id:
          type: string
        dimension:
          type: string
          enum:
          - discoverability
          - content
          - access_policy
          - capabilities
        state:
          type: string
          enum:
          - pass
          - warn
          - fail
          - unknown
          - not_applicable
        weight:
          type: integer
          minimum: 1
          maximum: 3
        method:
          type: string
        checked_url:
          type:
          - string
          - 'null'
          format: uri
        http_status:
          type:
          - integer
          - 'null'
        evidence:
          type: array
          items:
            type: string
        caveats:
          type: array
          items:
            type: string
        reference:
          type: string
        maturity:
          type: string
          enum:
          - standard
          - specification
          - proposal
          - draft
          - practice
    AgentReadinessFoundation:
      type: object
      required:
      - state
      - evidence
      properties:
        state:
          type: string
          enum:
          - pass
          - warn
          - fail
          - unknown
        evidence:
          type: array
          items:
            type: string
    AgentReadinessResponse:
      type: object
      required:
      - requested_url
      - final_url
      - checked_at
      - outcome
      - fetch_state
      - http_status
      - summary
      - signals
      - foundations
      - dimensions
      - checks
      - recommendations
      - meta
      properties:
        requested_url:
          type: string
          format: uri
        final_url:
          type: string
          format: uri
        checked_at:
          type: string
          format: date-time
        outcome:
          type: string
          enum:
          - complete
          - partial
          - unavailable
        fetch_state:
          type: string
          enum:
          - ok
          - blocked
          - http_error
          - non_html
          - empty
          - unknown
        http_status:
          type:
          - integer
          - 'null'
        summary:
          type: object
          required:
          - coverage
          - detected_signals
          - total_signals
          - score
          - rating
          - confidence
          - passed_checks
          - warning_checks
          - failed_checks
          - unknown_checks
          - not_applicable_checks
          description: The readiness score uses conclusive applicable checks. Unknown checks are excluded from the score and reduce the separate confidence percentage.
          properties:
            coverage:
              type: string
              enum:
              - broad
              - multi_channel
              - single_channel
              - none_detected
              - indeterminate
            detected_signals:
              type: integer
              minimum: 0
              maximum: 12
            total_signals:
              type: integer
              enum:
              - 12
            score:
              type:
              - integer
              - 'null'
              minimum: 0
              maximum: 100
            rating:
              type: string
              enum:
              - excellent
              - good
              - fair
              - needs_improvement
              - indeterminate
            confidence:
              type: integer
              minimum: 0
              maximum: 100
            passed_checks:
              type: integer
              minimum: 0
            warning_checks:
              type: integer
              minimum: 0
            failed_checks:
              type: integer
              minimum: 0
            unknown_checks:
              type: integer
              minimum: 0
            not_applicable_checks:
              type: integer
              minimum: 0
        signals:
          type: object
          required:
          - webmcp
          - remote_mcp
          - openapi
          - llms_txt
          - api_catalog
          - mcp_server_card
          - agent_skills
          - oauth
          - markdown
          - web_bot_auth
          - sitemap_markdown
          - agent_guide
          properties:
            webmcp:
              $ref: '#/components/schemas/AgentReadinessSignal'
            remote_mcp:
              $ref: '#/components/schemas/AgentReadinessSignal'
            openapi:
              $ref: '#/components/schemas/AgentReadinessSignal'
            llms_txt:
              $ref: '#/components/schemas/AgentReadinessSignal'
            api_catalog:
              $ref: '#/components/schemas/AgentReadinessSignal'
            mcp_server_card:
              $ref: '#/components/schemas/AgentReadinessSignal'
            agent_skills:
              $ref: '#/components/schemas/AgentReadinessSignal'
            oauth:
              $ref: '#/components/schemas/AgentReadinessSignal'
            markdown:
              $ref: '#/components/schemas/AgentReadinessSignal'
            web_bot_auth:
              $ref: '#/components/schemas/AgentReadinessSignal'
            sitemap_markdown:
              $ref: '#/components/schemas/AgentReadinessSignal'
            agent_guide:
              $ref: '#/components/schemas/AgentReadinessSignal'
        foundations:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentReadinessFoundation'
        dimensions:
          type: object
          required:
          - discoverability
          - content
          - access_policy
          - capabilities
          properties:
            discoverability:
              $ref: '#/components/schemas/AgentReadinessDimensionScore'
            content:
              $ref: '#/components/schemas/AgentReadinessDimensionScore'
            access_policy:
              $ref: '#/components/schemas/AgentReadinessDimensionScore'
            capabilities:
              $ref: '#/components/schemas/AgentReadinessDimensionScore'
        checks:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentReadinessCheck'
        recommendations:
          type: array
          items:
            type: object
            required:
            - code
            - severity
            properties:
              code:
                type: string
              severity:
                type: string
                enum:
                - high
                - medium
                - low
        meta:
          type: object
          required:
          - cached
          - fetch_path
          - duration_ms
          - probe_count
          - body_truncated
          - source_version
          - last_verified
          - rubric_version
          - max_probes
          properties:
            cached:
              type: boolean
            fetch_path:
              type: string
              enum:
              - primary
              - fallback
              - unknown
            duration_ms:
              type: integer
            probe_count:
              type: integer
            body_truncated:
              type: boolean
            source_version:
              type: string
            last_verified:
              type: string
              format: date
            rubric_version:
              type: string
            max_probes:
              type: integer
              minimum: 1
    AgentReadinessSignal:
      type: object
      required:
      - status
      - validation
      - method
      - checked_url
      - http_status
      - evidence
      - caveats
      properties:
        status:
          type: string
          enum:
          - detected
          - not_detected
          - unknown
          - unchecked
          description: not_detected means only that the documented bounded probes found no signal. It is not proof of absence.
        validation:
          type: string
          enum:
          - confirmed
          - advertised
          - malformed
          - runtime_required
          - not_applicable
        method:
          type: string
        checked_url:
          type:
          - string
          - 'null'
          format: uri
        http_status:
          type:
          - integer
          - 'null'
        evidence:
          type: array
          items:
            type: string
        caveats:
          type: array
          items:
            type: string
    AgentReadinessDimensionScore:
      type: object
      required:
      - score
      - confidence
      - passed
      - warned
      - failed
      - unknown
      - not_applicable
      - checks
      properties:
        score:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        confidence:
          type: integer
          minimum: 0
          maximum: 100
        passed:
          type: integer
          minimum: 0
        warned:
          type: integer
          minimum: 0
        failed:
          type: integer
          minimum: 0
        unknown:
          type: integer
          minimum: 0
        not_applicable:
          type: integer
          minimum: 0
        checks:
          type: array
          items:
            type: string
    ErrorResponse:
      type: object
      description: Standard error response format
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code for programmatic handling
              example: INVALID_DOMAIN
            type:
              type: string
              enum:
              - authentication_error
              - credits_error
              - permission_error
              - not_found_error
              - conflict_error
              - rate_limit_error
              - timeout_error
              - validation_error
              - upstream_error
              - api_error
              - request_error
              description: Stable error category used by official SDK subclasses
            message:
              type: string
              description: Human-readable error message
              example: Invalid domain format
            status:
              type: integer
              minimum: 400
              maximum: 599
              description: HTTP status repeated in the JSON error for queue and log processors
            retryable:
              type: boolean
              description: Whether retrying can be appropriate after applying retry guidance
            request_id:
              type: string
              description: Request identifier matching the X-Request-Id response header
            suggestion:
              type: string
              description: Suggestion for fixing the error
            details:
              type: object
              description: Optional structured context for the error
              additionalProperties: true
            retry_after:
              type: integer
              minimum: 0
              description: Seconds to wait before retrying when the error is temporary
              example: 300
            docs_url:
              type: string
              description: Link to relevant documentation
              example: /docs#parameters
          required:
          - type
          - code
          - message
          - status
          - retryable
          - request_id
          - docs_url
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key for authentication. Get yours free at https://domscan.net. Also accepts Authorization: Bearer header.'
    sessionCookie:
      type: apiKey
      in: cookie
      name: session
      description: Active DomScan browser session. Used by account-management endpoints.
externalDocs:
  description: Full API Documentation
  url: https://domscan.net/docs
x-rapidapi-product: domscan
x-domscan-rate-limits:
  free:
    general:
      scope: account
      sustained_requests_per_minute: 120
      burst_capacity: 60
      shared_across_api_keys_and_sessions: true
    bulk:
      scope: all bulk endpoints combined
      account_requests_per_minute: 20
      network_requests_per_minute: 100
      ipv6_network_prefix: 56
  paid:
    general:
      scope: API key for key-authenticated requests; IP for browser sessions
      sustained_requests_per_minute: 600
      burst_capacity: 120
    free_bulk_budget_applies: false
  response:
    status: 429
    retry_header: Retry-After
    headers_on_every_authenticated_response:
    - X-RateLimit-Plan
    - X-RateLimit-Limit
    - X-RateLimit-Remaining
    - X-RateLimit-Policy
    burst_headers:
    - X-RateLimit-Limit
    - X-RateLimit-Remaining
    policy_header: X-RateLimit-Policy
x-domscan-response-metadata:
  compatibility: additive response headers; established JSON success bodies are unchanged
  headers:
    X-Request-Id: Unique request identifier for logs and support
    X-API-Version: DomScan API release version
    X-Response-Time: Server processing duration in milliseconds
    X-Credits-Requested: Credits requested before refund settlement
    X-Credits-Charged: Credits retained after settlement
    X-Credits-Refunded: Credits returned during settlement
    X-Credits-Remaining: Authenticated account balance after the request
    X-Data-Freshness: fresh, cached, stale, mixed, or unknown
    X-RateLimit-Limit: Active burst capacity
    X-RateLimit-Remaining: Remaining burst capacity
    X-RateLimit-Plan: Active plan, or not_applicable before authentication
    X-RateLimit-Policy: Machine-readable active rate policy