Products

Browse / search the catalog

The primary catalog endpoint. Supports full-text + semantic search, brand/tag filtering, ΔE-ranked shade matching, per-customer reward projection, and dual-tender pricing (ILS + ℳ-credits).

Auth tiers

  • Tag-only or no-arg listing: bearer token optional.
  • q / phone / include=inventory / relevant_to_phone: full-scope bearer token required.

Precedence: near_hex ranking dominates sort; sort dominates the implicit relevance ranking.

get/api/v1/products

Request

  • Base URL: https://makeup.land
  • URL: https://makeup.land/api/v1/products
  • Auth: one of:
    • HTTP bearer
    • none

Query parameters

qstring

Free-text query. Triggers semantic + lexical search (union, rerank). Requires a bearer token when supplied without tag.

tagstring

EXACT tag-string filter (no translation, no substring). Matching is case-insensitive and whitespace-trimmed — PRO+ and pro+ are the same tag; tags come back lowercase. Catalog tags are Hebrew (e.g. שפתון, ביוטי, עיניים, שפתיים). For natural-language category lookup use q, which routes through semantic search.

brandstring

Brand identifier. Matches name / slug / Hebrew name with whitespace and punctuation normalised — Bali Body, balibody, bali-body all collapse.

phonestring

When supplied, the response embeds the customer's reward projection (reward_earned per product). Requires full-scope bearer token.

in_stock'true' | 'false'

String boolean. true filters to in-stock variants only.

max_pricenumber

Max ILS price filter (decimal, e.g. 99.99)

max_credit_centsinteger

Max ℳ-credit price filter in agorot

relevant_to_phonestring

Re-rank results by relevance to this customer's past orders + tags. Requires full-scope bearer token.

includestring

Comma-separated extra-field bundles. inventory adds stock_by_location and per-variant available. Requires full scope.

limitinteger

Default 10. Capped at 50.

pageinteger
near_hexstring

Single #RRGGBB hex or comma-separated list (≤8). Returns products ranked by ΔE distance to the closest match.

delta_e_maxnumber

ΔE2000 cutoff used with near_hex. Default 80 single-hex, 200 multi-hex.

hue_familystring

Comma-separated hue families. Post-filter — narrows results to products whose swatches fall in any of the listed families.

sort'price_asc' | 'price_desc' | 'popularity' | 'rating' | 'relevance'

Default relevance. rating uses a Bayesian shrinkage to avoid single-review products winning.

coverage'all' | 'any'

How multi-value filters (tags, hue_family) combine. all (default) intersects; any unions.

Response

Paginated catalog page

totalinteger required
pageinteger required
has_moreboolean required
partialboolean required

True when post-filters (hue_family, etc.) underfilled the page — the catalog page below this one may contain more matches.

Changes

No recorded changes to this operation across all 1 revision of this API.