AgentReady API

openapi: 3.1.0
info:
  title: AgentReady API
  version: '2026-11-01'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-01: 12 operation(s) read from 4 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; AgentReady has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 3
    documentation: 9
    pages-with-code: 2
    pages-read: 4
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-01'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://www.agentready.market/api
  - https://www.agentready.market/llms.txt
  - https://www.agentready.market/research/shopify-global-catalog-rest-api-shutdown
  - https://www.agentready.market/research/check-if-ai-shopping-agents-can-buy-on-your-store
paths:
  /api/reports:
    post:
      operationId: post_api_reports
      tags:
      - Api
      summary: Bulk reads return the latest stored report per host — instant
      x-source: https://www.agentready.market/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiReportsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiReportsResponse'
      x-evidence:
        kind: documentation
  /api/scan:
    get:
      operationId: get_api_scan
      tags:
      - Api
      summary: Run a scan (the merchant's own store — ~30s, synchronous)
      x-source: https://www.agentready.market/api
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
        description: Store URL to scan
      - name: vertical
        in: query
        required: false
        schema:
          type: string
        description: Optional vertical for the benchmark
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiScanResponse'
      x-evidence:
        kind: documentation
  /api/v1/scan:
    get:
      operationId: get_api_v1_scan
      tags:
      - Api
      summary: Scan any store programmatically
      description: GET https://www.agentready.market/api/v1/scan?url=<store>
      x-source: https://www.agentready.market/llms.txt
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
        description: store URL to scan
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/scan/{scanId}/brief.md:
    get:
      operationId: get_api_v1_scan_scanId_brief_md
      tags:
      - Api
      summary: Agent brief (Pro) — the full fix job as one markdown file
      description: 'Requires Authorization header: Bearer ar_...'
      x-source: https://www.agentready.market/api
      parameters:
      - name: scanId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1ScanScanidBriefMdResponse'
      x-evidence:
        kind: documentation
  /api/v1/scan/{scanid}:
    get:
      operationId: get_api_v1_scan_scanid
      tags:
      - Api
      summary: GET /api/v1/scan/{scanId}
      x-source: https://www.agentready.market/api
      parameters:
      - name: scanid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1ScanScanidResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://www.agentready.market/api/v1/scan/<scan_id>/brief.md  -H \"Authorization: Bearer ar_...\" \n \U0001F9E9 Function-calling\
          \ definitions — for custom agents \n Building on the OpenAI/Anthropic SDKs directly? Drop these\n tool definitions into your tools array;\
          \ both map to plain GET/POST\n calls, no key needed. \n [\n {\n \"name\": \"check_merchant_readiness\",\n \"description\": \"Before\
          \ attempting a purchase on a"
  /ask:
    get:
      operationId: get_ask
      tags:
      - Ask
      summary: Ask in natural language
      description: GET https://www.agentready.market/ask?query=<question>
      x-source: https://www.agentready.market/llms.txt
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
        description: question to ask
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /global/v2/lookup:
    post:
      operationId: post_global_v2_lookup
      tags:
      - Global
      summary: 'Shopify Global Catalog REST API shutdown: what to do by Nov 2'
      x-source: https://www.agentready.market/research/shopify-global-catalog-rest-api-shutdown
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /global/v2/p/by-variant/{vid}:
    get:
      operationId: get_global_v2_p_by_variant_vid
      tags:
      - Global
      summary: 'Shopify Global Catalog REST API shutdown: what to do by Nov 2'
      x-source: https://www.agentready.market/research/shopify-global-catalog-rest-api-shutdown
      parameters:
      - name: vid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /global/v2/p/{upid}:
    get:
      operationId: get_global_v2_p_upid
      tags:
      - Global
      summary: 'Shopify Global Catalog REST API shutdown: what to do by Nov 2'
      x-source: https://www.agentready.market/research/shopify-global-catalog-rest-api-shutdown
      parameters:
      - name: upid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /global/v2/search:
    get:
      operationId: get_global_v2_search
      tags:
      - Global
      summary: 'Shopify Global Catalog REST API shutdown: what to do by Nov 2'
      x-source: https://www.agentready.market/research/shopify-global-catalog-rest-api-shutdown
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /gptbot:
    get:
      operationId: get_gptbot
      tags:
      - Gptbot
      summary: GET /gptbot
      x-source: https://www.agentready.market/research/check-if-ai-shopping-agents-can-buy-on-your-store
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -s -o /dev/null -w \"%{http_code}\\n\"  -A \"Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.2;\
          \ +https://openai.com/gptbot\"  https://yourstore.com/products/your-product\n 200 means the door is open. 403 , 429 or a challenge page\
          \ means it isn’t,\nand this is the one failure that outweighs everything else: our own scoring\ncaps a store that blocks agents at the\
          \ door, however g"
  /products/your-product:
    get:
      operationId: get_products_your_product
      tags:
      - Products
      summary: GET /products/your-product
      x-source: https://www.agentready.market/research/check-if-ai-shopping-agents-can-buy-on-your-store
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -s https://yourstore.com/products/your-product | grep -i \"your price, e.g. 24.90\"\n If the price, the stock status or\
          \ the add-to-cart action only appears after\nJavaScript runs, an agent reading raw HTML can describe the product but cannot\nbuy it.\
          \ In a controlled test of 19 page configurations, JavaScript-only\nrendering was one of only two things that stopped a plain fetch from\n\
          succeeding; outr"
components:
  schemas:
    PostApiReportsRequest:
      type: object
      properties:
        hosts:
          type: array
          description: List of hostnames to retrieve reports for
      required:
      - hosts
    PostApiReportsResponse:
      type: object
      properties:
        reports:
          type: array
          description: Array of report objects
        host:
          type: string
          description: Hostname of the store
        scanned:
          type: boolean
          description: Whether a scan exists
        score:
          type: integer
          description: Score out of 100
        grade:
          type: string
          description: Letter grade
        capped:
          type: boolean
          description: Whether agents are blocked
        agent_ready_verified:
          type: boolean
          description: Verification status
        scanned_at:
          type: string
          description: Timestamp of the scan
        report_url:
          type: string
          description: URL to the full report
    GetApiScanResponse:
      type: object
      properties:
        score:
          type: integer
          description: Score out of 100
        grade:
          type: string
          description: Letter grade
        capped:
          type: boolean
          description: Whether agents are blocked outright
        pillars:
          type: array
          description: Pillar details
        top_fixes:
          type: array
          description: Top fixes
        scan_id:
          type: integer
          description: Identifier of the scan
        report_url:
          type: string
          description: URL to the full report
    GetApiV1ScanScanidBriefMdResponse:
      type: object
      properties:
        body:
          type: string
          description: Markdown content of the brief
    GetApiV1ScanScanidResponse:
      type: object
      properties:
        type:
          type: string
        properties:
          type: object
          properties:
            url:
              type: object
              properties:
                type:
                  type: string
                description:
                  type: string
            vertical:
              type: object
              properties:
                type:
                  type: string
                description:
                  type: string
        required:
          type: array
          items:
            type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Ask
- name: Global
- name: Gptbot
- name: Products