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

RequestReturns
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/:idOne card by its UUID.
GET /setsEvery set, with printing counts.
GET /sets/:codeOne set by code, e.g. ogn.
GET /bulk-dataIndex of the bulk exports.
GET /bulk/cardsThe whole catalogue: 1732 printings, ~1.2 MB.
GET /bulk/pricesTCGplayer prices (USD) for 1676 printings, and Cardmarket's (EUR). Refreshed daily.
GET /prices/:riftboundIdPrices 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/:slugOne tag: description, count, creator, and the search that lists its cards.
GET /cards/:id/tagsEvery community tag on one printing: function tags from its card, art tags of its own.
GET /bulk/tagsEvery tagging, one row per (tag, printing). What the site builds from.
GET /cards/:id/rulingsRulings for the card, from Riftbound FAQ. The same list for every printing.
GET /bulk/rulingsEvery ruling, one entry per card. What the site builds from.
GET /healthLiveness check.

Searching

/cards/search takes the same query syntax as the site's search box, documented in full on the syntax guide.

ExampleFinds
/cards/search?q=t:unit d:fury e<=3Cheap Fury units.
/cards/search?q=t:gear p:1Gear costing one rune.
/cards/search?q=s:ogn r:epicEpics 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

FieldMeaning
objectAlways "card".
idPermanent UUID for this printing. Use it with /cards/:id.
printing_idThe 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_idPermanent UUID shared by every printing of the same card. Also in /bulk/cards.
langLanguage of the text fields. Only "en" today.
namePrinted name, including any variant suffix, e.g. "Annie, Dark Child (Metal)".
oracle_nameThe base name shared by every printing, e.g. "Annie, Dark Child".
typeUnit, Spell, Gear, Legend, Battlefield or Rune.
domainsLowercased array. Also which runes may pay the rune cost.
energyEnergy cost. null when there is none.
powerRune cost: how many runes are recycled to play it. null when there is none.
mightCombat stat on units. null otherwise.
keywordsLowercased array.
tagsLowercased array. Searchable with tag:.
rules_textPlain text. Keeps :rb_*: symbol shortcodes.
flavor_textPlain text, or null.
setSet code, lowercased, e.g. "ogn".
set_nameFull set name.
collector_numberAs printed, zero-padded, e.g. "017". Letter-prefixed (t, r, s) for tokens, runes and special promos.
raritycommon, uncommon, rare, epic, showcase or promo.
artistIllustrator, or null.
variantWhat 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_idRiot's own id, e.g. ogn-025-298. Not unique: 52 promos share one.
rifthunt_uriCanonical path for this printing on rifthunt.com.
rulings_uriPath to the card's rulings, /cards/:id/rulings. An empty list when there are none.
legalitiesObject 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.
imagesObject 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_idTCGplayer product id, or null. Build your own link with it if you prefer.
cardmarket_idCardmarket product id, or null. Cardmarket URLs cannot be built from it; use purchase_uris.cardmarket.
finishesThe 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_urisObject with tcgplayer (an affiliate link, see below) and cardmarket (the product page, or a name search; not an affiliate link).
pricesTCGplayer prices per finish in USD, or null if we have none. See below.
cardmarket_pricesCardmarket 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

FieldMeaning
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

FieldMeaning
printing_idThe printing, as in /bulk/cards and on the card object. Join on this.
riftboundIdRiot's id. Not unique on its own.
collectorCollector number as printed, e.g. "017".
slugThe URL slug of the printing's page, e.g. "annie-dark-child-metal".
tcgIdTCGplayer product id.
purchaseUriAffiliate link to the product on TCGplayer.
updatedAtWhen the price was fetched.
finishesAn 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.

FieldMeaning
printing_idThe printing. Join on this.
riftboundId, collector, slugThe older key, as above.
cardmarketIdCardmarket product id.
purchaseUriThe product page on Cardmarket where we know it, otherwise a name search. Not an affiliate link.
updatedAtWhen the price guide was read.
finishesAn 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.

FieldWhereUse insteadWhy
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.

EndpointBrowserEdge
/cards/search60s browser1h edge, 24h stale-while-revalidate
/cards/:id, /cards/named1h browser24h edge
/sets, /sets/:code1h browser24h edge
/bulk/cards1h browser24h edge, 7d stale-while-revalidate
/bulk/rulings, /cards/:id/rulings1h browser24h edge, 7d stale-while-revalidate
/bulk/prices, /prices/:id5–10m browser15–30m edge, 24h stale-while-revalidate
/tags, /cards/:id/tags, and any search using otag: or art:30s browser1m 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.

DateChange
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.