Skip to content
rarixsmart binders
B2B · Endpoints

The v1 surface

A curated map of the routes partners actually use. Catalog (cards, figures, sets, oracle), price (history, altCurrencies, aggregates), discovery (search, trending, recent). All GET-only in v1, all return JSON, all gated by bearer auth.

Catalog — single entity

The most-hit family. One canonical entity per request, ~2-5kb payload depending on history range.

GET /v1/cards/:id
GET /v1/figures/:id
GET /v1/oracle/:id   # MTG concept view, aggregates printings
GET /v1/sets/:game/:setCode

# Optional query params on /v1/cards/:id:
#   ?range=30d|3mo|6mo|12mo|all   default 30d
#
# Optional query params on /v1/sets/:game/:setCode:
#   ?page=1
#   ?limit=60        capped server-side at 100

Shapes — all responses carry a versioned envelope. See FigureDetailResponse / CardDetailResponse in apps/web/lib/api.ts for the canonical TS types.

Catalog — listing

GET /v1/search?q=charizard
GET /v1/search?q=mtg:lea           # game prefix + free text supported
GET /v1/trending?game=mtg          # top-N by 24h velocity
GET /v1/recent?game=pokemon        # last-N added to canonical
GET /v1/artists/:slug              # all printings by an artist
GET /v1/figures/series/:id         # every figure in a series

Catalog — discovery feeds

The discover surface family — aggregated rollups, not entity detail. Used by news aggregators + market-research tools.

GET /v1/discover/sets
GET /v1/discover/users      # discover-feed users only — public showcase
                            # opt-ins. Anonymous user records are never
                            # returned.
GET /v1/discover/binders
GET /v1/discover/activity
GET /v1/discover/sparklines

Pull-rate research

Community-aggregated pull rates per series, with Bayesian smoothing against a global prior. Distinct from vendor-reported rates (often optimistic) — these are observed pulls from real packs across the user base.

GET /v1/series/:id/pull-stats

Catalog summary

GET /v1/catalog/summary
# {
#   "cards": { "total": 187432, "byGame": { "mtg": 109281, "pokemon": 71284, "lorcana": 4923, "onepiece": 1944 } },
#   "figures": { "total": 12087 },
#   "sets": { "total": 1421 }
# }

Snapshot counts. Useful as a sanity check before a full-catalog mirror — gives you the expected row count up front.

Not yet partner-callable

  • /v1/me/* — user-scoped surfaces, session auth only.
  • /v1/u/:handle/* — public showcase URL surfaces, available without bearer but with the same redaction rules as bearer paths.
  • /v1/admin/* — internal admin, never partner-readable.
  • /v1/observations — write surface, mobile-only.

Response idioms

  • JSON, UTF-8, gzip-encoded if your client accepts.
  • Cache-Control: public, s-maxage=300, stale-while-revalidate=3600 on most read routes — safe to mirror at your edge.
  • Money values: integer cents, USD canonical unless the field name carries a currency suffix.
  • Timestamps: ISO-8601 strings (2026-05-19T12:34:56.789Z).
  • Null vs missing: prefer null over absent keys — the wire shape stays stable across cache versions.