Answer Checkup Scan API

openapi: 3.2.0
info:
  title: Answer Checkup Scan API
  version: 0.1.0
  description: 'AI visibility scan and reports. AI-generated answers, measured via each engine''s API (OpenAI API with web search and Perplexity API). Paid endpoints use x402 v2 (HTTP 402, PAYMENT-REQUIRED / PAYMENT-SIGNATURE headers). Scan details (the checks and fixes for one free scan) cost $2.99, one time, paid by card through Stripe Checkout: POST /v1/checkout with product_tier "scan_unlock". Agent prices over x402 (USDC): Lite report 29 USDC, Full report 49 USDC, scan details 2.99 USDC.'
  contact:
    name: Answer Checkup
    email: hello@answercheckup.com
    url: https://answercheckup.com/
  license:
    name: Proprietary
servers:
- url: https://answercheckup.com
security: []
tags:
- name: Scan
paths:
  /v1/scan:
    post:
      operationId: scanSite
      summary: Free AI readiness scan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  example: https://example.com
      responses:
        '200':
          description: 'Scan result: score (0 to 100), grade and scan id. The checks and fixes unlock for $2.99 (GET /v1/scan/{scanId})'
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LockedScanView'
                - type: object
                  required:
                  - agentPrices
                  properties:
                    agentPrices:
                      type: string
                      description: Agent prices line, the same text as at the end of info.description
        '400':
          description: Invalid URL
        '429':
          description: 'Rate limit (free scan): 3 scans a minute, 10 an hour and 30 a day per IP address, and 5 an hour per scanned site. See retry-after.'
          headers:
            retry-after:
              schema:
                type: integer
              description: Seconds to wait
      tags:
      - Scan
    get:
      operationId: scanSiteGet
      summary: Free AI readiness scan (GET form)
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
        example: https://example.com
      responses:
        '200':
          description: 'Scan result: score (0 to 100), grade and scan id. The checks and fixes unlock for $2.99 (GET /v1/scan/{scanId})'
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LockedScanView'
                - type: object
                  required:
                  - agentPrices
                  properties:
                    agentPrices:
                      type: string
                      description: Agent prices line, the same text as at the end of info.description
        '400':
          description: Invalid URL
        '429':
          description: 'Rate limit (free scan): 3 scans a minute, 10 an hour and 30 a day per IP address, and 5 an hour per scanned site. See retry-after.'
          headers:
            retry-after:
              schema:
                type: integer
              description: Seconds to wait
      tags:
      - Scan
  /v1/scan/{scanId}:
    get:
      operationId: getScanDetails
      summary: 'One stored free scan: locked (grade and score) until its $2.99 unlock is paid…'
      parameters:
      - name: scanId
        in: path
        required: true
        schema:
          type: string
          pattern: ^scan_[a-f0-9]{32}$
      responses:
        '200':
          description: LockedScanView until unlocked; after the unlock the full ScanResult plus scanId, detailsLocked false, savedUrl and unlockedAt
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/LockedScanView'
                - $ref: '#/components/schemas/ScanResult'
        '400':
          description: Invalid scan id
        '404':
          description: Scan not found or expired (kept 30 days)
        '429':
          description: Rate limit. See retry-after.
      tags:
      - Scan
components:
  schemas:
    LockedScanView:
      type: object
      properties:
        scanId:
          type: string
          pattern: ^scan_[a-f0-9]{32}$
        url:
          type: string
        scannedAt:
          type: string
          format: date-time
        score:
          type: integer
          minimum: 0
          maximum: 100
        grade:
          type: string
        detailsLocked:
          type: boolean
          const: true
        unlock:
          type: object
          properties:
            priceUsd:
              type: number
            currency:
              type: string
            url:
              type: string
            checkout:
              type: object
              description: 'How to buy the details: POST to endpoint with body (product_tier and scan_id) plus the consent fields, which are required and given by the buyer (see ScanUnlockCheckoutRequest and consentText). Consent is never prefilled.'
              properties:
                method:
                  type: string
                endpoint:
                  type: string
                body:
                  type: object
                required:
                  type: array
                  items:
                    type: string
                consentText:
                  type: string
                  format: uri
            consent:
              type: object
    ScanResult:
      type: object
      properties:
        url:
          type: string
        score:
          type: integer
          minimum: 0
          maximum: 100
        grade:
          type: string
        checks:
          type: object
        scoreBreakdown:
          type: object
        fixes:
          type: array
          items:
            type: object
            properties:
              priority:
                type: string
                enum:
                - high
                - medium
                - low
              area:
                type: string
              fix:
                type: string