> ## 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.

# List retailers (platforms) in the catalog

> Zero-cost aggregate discovery endpoint. One row per platform with served product count, countries seen, and freshest observation; row-level product data remains on paid endpoints.



## OpenAPI

````yaml https://api.syntalic.com/openapi.json get /v1/public/retailers
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/retailers:
    get:
      tags:
        - Public
      summary: List retailers (platforms) in the catalog
      description: >-
        Zero-cost aggregate discovery endpoint. One row per platform with served
        product count, countries seen, and freshest observation; row-level
        product data remains on paid endpoints.
      operationId: listPublicRetailers
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: Max results to return (default 100, min 1, max 500)
          example: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Pagination offset
          example: 0
      responses:
        '200':
          description: Public retailers
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        platform:
                          type: string
                        product_count:
                          type: integer
                        countries:
                          type: array
                          items:
                            type: string
                        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

````