openapi: 3.2.0
info:
  title: Agent Ready NL Web API
  version: 1.0.0
  contact:
    name: Agent Ready
    url: https://agent-ready.dev/about#contact
    email: support@agent-ready.dev
  description: Programmatic access to agent-ready.dev scans.
  x-guidance: 'Scan any public website for AI agent-readability. POST /api/x402/scan with a JSON body {"url":"https://…"} and pay per scan with no account via x402 (X-PAYMENT header) or MPP (Authorization: Payment) — $0.02 for up to 25 pages, $0.25 for up to 250, USDC on Base mainnet. The same scan is available free under quota at POST /api/scan, or with an API key for Pro subscribers. Read-only; only public URLs are scanned.'
servers:
- url: https://agent-ready.dev
security:
- ApiKey: []
tags:
- name: NLWeb
paths:
  /api/v1/ask:
    get:
      operationId: askGet
      summary: Ask in natural language (NLWeb)
      description: 'NLWeb /ask endpoint, conventional GET form: /ask?query=. Natural-language search over Agent Ready''s own content (methodology, check registry, specs, and the content library — explainers, comparisons, how-to guides, glossary). Public — no API key required. Returns NLWeb result objects with a nested Schema.org `schema_object`. Set stream=true for Server-Sent Events. Also served at the root path /ask.'
      tags:
      - NLWeb
      security: []
      parameters:
      - schema:
          type: string
          example: how is the score calculated?
        required: true
        name: query
        in: query
      - schema:
          type: string
          enum:
          - list
          - summarize
        required: false
        name: mode
        in: query
      - schema:
          type: string
          enum:
          - methodology
          - checks
          - specs
          - llms-txt
          - check
          - page
        required: false
        name: itemType
        in: query
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
        required: false
        name: stream
        in: query
      responses:
        '200':
          description: An NLWeb answer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
        '400':
          description: Missing or invalid query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded. Response carries `Retry-After` (seconds) plus `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Back off using exponential delay with jitter — see the Rate limits & retry section in the docs.
          headers:
            X-RateLimit-Limit:
              description: Maximum number of requests permitted in the current window.
              schema:
                type: integer
                example: 10
            X-RateLimit-Remaining:
              description: Requests remaining in the current window. `0` on a 429 response.
              schema:
                type: integer
                example: 0
            Retry-After:
              description: Seconds until a slot frees in the sliding window (RFC 7231 §7.1.3). Honour this before retrying.
              schema:
                type: integer
                example: 42
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable. Retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: askPost
      summary: Ask in natural language (NLWeb), JSON-body form
      description: 'NLWeb /ask endpoint, JSON-body form: { query: { q }, prefer: { mode, streaming } }. Same response as the GET form. Public — no API key required.'
      tags:
      - NLWeb
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
      responses:
        '200':
          description: An NLWeb answer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
        '400':
          description: Invalid /ask request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No results (NLWeb failure envelope).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
        '429':
          description: Rate limit exceeded. Response carries `Retry-After` (seconds) plus `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Back off using exponential delay with jitter — see the Rate limits & retry section in the docs.
          headers:
            X-RateLimit-Limit:
              description: Maximum number of requests permitted in the current window.
              schema:
                type: integer
                example: 10
            X-RateLimit-Remaining:
              description: Requests remaining in the current window. `0` on a 429 response.
              schema:
                type: integer
                example: 0
            Retry-After:
              description: Seconds until a slot frees in the sliding window (RFC 7231 §7.1.3). Honour this before retrying.
              schema:
                type: integer
                example: 42
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable. Retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AskRequest:
      type: object
      properties:
        query:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 2000
          - type: object
            properties:
              text:
                type: string
                minLength: 1
                maxLength: 2000
              q:
                type: string
                minLength: 1
                maxLength: 2000
              itemType:
                type: string
                enum:
                - methodology
                - checks
                - specs
                - llms-txt
                - check
                - page
                - any
                description: Optional filter mapping to an Agent Ready corpus type. 'any' (default) searches everything.
              site:
                type: string
            required:
            - text
          - type: object
            properties:
              q:
                type: string
                minLength: 1
                maxLength: 2000
              itemType:
                type: string
                enum:
                - methodology
                - checks
                - specs
                - llms-txt
                - check
                - page
                - any
                description: Optional filter mapping to an Agent Ready corpus type. 'any' (default) searches everything.
              site:
                type: string
            required:
            - q
          example:
            text: how is the agent readability score calculated?
        mode:
          type: string
          enum:
          - list
          - summarize
          - generate
        streaming:
          anyOf:
          - type: boolean
          - type: string
        itemType:
          type: string
          enum:
          - methodology
          - checks
          - specs
          - llms-txt
          - check
          - page
          - any
          description: Optional filter mapping to an Agent Ready corpus type. 'any' (default) searches everything.
        site:
          type: string
        query_id:
          type: string
        prev:
          type: string
        decontextualized_query:
          type: string
        prefer:
          type: object
          properties:
            streaming:
              type: boolean
            format:
              type: string
              enum:
              - json
            mode:
              type: string
              enum:
              - list
              - summarize
            language:
              type: string
        context:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                - user
                - assistant
              content:
                type: string
            required:
            - role
            - content
        meta:
          type: object
          properties:
            version:
              type: string
            session:
              type: string
            user:
              type: string
      required:
      - query
      description: 'NLWeb /ask request. The spec shape is `{ query: { text } }`; the legacy string and `{ query: { q } }` forms plus a `prefer` envelope are also accepted.'
    AskResponse:
      anyOf:
      - $ref: '#/components/schemas/AskAnswer'
      - $ref: '#/components/schemas/AskFailure'
      description: Either an answer or a failure.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: subscription_required
            message:
              type: string
          required:
          - code
          - message
      required:
      - error
      description: Structured error envelope.
    SchemaObject:
      type: object
      properties:
        '@context':
          type: string
          enum:
          - https://schema.org
        '@type':
          type: string
          enum:
          - Article
          - TechArticle
          - WebPage
        name:
          type: string
        url:
          type: string
        description:
          type: string
      required:
      - '@context'
      - '@type'
      - name
      - url
      description: Schema.org JSON-LD for a result.
    AskResult:
      type: object
      properties:
        url:
          type: string
        name:
          type: string
        site:
          type: string
        score:
          type: number
          description: Relevance score (BM25).
        description:
          type: string
        schema_object:
          $ref: '#/components/schemas/SchemaObject'
      required:
      - url
      - name
      - site
      - score
      - description
      - schema_object
      description: An NLWeb result object.
    AskMeta:
      type: object
      properties:
        response_type:
          type: string
          enum:
          - answer
          - failure
          - elicitation
          - promise
        version:
          type: string
          enum:
          - '0.55'
        mode:
          type: string
          enum:
          - list
          - summarize
      required:
      - response_type
      - version
      - mode
      description: NLWeb response envelope metadata.
    AskAnswer:
      type: object
      properties:
        _meta:
          $ref: '#/components/schemas/AskMeta'
        query_id:
          type: string
        site:
          type: string
        mode:
          type: string
          enum:
          - list
          - summarize
        query:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/AskResult'
        summary:
          type: string
          description: Present when mode is 'summarize'.
      required:
      - _meta
      - query_id
      - site
      - mode
      - query
      - results
      description: Successful NLWeb answer.
    AskFailure:
      type: object
      properties:
        _meta:
          $ref: '#/components/schemas/AskMeta'
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - NO_RESULTS
              - INVALID_QUERY
              - RATE_LIMITED
              - TIMEOUT
              - INTERNAL
            message:
              type: string
          required:
          - code
          - message
      required:
      - _meta
      - error
      description: NLWeb failure envelope.
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: ar_live_<prefix>_<secret>
      description: API key issued from /dashboard/api-keys. Pro subscription required.