A Scryfall-style REST API for Riftbound (League of Legends TCG) card data. Phase 1: Card data API. Phase 2: LLM-powered natural language card search and deck advice.
Riftbound is Riot Games' physical TCG launched October 2025, built on League of Legends IP. It currently has two released sets — Origins (OGN, ~377 cards) and Spiritforged (SFD, ~220 cards) — with three more announced for 2026: Unleashed (May), Vendettas (Q3), and Radiance (Q4). The game uses a territory-control mechanic (not life totals), where units have a single stat (Might) and players score by conquering battlefields.
There is no community-run open card API equivalent to Scryfall for MTG. This project fills that gap.
The single source of truth. Riot exposes a dedicated Riftbound endpoint through their Developer Portal.
Endpoint: GET /riftbound/content/v1/contents
Access: Requires a Riot API key from developer.riotgames.com. You must apply with a description of your app — card galleries and deck builders are explicitly listed as approved use cases. During beta, only en locale is available.
Response schema (derived from community Go/Rust wrappers, as official docs have known inaccuracies — see issue #1093):
RiftboundContentV1DTO
├── sets: ContentSetV1DTO[]
│ ├── id: string // e.g. "OGN"
│ ├── name: string // e.g. "Origins"
│ └── cards: ContentCardV1DTO[]
│ ├── id: string
│ ├── name: string
│ ├── type: string
│ ├── faction: string
│ ├── rarity: string
│ ├── description: string // rules text
│ ├── flavorText: string
│ ├── keywords: string[]
│ ├── tags: string[]
│ ├── set: string
│ ├── collectorNumber: int
│ ├── stats: CardStatsV1DTO
│ │ ├── cost: int
│ │ ├── energy: int
│ │ ├── might: int
│ │ └── power: int
│ └── media: MediaDTO[] // NOTE: actual response uses `media`, not `art`
│ ├── type: string
│ ├── url: string // relative path — base URL undocumented
│ └── name: string
Known issues:
- The documented
artfield (withthumbnailURL,fullURL,artist) does not match the actual response, which returns amediaarray instead. Image URL base domain is undocumented — community projects have reverse-engineered it. - Only English locale available during beta.
Rate limits: Standard Riot API limits apply (20 requests per second / 100 per 2 minutes for development keys).
Policy notes: Riot explicitly encourages card gallery / deck builder apps. Monetization is allowed with a free tier requirement. You must use only assets provided through the Riot API. Official English card text is mandatory; translations must display alongside it. See the full Digital Tools Policy.
Existing wrappers:
- Go:
github.com/Kyagara/equinox— auto-generated client with typed DTOs - Rust:
riven—riftbound_content_v1()endpoint handle
scrydex.com operates a multi-TCG API (Pokémon, Lorcana, MTG, Riftbound, etc.) with a richer card schema than the raw Riot API. Currently in beta for Riftbound.
Endpoints:
GET /riftbound/v1/cards/<id>— single card by ID (e.g.OGN-296)GET /riftbound/v1/cards— paginated search across all cardsGET /riftbound/v1/expansions/<code>/cards— scoped to expansion
Auth: API key + team ID via X-Api-Key and X-Team-ID headers.
Enriched fields beyond Riot API:
domain(color/faction mapped to a named domain like "Fire", "Water", "Colorless")printed_number(e.g. "296/298")artistas a top-level fieldrulesas a string arrayvariantswith pricing data (normal/foil, condition, market prices, trends)imageswith small/medium/large URLs already resolvedexpansionobject withrelease_date,logo,total,printed_total
Search: Lucene-like query syntax (name:void, type:Battlefield, expansion.id:OGN), wildcards, exact matching, nested field access, ordering, and field selection.
Tradeoffs: Commercial product with rate limits and credit-based pricing. Good for cross-referencing pricing data and as a validation layer, but introduces a third-party dependency. Best used as a secondary enrichment source, not the primary data pipeline.
riftbound.leagueoflegends.com/en-us/card-gallery — Riot's own card browser. The page is fully client-side rendered (React/SPA), so the HTML source contains no card data. The actual card data is loaded via XHR/fetch calls to internal APIs.
Approach: Use browser devtools (or headless Chromium) to intercept the network requests the gallery makes. These internal API responses likely contain the full card dataset in JSON format with resolved image URLs. This is the same data the Riot API serves, but potentially with the image base URLs already resolved.
Status: Several community projects have successfully scraped this — Piltover Archive and riftbound.gg both source from it. Not a stable API contract, but useful for bootstrapping.
| Source | Format | Notes |
|---|---|---|
| OwenMelbz/riftbound.json | JSON Gist | Full v1 card dump, likely from Riot API. Good for bootstrapping. |
| dragogodev/cgs | JSON | Card Game Simulator data repo — includes Riftbound alongside dozens of other TCGs. Structured for TTS/digital play. |
| oriondean/Rifty | Web app | Fan collection tracker with embedded card data, organized by set. |
| NewtonGluten/riftboundbot | JS | Discord bot with a riftbound-scraper directory — includes image grabber and card data extraction. |
| LEG1TxCHA0S/riftbound-discord-bot | JS | Polls the official riftbound-content-v1 endpoint, diffs against known card IDs, and posts new cards to Discord. Good reference for the sync pattern. |
| Source | Coverage | Notes |
|---|---|---|
| Scrydex | NM raw, graded, foil/normal variants | Market price, low price, 1-day and 7-day trends |
| JustTCG | Multi-TCG pricing API | Real-time pricing, condition grading, foil tracking |
| PriceCharting | eBay-derived pricing | Ungraded & graded values, set population data |
- Spiritforged FAQ — errata, rules patches, reflexive triggers
- State of the Game — ban philosophy, meta health, format rules
- Official rules/news RSS from
riftbound.leagueoflegends.com/en-us/news/
┌─────────────────────────┐
│ Riot API (primary) │
│ riftbound-content-v1 │
└────────┬────────────────┘
│ scheduled sync (daily)
▼
┌─────────────────────────┐
│ Ingestion Worker │
│ - normalize schema │
│ - resolve image URLs │
│ - detect new cards │
│ - apply errata │
└────────┬────────────────┘
│
┌─────────────┼──────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────┐ ┌─────────────┐
│ PostgreSQL │ │ Images │ │ Changelog │
│ card data │ │ (S3/R2) │ │ (new cards │
│ + FTS index │ │ cached │ │ errata) │
└──────┬───────┘ └──────────┘ └─────────────┘
│
▼
┌──────────────────────────────────┐
│ REST API (Phase 1) │
│ /cards, /cards/:id, /sets, │
│ /search, /random, /autocomplete │
└──────────────────────────────────┘
│
▼ (Phase 2)
┌──────────────────────────────────┐
│ LLM Layer │
│ Natural language card search │
│ "find me blue removal spells" │
│ Deck advice, synergy discovery │
└──────────────────────────────────┘
- Riot's rate limits (20 req/s dev) don't support a public-facing API
- The
mediafield has unresolved image URLs that need post-processing - No search/filter — Riot returns the entire card catalog in one response
- No pricing, errata tracking, or computed fields (color identity, legality)
- Building our own layer lets us add full-text search, fuzzy matching, and eventually the LLM layer
Our normalized schema, merging Riot's data with enrichments:
interface Card {
// Identity
id: string; // "OGN-296"
name: string; // "Void Gate"
set_code: string; // "OGN"
set_name: string; // "Origins"
collector_number: string; // "296"
printed_number: string; // "296/298"
// Classification
type: string; // "Battlefield" | "Champion" | "Unit" | "Spell" | "Equipment" | "Legend"
domain: string; // "Fire" | "Water" | "Earth" | "Air" | "Shadow" | "Light" | "Colorless"
rarity: string; // "Common" | "Uncommon" | "Rare" | "Epic"
faction: string; // Runeterra region/faction
// Stats
cost: number | null;
energy: number | null;
might: number | null;
power: number | null;
// Text
rules_text: string; // full rules text
flavor_text: string;
keywords: string[]; // ["Quick-Draw", "Hidden", ...]
tags: string[];
// Media
artist: string;
images: {
small: string;
medium: string;
large: string;
};
// Metadata
legality: Record<string, string>; // format -> legal/banned
errata: string | null; // corrected text if any
released_at: string; // set release date
// Pricing (optional, via enrichment)
prices?: {
normal?: { low: number; market: number; currency: string };
foil?: { low: number; market: number; currency: string };
};
}GET /v1/cards # paginated list, filterable
GET /v1/cards/:id # single card by ID
GET /v1/cards/search?q= # full-text + structured search
GET /v1/cards/random # random card
GET /v1/cards/autocomplete?q= # name autocomplete (prefix)
GET /v1/sets # all sets
GET /v1/sets/:code # single set with metadata
GET /v1/sets/:code/cards # all cards in a set
GET /v1/symbols # domain/keyword icon catalog
GET /v1/bulk # full data dump (JSON download)
Search syntax (Scryfall-inspired):
name:jinx— cards with "jinx" in the nametype:champion domain:fire— fire championscost:3 rarity:rare— 3-cost rareskeyword:hidden— cards with Hidden keywordset:SFD— Spiritforged cards onlyrules:"bonus damage"— phrase search in rules text
Natural language interface on top of the card data:
- Semantic search: "find me cheap removal that works at any battlefield"
- Deck advice: "what cards synergize with Draven's aggro playstyle?"
- Rules Q&A: "how does Hidden interact with Quick-Draw?"
- Meta context: bring in errata and rules patches as RAG context
Implementation: embed card rules text + keywords → vector store, use Claude as the reasoning layer with card data as tool calls.
Per Riot's Digital Tools Policy:
- Approved use case: Card galleries and deck builders are explicitly encouraged
- API key required: Must apply through the Developer Portal with app description
- Assets: Must use only Riot API-provided assets (card art, text)
- Card text: Must display official English text; translations alongside only
- Monetization: Allowed with a free tier. Content must be transformative.
- Prohibited: Automated rules enforcement, gameplay simulation, metagame-defining data (win rates, play rates)
- Attribution: Must include the statement from Section 6 of Riot's Legal Jibber Jabber
TBD — see questions at top. Recommended baseline:
- Runtime: Node.js / TypeScript
- Framework: Fastify or Express
- Database: PostgreSQL with
pg_trgmfor fuzzy search - Cache: Redis for hot card lookups and rate limiting
- Image proxy: Cloudflare R2 or S3 for cached card images
- Deployment: Docker → Fly.io or Railway
# 1. Get a Riot API key
# https://developer.riotgames.com → Register → Apply for Riftbound access
# 2. Clone and install
git clone https://github.com/Fbartoli/riftbound-api.git
cd riftbound-api
npm install
# 3. Configure
cp .env.example .env
# Set RIOT_API_KEY=RGAPI-...
# 4. Seed database from Riot API
npm run seed
# 5. Start
npm run dev- Riot Developer Portal — Riftbound Docs
- Riot API — riftbound-content-v1
- Scrydex Riftbound API Docs
- Scryfall API (design inspiration)
- Piltover Archive (community reference)
- Riftbound.gg (community reference)