Changelog

Still draft. This release collapses the discovery-chain surface from 0.1.0 into three standalone, identically-filtered endpoints. Anything built against 0.1.0's paths or parameters needs to migrate — nothing below is additive-only.

Changed (breaking)

• The capped-sample endpoint, previously GET /v1/catalog/sample, is now GET /api/v1/sample — its cap is raised from 25 rows to 100
• The complete-set endpoint, previously GET /v1/catalog/products, is now GET /api/v1/catalog — cursor-paginated, unchanged in that respect
• The coverage endpoint, previously GET /v1/catalog/coverage, is now GET /api/v1/coverage
• The old date-range parameters are renamed to start_date/end_date — same ISO 8601 format, still filtering on crawl_date
• The Product row's price field is replaced by mrp, selling_price, and discount_pct — there is no single combined price field anymore
• Filters — retailer, category, department, rcd, start_date, end_date — are now identical and optional on all three endpoints; no endpoint depends on a value proven by an earlier call
• Keys are created in the console, not issued out of band. Sign in, name a key, create it — the secret is shown exactly once and never again. See Authentication.
• Keys do not expire. Revoking is the only thing that ends one, and it takes effect on the next request. Hold as many as you need, one per integration.
• The sandbox/production split is gone. There is one kind of key and it reads the catalog directly; there is no tier to request an upgrade to
• The base URL is https://orbix-fastapi-uat.stylumia.com and every endpoint sits under /api/v1 — previously /v1
• Rate limits are counted per team, not per key

Added

• department filter, alongside retailer and category
• rcd filter — one or more retailer:category:department triples, comma-separated, shorthand for the three individual filters
• unknown_department error code (400, not retryable), matching the shape of unknown_retailer and unknown_category
• meta.coverage on every response, including /api/v1/sample and /api/v1/catalog — combinations matched, matching and corpus row counts, and the date range spanned, so one request answers both "what did I get" and "how much exists"
• The Explorer is public — build a request, read the schema, and see an example response without signing in; signing in is only required to run a request against live data

Removed

• The retailer-listing endpoint — no replacement; call GET /api/v1/coverage with no filters to see every retailer your team can see
• The category-listing endpoint — no replacement; GET /api/v1/coverage covers this too
• The discovery-chain narrative (list retailers, then categories, then coverage, then pull rows — each step proving the next) — every endpoint now works standalone; a wrong filter value returns valid_options naming the real ones instead

Everything in this release is draft. Endpoint shapes, field names, and response structures may change without notice until v1.0.0. Do not build a production integration against this version yet.

Added

• GET /v1/catalog/retailers — every retailer a key can see
• GET /v1/catalog/categories — categories, optionally scoped with retailer=
• GET /v1/catalog/coverage — row counts and date range by retailer/category
• GET /v1/catalog/products — filtered, cursor-paginated product rows
• GET /v1/catalog/sample — a small, capped sample for a quick look
• application/problem+json errors on every failure, carrying code, retryable, recovery, valid_options where relevant, and request_id
• Self-serve accounts — sign in with email and an OTP, a team is auto-provisioned, no manual setup
• Sandbox keys (orbx_test_) over a frozen slice of real data
• RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers on every /v1 response

Known limitations

• No exports (csv/xlsx/email) — read the API directly
• Filters are whole-catalog only: retailer, category, date_from/date_to — no per-field or full-text search yet
• Ratings coverage is ~46% of rows, seller coverage ~68%; shipment and variant data are not available on this surface
• The explorer UI isn't built yet — the discovery flow works today, but only over curl or your own client
• The coverage & freshness page is a stub

What lands in a changelog entry

Every change to the published OpenAPI document appears here — that's enforced in CI, not left to memory, so this page can't silently drift from what's actually live. Breaking changes are announced here before they ship, not discovered after.