---
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. MCP is disabled by default; check `/.well-known/mcp.json` for its deployed status. Limited catalog samples remain available.

## 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) — disabled by default; see the status manifest.
- [SwitchMall product showcase](https://switchmall.ai/gpt/products.json?limit=5) — a non-paginated sample of at most 5 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. Restricted machine catalog access shares 6 requests per hour and 20 per day per IP, with at most 5 records per response and no pagination. Product records additionally share a 10-record minute budget. MCP is disabled by default. 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.
