Skip to main content

Base URL and content type

All requests go to:
Every request body and response body uses application/json. Set Content-Type: application/json on requests that include a body.

Authentication

Send your Platform API key as a Bearer token on every request:
API keys are organization-scoped. Rotate or deactivate keys in StoreRouter Platform; deactivation takes effect on the next request.
Never expose your Platform API key in client-side code or public repositories. Treat it like a password.

OpenAPI specification

The machine-readable contract is published at every platform deploy:
The document includes server URLs, operation IDs such as searchProducts, lookupProduct, and moreLikeThisProducts, full request and response schemas, and example error bodies. Most ecosystems can generate a typed client from it - for example openapi-generator, openapi-typescript, or oapi-codegen.

Catalog endpoints

The Catalog API reference documents these endpoints.

Taxonomy endpoints

The taxonomy endpoints return the canonical categories and enrichment attributes that StoreRouter assigns to products, with the search facets that select them. They return definitions, not inventory; use POST /products/facet-counts for counts.

Brand endpoints

See Discover brands for search, similarity, scope, and examples.

Store endpoints

Stores are the retailers whose products StoreRouter indexes. They are distinct from brands, which make the products. To search a store’s products, pass its domain in stores on POST /products/search. The taxonomy, store, and facet-count endpoints are not billed. They share your organization’s rate limit.

Error model

All error responses carry a top-level detail field. String detail (auth, authorization, and not-found errors):
Array detail (validation errors):

Error status codes

Retry transient network errors, 5xx responses, and 429 (after waiting Retry-After). The other 4xx codes listed above require a change in the caller.

Rate limits

Requests are rate limited per organization — one budget shared across all of your API keys and MCP sessions. The cap is a generous safety ceiling set well above normal traffic and is not published as a fixed number; read your current allowance from the X-RateLimit-Limit response header. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When you exceed the limit, the API returns 429 Too Many Requests with detail: "rate_limit_exceeded" and a Retry-After header. See the Rate Limits guide for the headers, backoff code, and the MCP equivalent.

REST and MCP: choosing a surface

Both surfaces run against the same grants table. A grant change on one path takes effect immediately on the other.
If you are building an agent-based workflow and already have OAuth in place, prefer the MCP server — the tool signatures map 1:1 to these REST endpoints.

Brands

Use the brand discovery guide to search brand identities, find similar brands, resolve canonical names, and browse their accessible products. The Brands API reference documents all six operations. Brands describe makers and designers; they are distinct from stores or sellers. Brand metadata is corpus-wide, while product browse applies your catalog access scope.