REST API basics

minipim is headless: everything the admin does goes through the same public /v1 REST API you can call yourself. There are no private admin endpoints.

With the API

Base URL: https://api.minipim.com. Every catalog endpoint lives under /v1.

Reference: the interactive OpenAPI reference is at api.minipim.com/docs, and the raw spec is at /docs/json. The spec is generated from the route definitions, so it is the authoritative list of endpoints, parameters and response shapes.

Authentication: send an API key as a bearer token.

curl 'https://api.minipim.com/v1/products?status=active&limit=20' \
  -H 'Authorization: Bearer pim_…'

A key already knows its organization, so no tenant header is needed. Requests made with a signed-in admin session instead pick the organization with the x-organization-id header.

Health checks: GET /healthz (liveness, returns the API version) and GET /readyz (database connectivity) need no authentication.

Conventions

• JSON in, JSON out. Send Content-Type: application/json. An empty body on DELETE is accepted.
• camelCase for query parameters, request bodies and responses: categoryId, updatedAt, familyId. The audit log filters are the exception (entity_type, entity_id).
• IDs are UUIDs. Path parameters are {id}; slugs are lookups, not stable IDs. Use ?slug= on list endpoints to resolve one.
• Money is integer cents plus an ISO 4217 currency: { "amount_cents": 1999, "currency": "USD" }. Never a float.
• Measurements carry a unit: { "amount": 2.5, "unit": "kg" }.
• Dates are ISO 8601 strings in UTC.
• Attribute values are keyed by locale and channel: { "description": [{ "locale": "en_US", "channel": null, "value": "…" }] }. See Attributes and Locales and translations.
• Resolved values: pass ?locale= and ?channel= to GET /v1/products/{id} to get a flat resolvedAttributes map alongside the raw arrays. List endpoints accept these parameters but do not resolve.
• Every write emits an event, which feeds the audit log and outbound webhooks.

Rules and limits

• GET /v1/products and GET /v1/categories reject unknown query parameters with a 422, so a typo like ?category_id= fails loudly instead of returning unfiltered results. See Listing, filtering and pagination.
• Responses use accurate status codes and one error envelope; see Errors.
• Media uploads are multipart, one file per request, up to 100 MB. See Media.
• Tags are canonicalized on write ("Buying Guide" becomes buying-guide), so the response may not match your input verbatim. See Tags.
• GET /v1/organizations/me returns the current organization, including which optional features are on.
• The TypeScript SDK is generated from the same spec and gives you typed paths and responses.