## [0.2.0] — 11 September 2026 · Draft

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`](/reference) — its cap is raised from 25 rows to 100
- The complete-set endpoint, previously `GET /v1/catalog/products`, is now
  [`GET /api/v1/catalog`](/reference) — cursor-paginated, unchanged in that
  respect
- The coverage endpoint, previously `GET /v1/catalog/coverage`, is now
  [`GET /api/v1/coverage`](/reference)
- 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`](/docs/objects/product) — 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](/docs/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`](/errors#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](/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`](/reference) 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

## [0.1.0] — 9 September 2026 · Draft

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](/docs/error-handling) on every
  failure, carrying `code`, `retryable`, `recovery`, `valid_options` where
  relevant, and `request_id`
- Self-serve accounts — [sign in](/signin) with email and an OTP, a team is
  auto-provisioned, no manual setup
- [Sandbox keys](/docs/authentication) (`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](/docs/coverage-freshness) is a stub

## What lands in a changelog entry

Every change to the published [OpenAPI document](/openapi.json) 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.