ayushrai-site Ask API

openapi: 3.2.0
info:
  title: Ayush Rai public Ask API
  version: 1.0.0
  description: 'Read-only API over the same public content as Ayush Rai''s website. Unverified award metrics are omitted. There is no separate dataset for this API.


    Access: Free and public. No account or API key is needed because every endpoint is read-only over published content. There is no separate test environment or paid tier. Clients may cache responses for five minutes. REST responses grant CORS only to the site''s own origins, so call the REST API from a server, an agent, or the CLI rather than from a browser page on another site. The MCP endpoint and its Server Card allow any origin.


    Rate limits: 60 requests per 60 seconds per client address, counted per server instance. Every response carries RateLimit-Policy and RateLimit headers (draft-ietf-httpapi-ratelimit-headers-11). Over the limit, the API returns 429 with a Retry-After header in seconds and error code rate_limited.


    Errors: every error body is { "error": { "code", "message", "hint", "docs" } }. code is stable; hint says how to fix the request.


    Versioning: Versioned in the URL path. /api/v1 is stable: fields may be added, but none are removed or renamed. Breaking changes ship under a new path such as /api/v2. A replaced version keeps working for at least 90 days; during that window its responses carry Deprecation and Sunset headers and a Link with rel="successor-version", and the dates are listed on /developers. The unversioned /api/search and /api/projects are aliases of v1 and follow the same policy. No version is deprecated today.


    MCP: the same project and search tools are available over Streamable HTTP at POST /api/mcp. Its Server Card is at GET /api/mcp/server-card.'
  contact:
    name: Ayush Rai
    email: ayushrai0211@gmail.com
    url: https://www.ayushrai.site/developers/
servers:
- url: https://www.ayushrai.site
security: []
tags:
- name: Ask
paths:
  /ask:
    get:
      operationId: askGet
      summary: NLWeb-shaped lexical ask (GET)
      description: Natural-language query over the same lexical index as /api/v1/search. Not generative. Pass query or q. Responses include _meta.version (0.55) and _meta.response_type.
      parameters:
      - name: query
        in: query
        required: false
        schema:
          type: string
          maxLength: 200
      - name: q
        in: query
        required: false
        description: Alias for query
        schema:
          type: string
          maxLength: 200
      - name: streaming
        in: query
        required: false
        description: Pass true for a text/event-stream response (start, result, complete events).
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: 'NLWeb conversational_search answer or failure. With streaming, text/event-stream frames: start (_meta.streaming true), result ({ index, item }) per hit or error, then complete.'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
            text/event-stream:
              schema:
                type: string
        '405':
          description: Unsupported HTTP method. error.code is method_not_allowed. /ask accepts GET, HEAD, and POST.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
        '429':
          description: Rate limit exceeded. error.code is rate_limited.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
      tags:
      - Ask
    post:
      operationId: askPost
      summary: NLWeb-shaped lexical ask (POST)
      description: 'Same as GET /ask. Body may be { "query": "…" }, { "query": { "text": "…" } }, or { "q": "…" }.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
      responses:
        '200':
          description: 'NLWeb conversational_search answer or failure. With streaming, text/event-stream frames: start (_meta.streaming true), result ({ index, item }) per hit or error, then complete.'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
            text/event-stream:
              schema:
                type: string
        '400':
          description: POST body is not JSON. _meta.response_type is failure; error.code is invalid_query.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
        '405':
          description: Unsupported HTTP method. error.code is method_not_allowed. /ask accepts GET, HEAD, and POST.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
        '429':
          description: Rate limit exceeded. error.code is rate_limited.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
      tags:
      - Ask
components:
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 1
    RateLimit:
      description: Remaining quota and seconds until reset, for example "default";r=59;t=60.
      schema:
        type: string
    RateLimitPolicy:
      description: 'Quota policy: "default";q=60;w=60.'
      schema:
        type: string
  schemas:
    AskResponse:
      type: object
      required:
      - _meta
      properties:
        query:
          type: string
        site:
          type: string
        mode:
          type: string
        total_results:
          type: integer
        results:
          type: array
          items:
            type: object
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
        _meta:
          type: object
          required:
          - version
          - response_type
          properties:
            version:
              type: string
              const: '0.55'
            response_type:
              type: string
              enum:
              - answer
              - failure
            response_format:
              type: string
            mode:
              type: string
            site:
              type: string
            note:
              type: string
    AskRequest:
      type: object
      properties:
        query:
          oneOf:
          - type: string
            maxLength: 200
          - type: object
            properties:
              text:
                type: string
                maxLength: 200
        q:
          type: string
          maxLength: 200
        prefer:
          type: object
          properties:
            streaming:
              type: boolean
              description: true selects the SSE response
externalDocs:
  description: Developer notes
  url: https://www.ayushrai.site/developers/