API guide
Every card on this site is available as JSON from
https://api.rifthunt.com. No key, no signup, no quota: all
requests are GET, all responses are
application/json, and CORS is open so you can call it straight
from a browser app.
Fields on their way out are marked Deprecated and listed under deprecations; what has changed since launch is in the changelog. Building with an AI assistant? There is a prompt to paste in.
Fair use
There is no hard rate limit, which is a request rather than a promise. Keep bursts under roughly 10 requests per second and put a short delay between calls in a loop.
If you want more than a few hundred cards, do not crawl: download the bulk export once and work locally. It is one request instead of a thousand and it is faster for you.
Send a User-Agent that identifies your project. If something
misbehaves, that is the difference between getting an email and getting
blocked.
Endpoints
| Request | Returns |
|---|---|
| GET /cards/search?q=… | Search. Same syntax as the site (see the syntax guide). Takes unique=, order= and dir=, below. |
| GET /cards/named?exact=… | One card by exact name. |
| GET /cards/:id | One card by its UUID. |
| GET /sets | Every set, with printing counts. |
| GET /sets/:code | One set by code, e.g. ogn. |
| GET /bulk-data | Index of the bulk exports. |
| GET /bulk/cards | The whole catalogue: 1732 printings, ~1.2 MB. |
| GET /bulk/prices | TCGplayer prices (USD) for 1676 printings, and Cardmarket's (EUR). Refreshed daily. |
| GET /prices/:riftboundId | Prices for one printing. |
| GET /prices/:riftboundId/history?range= | Daily price history for one printing, by seller and finish. range is 1m, 3m, 6m, 1y or all. |
| GET /tags?kind=&q= | Community tags, most-used first. kind is function or art; q filters by name. |
| GET /tags/:kind/:slug | One tag: description, count, creator, and the search that lists its cards. |
| GET /cards/:id/tags | Every community tag on one printing: function tags from its card, art tags of its own. |
| GET /bulk/tags | Every tagging, one row per (tag, printing). What the site builds from. |
| GET /cards/:id/rulings | Rulings for the card, from Riftbound FAQ. The same list for every printing. |
| GET /bulk/rulings | Every ruling, one entry per card. What the site builds from. |
| GET /health | Liveness check. |
Searching
/cards/search takes the same query syntax as the site's search
box, documented in full on the syntax guide.
| Example | Finds |
|---|---|
| /cards/search?q=t:unit d:fury e<=3 | Cheap Fury units. |
| /cards/search?q=t:gear p:1 | Gear costing one rune. |
| /cards/search?q=s:ogn r:epic | Epics in Origins. |
Results are one printing per card by default: reprints and variants collapse into a single entry, and the rest are on that card's page. A query matching nothing returns 404, not an empty list.
Response shape
Lists are wrapped in an envelope:
{
"object": "list",
"total_cards": 41,
"has_more": false,
"next_page": null,
"data": [ /* card objects */ ]
} Errors use the same convention, with the HTTP status repeated in the body:
{
"object": "error",
"status": 404,
"code": "not_found",
"details": "Your query didn't match any cards. Adjust your search terms."
} The card object
| Field | Meaning |
|---|---|
| object | Always "card". |
| id | Permanent UUID for this printing. Use it with /cards/:id. |
| printing_id | The same UUID as id, repeated under the name the bulk files use, so one field name joins the card object, /bulk/cards and /bulk/prices. (In /bulk/cards, id is a different, deprecated field.) |
| oracle_id | Permanent UUID shared by every printing of the same card. Also in /bulk/cards. |
| lang | Language of the text fields. Only "en" today. |
| name | Printed name, including any variant suffix, e.g. "Annie, Dark Child (Metal)". |
| oracle_name | The base name shared by every printing, e.g. "Annie, Dark Child". |
| type | Unit, Spell, Gear, Legend, Battlefield or Rune. |
| domains | Lowercased array. Also which runes may pay the rune cost. |
| energy | Energy cost. null when there is none. |
| power | Rune cost: how many runes are recycled to play it. null when there is none. |
| might | Combat stat on units. null otherwise. |
| keywords | Lowercased array. |
| tags | Lowercased array. Searchable with tag:. |
| rules_text | Plain text. Keeps :rb_*: symbol shortcodes. |
| flavor_text | Plain text, or null. |
| set | Set code, lowercased, e.g. "ogn". |
| set_name | Full set name. |
| collector_number | As printed, zero-padded, e.g. "017". Letter-prefixed (t, r, s) for tokens, runes and special promos. |
| rarity | common, uncommon, rare, epic, showcase or promo. |
| artist | Illustrator, or null. |
| variant | What kind of printing this is: base, alternate, overnumbered, signature, showcase or null. base is the card's original printing (its earliest plain one), and exactly one printing of each card has it. null is a promo, a Metal or Starter (which say so in the name) or a plain reprint in a later set. Also in /bulk/cards. |
| riftbound_id | Riot's own id, e.g. ogn-025-298. Not unique: 52 promos share one. |
| rifthunt_uri | Canonical path for this printing on rifthunt.com. |
| rulings_uri | Path to the card's rulings, /cards/:id/rulings. An empty list when there are none. |
| legalities | Object keyed by standard and 2v2, each with status (legal, banned or not_legal) and banned_from, the date a ban applies from, or null. See below. |
| images | Object with small (200 wide), normal (480 wide) and large (744x1039) WebP URLs on images.rifthunt.com, plus back for the five double-sided tokens. Immutable: the ?v= changes when the image does. |
| tcg_id | TCGplayer product id, or null. Build your own link with it if you prefer. |
| cardmarket_id | Cardmarket product id, or null. Cardmarket URLs cannot be built from it; use purchase_uris.cardmarket. |
| finishes | The finishes this printing is made in: ["normal", "foil"], ["foil"] or ["normal"], the same names as the keys of prices. null when unknown (no TCGplayer product). |
| purchase_uris | Object with tcgplayer (an affiliate link, see below) and cardmarket (the product page, or a name search; not an affiliate link). |
| prices | TCGplayer prices per finish in USD, or null if we have none. See below. |
| cardmarket_prices | Cardmarket prices per finish in EUR — trend (their headline figure) and low — or null if we have none. Never converted to or from USD. |
Legality
legalities has one entry per format, standard and
2v2. status is legal,
banned or not_legal (tokens). The lists are Riot's,
from playriftbound.com; the Korean and Traditional Chinese circuits keep
their own from 2026-11-23, and those are not represented.
"legalities": {
"standard": { "status": "legal", "banned_from": "2026-11-23" },
"2v2": { "status": "legal", "banned_from": "2026-11-23" }
}
Riot announces a ban about ten days before it applies. In that window
status is still legal and banned_from
is the date it stops being so, as above; from that date
status is banned and banned_from
stays as the date the ban began. It is null on a card with no
ban, and on one banned card, Master Yi, Wuju Bladesman in 2v2, whose date
was never published. Card responses are cached for up to a day, so if the
exact day matters, compare banned_from to the date yourself
rather than waiting for status to change. Riot gives a date
and no time; we switch at midnight Pacific. The field is on the card
object only, not in /bulk/cards.
curl -s "https://api.rifthunt.com/cards/search?q=banned:upcoming" One printing or all of them
By default search returns one printing per card: the
plain one, without a variant suffix. Add
unique=prints to get every printing, which is what you want
for prices: a card and its Metal promo are separate products fifty times
apart in value.
curl -s "https://api.rifthunt.com/cards/search?q=annie&unique=prints" /cards/named?exact= accepts either form. The base name returns
the plain printing; a printed name such as Annie, Dark Child (Metal)
returns that printing.
Sorting
unique= is cards (default), prints, or art
for one printing per illustration. order= is one of name (default),
released, set, number, usd (TCGplayer market
price), eur (Cardmarket trend), rarity, energy,
power, might or artist.
dir= is asc, desc, or auto (default):
newest and priciest first, everything else A to Z. Cards with no value for the sort key
come last either way. next_page carries all three.
curl -s "https://api.rifthunt.com/cards/search?q=t:legend&unique=prints&order=usd"
The same three can be written in the query itself, as on the site and on Scryfall:
sort: (or order:), dir: and unique:.
A term in the query beats the parameter of the same name. A price sort puts the
unpriced last, and for eur skips a finish the printing is not made in,
since Cardmarket sellers list foil-only cards without marking them foil.
curl -s "https://api.rifthunt.com/cards/search?q=set:rad+sort:eur" Bulk data
/bulk/cards returns all 1732 printings in one response,
about 1.2 MB. It is the same file the site itself builds from, so it will
never disagree with what you see here. Fetch it once a day at most, since
card data only changes when a set does.
curl -s https://api.rifthunt.com/bulk/cards > cards.json
Each printing there carries two permanent ids. printing_id
identifies the printing; it is the same UUID as the card object's
id and printing_id. oracle_id is
shared by every printing of the same card, so you can group printings into
cards, or match one to an API result, without a second request.
The file is not in the card object's shape. It is the shape the site
builds from: camelCase names, and capitalised values such as
"Unit" and ["Fury"].
{
"fetched": "2026-11-06T21:03:32.635Z", // when the catalogue was last ingested
"source": "riotgames.com",
"sets": [ { "id": "OGN", "name": "Origins", "count": 352, "released": "2025-10-31" }, … ],
"cards": [ /* one object per printing, below */ ]
} A printing in /bulk/cards
| Field | Meaning |
|---|---|
| idDeprecated | Our ingest's source record id, e.g. "ogn-001-298". Not the card object's id. Use printing_id. |
| printing_id | Permanent UUID for this printing. The same value as id and printing_id on the card object, and printing_id in /bulk/prices. Join on this. |
| oracle_id | Permanent UUID shared by every printing of the same card. Group on this. |
| oracleIdDeprecated | The same value as oracle_id, under the name it first shipped with. Use oracle_id. |
| variant | base, alternate, overnumbered, signature, showcase or null. The same value as variant on the card object; base marks the card's original printing. |
| riftboundId | Riot's id, e.g. "ogn-025-298". The card object's riftbound_id. Not unique: 52 promos share one with their base printing. |
| name | Printed name, including any variant suffix, e.g. "Annie, Dark Child (Metal)". |
| cleanName | The name without its variant suffix, e.g. "Annie, Dark Child". To group printings, use oracle_id rather than this. |
| num | Collector number as an integer, e.g. 17. Variants share their base printing's number; the card object's collector_number is the printed string. |
| energy | Energy cost, or null. |
| might | Combat stat on units, or null. |
| power | Rune cost: how many runes are recycled to play it, or null. Not a combat stat. |
| type | Unit, Spell, Gear, Legend, Battlefield or Rune. |
| supertype | Champion, Basic, Signature, Token, or null. |
| rarity | Common, Uncommon, Rare, Epic, Showcase or Promo. |
| domains | Array of Fury, Calm, Mind, Body, Chaos, Order or Colorless. Capitalised, unlike the card object. |
| text | Rules text, plain, with :rb_*: symbol shortcodes and [Keyword] tokens, or null. |
| rich | The same rules text as HTML, with the same shortcodes and tokens, or null. |
| flavour | Flavour text, or null. The card object calls it flavor_text. |
| set | Set code, uppercase, e.g. "OGN". |
| setName | Full set name. |
| tags | Riot's own tags in their original case, e.g. ["Ionia"]. Not community tags (those are in /bulk/tags). |
| artist | Illustrator, or null when unknown. |
| tcgId | TCGplayer product id as a string, or null. |
| imgUrl | Full-size image at its source (Riot's CDN, TCGplayer or rifthunt.com). For sized WebP copies on images.rifthunt.com, use images on the card object. |
| imgInternal | A legacy file name such as "cards/ogn-001-298.png", not a URL, and null on most newer sets. Ignore it. |
| orientation | portrait, or landscape for Battlefields. |
| alt | true for an alternate-art printing. |
| sig | true for a Signature printing. |
| over | true for an overnumbered printing. |
| finishes | The finishes this printing is made in: ["normal", "foil"], ["foil"] or ["normal"]. null when unknown (no TCGplayer product). |
| cardmarketId | Cardmarket product id as a string, or null. |
| cardmarketUrl | The product's page on cardmarket.com, or null when only the id is known. Not derivable from the id. |
| imgHashInternal | Version of our mirrored copy of the image. Internal; the card object's images URLs already carry it. |
| imgBackUrl | Back face of a double-sided token, at its source. Absent on single-sided cards. |
| imgBackHashInternal | Version of our mirrored copy of the back face. |
Fields marked Internal are ours. They may change without notice, so do not build on them. Fields marked Deprecated are listed under deprecations.
Community tags
Cards carry two kinds of community tag: function
tags on the card (what it does, searchable as otag:removal) and
art tags on a printing (what the picture shows, art:dragon).
Reading them needs no account. Adding them does: sign in on the tagger, which uses the same API with a bearer token.
Tags can change at any time, so cache them for minutes, not days.
curl -s "https://api.rifthunt.com/cards/search?q=otag:removal" Rulings
Rulings come from Riftbound FAQ,
Christian “Near” Ivicevic's unofficial rulings site, under CC BY-SA 4.0:
167 rulings on 71 cards right now. Every response names the source, the
upstream commit and the licence; if you republish them, keep the attribution. Each ruling is a
question and an answer, the answer as plain text (comment) and as HTML that uses the
same :rb_*: shortcodes and [Keyword] tokens as rules_text.
Rulings belong to the card, so every printing returns the same list. A wrong ruling is reported on
the FAQ's GitHub, not to us.
curl -s https://api.rifthunt.com/bulk/rulings > rulings.json Prices
Prices are a separate export, because they change on a completely different
schedule to the catalogue. /bulk/prices returns 1699 rows,
one per printing with a TCGplayer product, of which 1676 have
a current market price. The rest are listed products with nothing for sale
right now, so every field is null. Refreshed daily.
curl -s https://api.rifthunt.com/bulk/prices > prices.json
Normal and foil are reported separately, under finishes, because
TCGplayer prices them separately and they diverge by orders of
magnitude: the same card can be seven cents normal and $185 foil.
{
"fetched": "2026-11-07T00:16:15.903Z", // when this response was built; each row's updatedAt is its price's age
"source": "tcgplayer",
"currency": "USD",
"prices": [ /* one row per printing, below */ ],
"cardmarket": {
"source": "cardmarket",
"currency": "EUR",
"prices": [ /* one row per printing Cardmarket lists, below */ ]
}
} A row in /bulk/prices
| Field | Meaning |
|---|---|
| printing_id | The printing, as in /bulk/cards and on the card object. Join on this. |
| riftboundId | Riot's id. Not unique on its own. |
| collector | Collector number as printed, e.g. "017". |
| slug | The URL slug of the printing's page, e.g. "annie-dark-child-metal". |
| tcgId | TCGplayer product id. |
| purchaseUri | Affiliate link to the product on TCGplayer. |
| updatedAt | When the price was fetched. |
| finishes | An object keyed by normal and foil, each with market, low, mid, high and directLow in USD, any of them null. |
Every row reports both finishes, including ones the card is never made in.
Check the printing's finishes in /bulk/cards to tell
them apart: a finish listed there with null prices exists but has
no listings, and a finish missing from it does not exist (most rares and up
are foil only).
Join a row to its card on printing_id. The older key,
riftboundId, collector and slug
together, still works. Never key on riftboundId alone: the 52
“(Metal)” promos share an id with their base printing and are
separate products at very different prices, so keying on the id by itself
will silently give you the wrong one.
A row in the cardmarket block
Cardmarket's figures are EUR and come from its daily price guide, so they
are a different market, not a conversion. trend is the number
its own product pages lead with. Show them as EUR; do not convert them
into the TCGplayer prices or compare the two as if they were one.
| Field | Meaning |
|---|---|
| printing_id | The printing. Join on this. |
| riftboundId, collector, slug | The older key, as above. |
| cardmarketId | Cardmarket product id. |
| purchaseUri | The product page on Cardmarket where we know it, otherwise a name search. Not an affiliate link. |
| updatedAt | When the price guide was read. |
| finishes | An object keyed by normal and foil, each with trend and low in EUR. A finish Cardmarket has no trend for is null, null. |
Price history
/prices/:riftboundId/history returns one printing's daily
prices over time, by seller and finish. Narrow a shared Riftbound id with
collector and slug, as for /prices.
range is a preset — 1m, 3m (the
default), 6m, 1y or all — and the
server picks the bucket so no series has more than about 400 points: days
up to a year, then weeks, then months, each bucket the average of its
days. source and finish take comma lists to
narrow the series. History begins on 2026-11-09; nothing older exists at
either seller.
{
"object": "price_history",
"printing_id": "…",
"riftbound_id": "ogn-275-298",
"range": "3m", "from": "2026-08-09", "to": "2026-11-09", "bucket": "day",
"dates": ["2026-08-09", "2026-08-10", …], // one per bucket, every bucket in the range
"series": {
"tcgplayer": { "currency": "USD", "field": "market", "normal": [0.11, null, …], "foil": [0.39, …] },
"cardmarket": { "currency": "EUR", "field": "trend", "normal": [0.08, …], "foil": [0.31, …] }
}
}
Each finish array lines up with dates; null is a
day with no figure. A finish with no figures in the whole range is left out.
One printing per request: there is no bulk history.
Affiliate links
The purchase_uris.tcgplayer value on every card, and the
purchaseUri on every price row, are affiliate links. RiftHunt
earns a commission when someone buys through one. They are how this API
stays free and keyless, and you are welcome to use them in your own app.
The Cardmarket links are not affiliate links; they carry a
utm_source so Cardmarket can see where its visitors come from,
and nothing else.
Deprecations
These fields are still served, so nothing that reads them breaks today. They will be removed soon. Switch to the replacement now.
| Field | Where | Use instead | Why |
|---|---|---|---|
| idDeprecated | /bulk/cards | printing_id | It is our ingest's source record id, not the card object's id, so one name meant two different things. |
| oracleIdDeprecated | /bulk/cards | oracle_id | The same value under the name it first shipped with. oracle_id matches the card object. |
Using an AI coding assistant
If you build with Claude, Copilot, Cursor or similar, paste this in at the start. It covers the things an assistant would otherwise guess wrong.
I'm building with the RiftHunt API for Riftbound card data. Facts to rely on:
- Base URL https://api.rifthunt.com. GET only, JSON, no key, CORS open. Docs: https://rifthunt.com/api/
- For more than a few hundred cards, download the bulk files once and work locally instead of calling per card:
/bulk/cards (every printing, ~1.2 MB, refresh at most daily) and /bulk/prices (refresh at most daily).
- Send a User-Agent naming my project. When calling in a loop, wait about a second between requests.
- Each printing has a permanent printing_id (UUID) and an oracle_id (UUID shared by every printing of the
same card). Join cards, prices and API results on printing_id; group printings into cards on oracle_id.
- In /bulk/cards, "id" and "oracleId" are deprecated. Never read them: use printing_id and oracle_id.
- riftboundId is NOT unique (Metal promos share it with the base printing). Never key on it alone.
- "finishes" on a printing lists the finishes it is made in (["normal","foil"], ["foil"], ["normal"], or null if
unknown). Every price row reports both finishes; a finish missing from the printing's list does not exist,
and one that is listed with null prices has no current listings.
- "power" is the rune cost, not a combat stat; "might" is the only combat stat.
- /bulk/cards is camelCase with capitalised values (type "Unit", domains ["Fury"]). The API card object
(/cards/search, /cards/:id) is snake_case with lowercased domains, rarity and tags.
- Search uses the site's syntax (https://rifthunt.com/syntax/), e.g. /cards/search?q=t:unit d:fury e<=3.
Add unique=prints for every printing. No match is a 404, not an empty list.
- "legalities" on the card object (not in /bulk/cards) has, per format (standard, 2v2), a status of legal, banned or
not_legal and a banned_from date. A ban is announced before it applies: until then status is "legal" and
banned_from is in the future. To know if a card is playable on a given day, compare banned_from to that day.
- purchase_uris.tcgplayer and purchaseUri are affiliate links; keep them if linking to TCGplayer.
- "prices" is TCGplayer in USD; "cardmarket_prices" (and the "cardmarket" block of /bulk/prices) is Cardmarket in EUR,
with "trend" as its headline figure. Never convert one into the other or add them up.
- Card names, text and images are Riot Games' (unofficial Fan Content). Caching
Responses are cached at Cloudflare's edge, so most requests never reach the origin. Respect these and you will rarely notice a limit exists.
| Endpoint | Browser | Edge |
|---|---|---|
| /cards/search | 60s browser | 1h edge, 24h stale-while-revalidate |
| /cards/:id, /cards/named | 1h browser | 24h edge |
| /sets, /sets/:code | 1h browser | 24h edge |
| /bulk/cards | 1h browser | 24h edge, 7d stale-while-revalidate |
| /bulk/rulings, /cards/:id/rulings | 1h browser | 24h edge, 7d stale-while-revalidate |
| /bulk/prices, /prices/:id | 5–10m browser | 15–30m edge, 24h stale-while-revalidate |
| /tags, /cards/:id/tags, and any search using otag: or art: | 30s browser | 1m edge, 5m stale-while-revalidate |
Examples
# shell
curl -s "https://api.rifthunt.com/cards/search?q=t:gear%20p:1"
# PowerShell: note curl is an alias for Invoke-WebRequest, so use the native cmdlet
Invoke-RestMethod "https://api.rifthunt.com/sets" | Select-Object -ExpandProperty data
# browser / Node
const res = await fetch("https://api.rifthunt.com/cards/named?exact=Blind Fury");
const card = await res.json();
console.log(card.energy, card.power, card.domains); Changelog
Every change a consumer can see since launch, newest first: new routes, fields and syntax, data corrections, and anything that changed shape. Fields on their way out are under deprecations.
| Date | Change |
|---|---|
| 2026-11-19 | Variant marks the base printing. Variant previously had a null value to denote that a printing was either the base printing or didn't have a variant. Now the base printing of each card has variant value of "base" if it's the base printing. Null means only that the printing has no variant, such as a promo or a later reprint. We've also added this field to /bulk/cards so there is consistency across the API. |
| 2026-11-17 | Legalities on the card object. legalities gives each format's status and banned_from, the date a ban applies from. A ban Riot has announced is listed with its date before it takes effect, and banned:upcoming finds those cards in search. |
| 2026-11-17 | Radiance ban list. Eight cards and two battlefields are banned in Standard and 2v2 from 2026-11-23: Riven, Broken Blade; Zhonya's Hourglass; Stellacorn Herder; Nocturne, Horrifying; Rhasa the Sunderer; Brynhir Thundersong; Dazzling Aurora; Baited Hook; Emperor's Dais; Star Spring. f:, legal: and banned: change on that date, not before. |
| 2026-11-09 | Cardmarket prices, in EUR. cardmarket_prices, cardmarket_id and purchase_uris.cardmarket on the card object; a cardmarket block in /bulk/prices; cardmarketId and cardmarketUrl in /bulk/cards. TCGplayer stays in USD and nothing is converted. |
| 2026-11-09 | Price history. /prices/:riftboundId/history?range= returns one printing's daily prices by seller and finish, bucketed by day, week or month. History is kept from this date. |
| 2026-11-09 | Sort by EUR, and sorting inside the query. order=eur, with eur: and eurfoil: filters. sort:, dir: and unique: (also order: and direction:) can be written in q and beat the parameter of the same name. |
| 2026-11-06 | Permanent ids and finishes. printing_id and oracle_id on the card object and in /bulk/cards, frozen from this date. finishes lists the finishes a printing is made in. In /bulk/cards, id and oracleId are deprecated. |
| 2026-11-03 | Rulings. /cards/:id/rulings and /bulk/rulings, with rulings_uri on every card. From Riftbound FAQ, CC BY-SA 4.0. |
| 2026-11-03 | Any format. f:any and banned:any in search. |
Terms
Free for any use, commercial included. RiftHunt is unofficial Fan Content under Riot Games' Legal Jibber Jabber policy: card names, text and images are Riot's, and your project inherits the same terms. A link back is appreciated but not required.