API reference

Public read-only API over the card catalogue.

id values are opaque strings. Do not parse them, and reserve 255 characters.

AuthenticationCopy Anchor Link

Authentication is optional for catalogue reads. Without a key, requests use the anonymous lane. A key identifies the caller and doubles both the per-minute and the daily allowance on the Free plan. It also lets Rarity block one consumer without blocking its entire IP range. Send Authorization: Bearer rar_live_.... A malformed, revoked or unknown key returns 401. Omitting the key uses the anonymous lane.

Rate limitsCopy Anchor Link

Without a key: 30 requests/minute and 1,000/day. With a key on the Free plan: 60/minute per key and 2,000/day per organization, so a new key buys no new day. A daily allowance refills continuously and has no midnight reset, so a burst followed by steady use can approach twice the number in 24 hours. Maker: 300/minute. Studio: 1,000/minute. Scale: agreed per contract. Paid plans have no daily limit. Exceeding either limit returns 429 with Retry-After in seconds, and with upgrade_url in the error when the request carried a key. The code is rate_limit_exceeded when the minute allowance is spent and daily_quota_exceeded when the daily allowance is spent. Responses from the limiter carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset in Unix seconds. These headers describe the window with fewer requests remaining. If the windows are tied, they describe the minute window.

Accounts of Rarity's own ecosystem are not limited: their requests are never refused with 429 and their responses carry no X-RateLimit-* headers. The headers are therefore optional on every response except the 429.

Caching and conditional requestsCopy Anchor Link

The three rate-limit headers report the origin's view of the caller. A cache hit does not reach the limiter or consume quota, but it retains the headers recorded when the cache entry was created, possibly for another caller. Use the headers only when CF-Cache-Status is not HIT, STALE or UPDATING. A 429 is never cached, so its Retry-After always applies to the current caller.

A 304 Not Modified does not count against either allowance. Send If-None-Match with the ETag from the previous response. Cache responses and revalidate them to reduce requests against the free lane.

ErrorsCopy Anchor Link

Error responses use a stable error.code for client branching. error.message is unstable by contract and must not be parsed. Dynamic values also appear in structured fields such as param and value.

Invalid query input returns 400. Rate limits return 429, and an unusable key returns 401. A missing key remains valid for operations that allow the anonymous lane.

WebhooksCopy Anchor Link

Events may arrive out of order. Delivery is at least once, so deduplicate by delivery id. Payloads contain identifiers only; fetch the current resource from the API after receipt.

The webhook backend signs deliveries and sends svix-id, svix-timestamp and svix-signature. svix-signature contains a version-prefixed, base64 HMAC-SHA256 signature over {svix-id}.{svix-timestamp}.{raw body}. Verify it against the raw body using a constant-time comparison. Reject timestamps outside your chosen tolerance. Use svix-id as the deduplication key.

The webhook backend defines these header names. Replacing that backend may require consumer code changes.

The three operations under /v1/webhooks require a key because they create or manage subscriptions for an account. POST /v1/webhooks returns the signing secret once. No endpoint returns it again.

ConventionsCopy Anchor Link

A parameter declared with a scalar schema is sent at most once: repeating it is a 400 (repeated_parameter), never a silently discarded value. The repeatable filters of GET /v1/cards are declared as arrays: set, rarity, category, color and type. So is game on GET /v1/cards/suggest.

/v1/cards and /v1/cards/{id} ignore unknown query parameters. Known parameters still follow the validation and repetition rules documented for each operation.

What does not count as breaking: https://rarity.dev/docs/compatibility

BrowsersCopy Anchor Link

GET and HEAD under /v1 answer any origin with Access-Control-Allow-Origin: * and no credentials, and OPTIONS costs no quota. The preflight allows those two methods only: a page cannot read the response to any other method, and a preflighted request with one is refused. A rar_live_ key in a browser app is an exposed key: anyone who opens the page can read it.