> ## Documentation Index
> Fetch the complete documentation index at: https://crushrewards.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalog coverage map (depth/quality per cell)

> Zero-cost aggregate discovery endpoint. Coverage + freshness per (platform, country, category_root): priced/recent/known-brand product counts and quality_status (serving/thin/unmanaged/empty), so an agent can gauge whether a paid query will hit deep data. Row-level product data remains on paid endpoints.



## OpenAPI

````yaml https://api.syntalic.com/openapi.json get /v1/public/coverage
openapi: 3.1.0
info:
  title: 'Syntalic — Data Analytics for Agentic Commerce '
  version: 1.0.0
  description: >-
    Competitive pricing data across US and Canadian e-commerce retailers
    (Amazon, Walmart, Target, Best Buy, Home Depot, etc.). Serves price
    comparisons, deal alerts, brand tracking, promotional intelligence, and
    market analytics to AI agents via x402 and MPP micropayments.
  x-guidance: >-
    This API has three endpoint groups organized by use case:


    **Shopper endpoints** ($0.01/query): Use these for price comparisons and
    deal hunting. Start with /v1/shopper/best-price?q=<product> to find the
    cheapest option across retailers. Use
    /v1/shopper/deal-finder?category=<category> to find discounted products. Use
    /v1/shopper/price-drop-alert?q=<product> to check for recent price drops.


    **Marketing endpoints** ($0.01/query): Use these for competitive analysis.
    /v1/marketing/competitive-landscape?category=<category> shows all products
    in a category with pricing. /v1/marketing/brand-tracker?brand=<brand> tracks
    a brand's pricing over time.
    /v1/marketing/share-of-shelf?category=<category> shows brand market share.


    **Analyst endpoints** ($0.02/query): Use these for market-level insights.
    /v1/analyst/inflation?category=<category> shows price trends over time.
    /v1/analyst/price-dispersion?category=<category> shows price spread across
    retailers.


    All endpoints accept an optional 'country' parameter (us or ca, defaults to
    us). Query parameters use 'q' for free-text search and 'category' for
    category-level queries.


    Marketing and analyst responses carry a `meta` block (served_from,
    freshness_seconds, schema_version) for staleness budgeting and a `resolved`
    block describing how the category input was matched against the taxonomy.
    Every response also sends an X-Data-Freshness-Hours header.


    **Free pre-payment rejection:** requests that cannot be served are rejected
    BEFORE any payment challenge — invalid params (400 INVALID_PARAMS),
    retailers that are not serving-eligible (404 RETAILER_NOT_SERVING_ELIGIBLE,
    with the catalog quality status and the serving_eligible_retailers list in
    error.details), and shopper queries that resolve to nothing in the catalog
    (404 NO_RESULTS). You only pay when the API can actually execute your query.
    Retailer values are case-insensitive (amazon == Amazon).
servers:
  - url: https://api.syntalic.com
security: []
paths:
  /v1/public/coverage:
    get:
      tags:
        - Public
      summary: Catalog coverage map (depth/quality per cell)
      description: >-
        Zero-cost aggregate discovery endpoint. Coverage + freshness per
        (platform, country, category_root): priced/recent/known-brand product
        counts and quality_status (serving/thin/unmanaged/empty), so an agent
        can gauge whether a paid query will hit deep data. Row-level product
        data remains on paid endpoints.
      operationId: listPublicCoverage
      parameters:
        - name: country
          in: query
          required: false
          schema:
            type: string
            enum:
              - us
              - ca
          description: Filter to a country
          example: us
        - name: platform
          in: query
          required: false
          schema:
            type: string
          description: Filter to a platform (e.g. amazon, walmart)
          example: walmart
        - name: category_root
          in: query
          required: false
          schema:
            type: string
          description: Filter to a top-level category
          example: electronics
        - name: quality_status
          in: query
          required: false
          schema:
            type: string
            enum:
              - serving
              - thin
              - unmanaged
              - empty
          description: Filter to a coverage tier
          example: serving
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 200
            minimum: 1
            maximum: 1000
          description: Max results to return (default 200, min 1, max 1000)
          example: 200
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Pagination offset
          example: 0
      responses:
        '200':
          description: Public coverage
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        platform:
                          type: string
                        country:
                          type: string
                        category_root:
                          type: string
                        priced_product_count:
                          type: integer
                        recent_priced_product_count:
                          type: integer
                        known_brand_product_count:
                          type: integer
                        quality_status:
                          type: string
                        is_serving_eligible:
                          type: boolean
                        last_observed_at:
                          type: string
                          format: date-time
                          nullable: true
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '500':
          description: Public discovery error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: true
                    additionalProperties: true

````