Listing, filtering and pagination

Most minipim list endpoints use offset pagination and return a small envelope. A few return the full set as a plain array. This page lists which is which and the filters GET /v1/products supports.

With the API

Paginated endpoints return:

{ "data": [], "limit": 50, "offset": 0, "hasMore": true }

Keep requesting with offset += limit until hasMore is false. hasMore is exact: the server fetches one extra row to decide it, so a final page that happens to be full still reports false.

Endpoint	Shape	Default / max limit
GET /v1/products	Envelope, optional total	50 / 200
GET /v1/content	Envelope	50 / 200
GET /v1/brands	Envelope	50 / 200
GET /v1/audit-log	Envelope	100 / 500
GET /v1/categories	Plain array, whole tree unless you pass limit (max 1000)	none
GET /v1/attributes, /v1/modifiers, /v1/locales, /v1/channels, /v1/connectors	Plain array, everything	none

curl 'https://api.minipim.com/v1/products?status=active&categoryId=8d2a…&includeDescendants=true&limit=200&withTotal=true' \
  -H 'Authorization: Bearer pim_…'

Product filters

• status: draft, active or archived.
• q: relevance search over name, slug and attribute text. Results sort by relevance when q is present unless you set sortBy.
• slug: exact, case-sensitive match. Use this, not q, to turn a URL slug into an id.
• ids: up to 200 ids, comma-separated or repeated. Unknown ids are simply missing from the result.
• familyId, brandId, brand (brand name, case-insensitive), connectorId.
• categoryId: direct assignments only. Add includeDescendants=true to include the whole subtree.
• tag: repeatable, and a product must carry every listed tag. Values are canonicalized the same way writes are.
• updatedSince: ISO 8601. Use it to catch up after downtime.
• sortBy: name, slug, status, updatedAt, createdAt, relevance or attribute. sortDir: asc (default) or desc.
• sortAttribute and filterAttribute with filterMin / filterMax: sort or range-filter by a money, number or decimal attribute. Money bounds are integer cents, so filterMin=1000 means 10.00.
• withTotal=true adds a total count. It costs an extra query, so leave it off on hot paths.

GET /v1/products/facets takes the same filters and returns counts by family, status, category, brand, tag and connector. facetLimit (up to 500) raises the per-dimension cap, and includeEmpty=true includes categories and brands with zero matches.

GET /v1/content supports status, q (title), slug, ids, familyId, categoryId, includeDescendants, channelId, tag and updatedSince, and sorts by updatedAt descending by default.

Rules and limits

• GET /v1/products and GET /v1/categories reject unknown query parameters with 422. Other list endpoints ignore unknown parameters, so check spelling there.
• Boolean query flags accept true, false, 1 or 0. ?withTotal=false really means false. Any other value is a 422.
• sortBy=attribute without sortAttribute is a 422, and so is naming an attribute that is not money, number or decimal. Measurements are refused because their values carry units.
• Attribute sorts and filters read the default-scope value (no locale, no channel). Products without one sort last and are excluded by any bound. No currency conversion is applied.
• ?locale= and ?channel= are accepted on the product list but ignored. Fetch the product detail for resolvedAttributes.
• The facet tags and statuses dimensions never include zero-count entries.
• Pagination is offset-based; there are no cursors. The SDK’s paginate helper handles both envelope and array responses, see TypeScript SDK.

Full parameter lists are in the API reference. For keeping a copy in sync, pair updatedSince with webhooks.