---
title: SwitchMall Public API
description: Read-only SwitchMall product and merchant statistics plus catalog data resources.
canonical_url: https://switchmall.ai/developers/api
openapi_url: https://switchmall.ai/openapi.json
---

# SwitchMall Public API

SwitchMall provides a small read-only public API. The stable REST endpoints documented here return engagement statistics for products and merchants. For catalog discovery tied to a concrete user request, use the SwitchMall MCP server.

## SwitchMall Product Statistics API

```http
GET https://switchmall.ai/api/public/v1/products/{productId}/stats
Accept: application/json
```

`productId` must be a positive integer. No API key or user token is required.

```bash
curl --header 'Accept: application/json' \
  'https://switchmall.ai/api/public/v1/products/12345/stats'
```

Successful response:

```json
{
  "productId": 12345,
  "viewsCount": 128,
  "likesCount": 17,
  "dislikesCount": 2
}
```

The endpoint allows cross-origin browser requests. It may return `400` for an invalid ID, `405` for an unsupported method, `429` when the public rate limit is exceeded, or `500` for an unexpected server error. A missing product ID can still have zero statistics because this endpoint does not assert catalog existence.

## Merchant view statistics

Use the merchant ID to retrieve rolling 24-hour totals plus per-product and per-offer view tables:

```http
GET https://switchmall.ai/api/public/v1/merchants/{merchantId}/stats
Accept: application/json
```

```bash
curl --header 'Accept: application/json' \
  'https://switchmall.ai/api/public/v1/merchants/42/stats'
```

```json
{
  "merchantId": 42,
  "merchantName": "Example Store",
  "productViewsCount": 150,
  "productUserViewsCount": 90,
  "productAgentViewsCount": 60,
  "offerViewsCount": 25,
  "totalViewsCount": 175,
  "period": "24h",
  "comparisonDate": "2026-08-30",
  "scheduledAt": "14:00 MSK",
  "comparisons": {
    "productViews": { "count": 150, "previousCount": 100, "changePercent": 50 },
    "productUserViews": { "count": 90, "previousCount": 60, "changePercent": 50 },
    "productAgentViews": { "count": 60, "previousCount": 40, "changePercent": 50 },
    "offerViews": { "count": 25, "previousCount": 20, "changePercent": 25 },
    "totalViews": { "count": 175, "previousCount": 120, "changePercent": 45.8 }
  },
  "products": [
    { "id": 12345, "name": "Example product", "viewsCount": 150, "userViewsCount": 90, "agentViewsCount": 60 }
  ],
  "offers": [
    { "id": 678, "name": "Example offer", "viewsCount": 25, "userViewsCount": 25, "agentViewsCount": 0 }
  ]
}
```

All counters cover the rolling 24 hours before the request. `comparisons` compares that window with the latest previous daily snapshot, captured at `14:00 MSK`; `comparisonDate` identifies the baseline. Only products and offers with views are included, ordered by descending `viewsCount`. Product totals combine signed-in user and AI-agent views and expose both sources separately. Offer analytics currently contain signed-in user views, so their `agentViewsCount` is `0`. A merchant ID with no activity in the window returns zero totals and empty arrays.

Time-bucketed agent view history starts when version 1.2 is deployed; older all-time agent totals are intentionally not projected into the 24-hour window.

The endpoint requires no API key, allows cross-origin requests, has a limit of 600 requests per client IP per hour, and may be cached by the CDN for 30 seconds. Invalid IDs return `INVALID_MERCHANT_ID`.

Error responses are JSON and contain `error`, a stable `code`, a human-readable `message`, and a concrete `resolution` hint. Existing clients can continue reading the backward-compatible `error` field.

## SwitchMall catalog data

- [SwitchMall MCP server](https://switchmall.ai/developers/mcp) — search and retrieve current products.
- [SwitchMall product showcase](https://switchmall.ai/gpt/products.json?limit=20) — a non-paginated sample of at most 20 rotating discovery products.
- [SwitchMall AI catalog manifest](https://switchmall.ai/gpt.json) — live counts and endpoint metadata.
- [SwitchMall OpenAPI specification](https://switchmall.ai/openapi.json) — OpenAPI 3.0 JSON.
- [SwitchMall OpenAPI specification in YAML](https://switchmall.ai/api/openapi.yaml) — equivalent YAML representation.

## Authentication

See [SwitchMall authentication documentation](https://switchmall.ai/developers/auth). Public resources listed above do not require credentials.

## Acceptable use and rate limits

Public interfaces are for interactive, user-requested product discovery. MCP and public JavaScript catalog access share a limit of 40 returned product records per client IP per minute. Every cited product must identify SwitchMall and include its returned canonical link. Catalog enumeration, mirroring, bulk ingestion, resale, republication, training-dataset creation, and attempts to evade quotas are not permitted. Rate-limited responses use HTTP `429`, include `Retry-After`, and provide a structured `RATE_LIMIT_EXCEEDED` error. Access is governed by the [SwitchMall Agent Catalog Terms](https://switchmall.ai/developers/agent-terms). Contact SwitchMall for an approved higher-volume integration.