openapi: 3.0.3 info: title: YGOPRODeck Yu-Gi-Oh! Card Database API version: v7 description: | YGOPRODeck is a free, community-run REST API for the complete Yu-Gi-Oh! Trading Card Game corpus. The v7 API exposes card search and filtering, card sets, archetypes, the valid value enumerations used by the search engine (types, races, attributes, link markers), the underlying database version, and a random-card endpoint. No authentication is required; the documented rate limit is 20 requests per second per IP (one-hour ban on violation). All card text and imagery is copyright Konami Digital Entertainment / 4K Media. This spec is a third-party API description, generated from the YGOPRODeck API Guide (https://ygoprodeck.com/api-guide/) and live response inspection. termsOfService: https://ygoprodeck.com/api-guide/ contact: name: YGOPRODeck url: https://ygoprodeck.com/ license: name: Community / Unspecified url: https://ygoprodeck.com/about/ x-generated-from: documentation x-last-validated: '2026-05-30' externalDocs: description: YGOPRODeck API Guide url: https://ygoprodeck.com/api-guide/ servers: - url: https://db.ygoprodeck.com/api/v7 description: YGOPRODeck v7 production API tags: - name: Cards description: Card search, filtering, and metadata retrieval. - name: Card Sets description: Yu-Gi-Oh! card set catalog and per-print details. - name: Archetypes description: Recognised Yu-Gi-Oh! archetype catalog. - name: Reference Data description: Valid value enumerations used by the search engine. - name: Database description: Database version and freshness information. paths: /cardinfo.php: get: tags: - Cards operationId: searchCards summary: YGOPRODeck Search Cards description: | Search and filter the complete Yu-Gi-Oh! card database. Without parameters, returns all cards (large payload — clients should always pass filters). Filter by name, fuzzy name, passcode id, type, race, attribute, level, link rating, link markers, ATK/DEF (with comparison operators `lt`, `lte`, `gt`, `gte`), pendulum scale, archetype, banlist, format, and more. Supports sorting, pagination (`num` + `offset`), language switching, and an extended metadata mode via `misc=yes`. parameters: - name: name in: query description: Exact card name. Use a pipe (`|`) to query multiple names in one call (e.g. `Baby Dragon|Time Wizard`). required: false schema: type: string example: Dark Magician - name: fname in: query description: Fuzzy / partial card name search. required: false schema: type: string example: Magician - name: id in: query description: Card passcode (8-digit numeric id). Comma-separated for multiple ids. required: false schema: type: string example: '46986414' - name: konami_id in: query description: Konami official card id (different from the printed passcode). required: false schema: type: string example: '4007' - name: type in: query description: Card type (e.g. `Effect Monster`, `Synchro Monster`, `Spell Card`, `Trap Card`, `Link Monster`). required: false schema: type: string enum: - Effect Monster - Flip Effect Monster - Flip Tuner Effect Monster - Fusion Monster - Gemini Monster - Link Monster - Normal Monster - Normal Tuner Monster - Pendulum Effect Fusion Monster - Pendulum Effect Monster - Pendulum Effect Ritual Monster - Pendulum Flip Effect Monster - Pendulum Normal Monster - Pendulum Tuner Effect Monster - Ritual Effect Monster - Ritual Monster - Skill Card - Spell Card - Spirit Monster - Synchro Monster - Synchro Pendulum Effect Monster - Synchro Tuner Monster - Token - Toon Monster - Trap Card - Tuner Monster - Union Effect Monster - XYZ Monster - XYZ Pendulum Effect Monster example: Spellcaster - name: race in: query description: Monster race (for monsters) or sub-type (for Spell/Trap, e.g. `Continuous`, `Quick-Play`, `Counter`). required: false schema: type: string example: Spellcaster - name: attribute in: query description: Monster attribute. required: false schema: type: string enum: - DARK - LIGHT - WATER - FIRE - WIND - EARTH - DIVINE example: DARK - name: level in: query description: Monster level or rank. Supports comparison operators `lt`, `lte`, `gt`, `gte` (e.g. `gte4`). required: false schema: type: string example: '7' - name: link in: query description: Link rating for Link Monsters. required: false schema: type: integer example: 4 - name: linkmarker in: query description: Link marker positions (one or more, comma-separated). Values are `Top`, `Bottom`, `Left`, `Right`, `Top-Left`, `Top-Right`, `Bottom-Left`, `Bottom-Right`. required: false schema: type: string example: Top,Bottom - name: atk in: query description: ATK value filter. Supports comparison operators `lt`, `lte`, `gt`, `gte` (e.g. `gte2500`). required: false schema: type: string example: gte2500 - name: def in: query description: DEF value filter. Supports comparison operators `lt`, `lte`, `gt`, `gte`. required: false schema: type: string example: lt2000 - name: scale in: query description: Pendulum scale value. required: false schema: type: integer example: 4 - name: archetype in: query description: Archetype name (see `/archetypes.php` for the complete list). required: false schema: type: string example: Blue-Eyes - name: cardset in: query description: Card set name (see `/cardsets.php` for the complete list). required: false schema: type: string example: Metal Raiders - name: banlist in: query description: Banlist type to filter against. required: false schema: type: string enum: - TCG - OCG - Goat example: TCG - name: format in: query description: Tournament format legality filter. required: false schema: type: string enum: - tcg - ocg - goat - ocg goat - speed duel - master duel - rush duel - duel links - genesys example: master duel - name: staple in: query description: Pass `yes` to filter to staple cards only. required: false schema: type: string enum: - 'yes' example: 'yes' - name: has_effect in: query description: Pass `true` or `false` to filter cards by whether they have an actual effect. required: false schema: type: boolean example: true - name: sort in: query description: Sort order for the result set. required: false schema: type: string enum: - atk - def - name - type - level - id - new example: atk - name: misc in: query description: Pass `yes` to include extended metadata (views, upvotes, formats, treated_as, release dates, konami_id, md_rarity, has_effect, genesys_points). required: false schema: type: string enum: - 'yes' example: 'yes' - name: tcgplayer_data in: query description: Pass `yes` to use TCGplayer card set data instead of the default. required: false schema: type: string enum: - 'yes' example: 'yes' - name: language in: query description: Language code for card text. Default is English (omit). Supported alternatives are `fr`, `de`, `it`, `pt`. required: false schema: type: string enum: - fr - de - it - pt example: fr - name: startdate in: query description: Start date (`YYYY-MM-DD`) for release-date filtering. required: false schema: type: string format: date example: '2024-01-01' - name: enddate in: query description: End date (`YYYY-MM-DD`) for release-date filtering. required: false schema: type: string format: date example: '2024-12-31' - name: dateregion in: query description: Region whose release dates the `startdate`/`enddate` window applies to (e.g. `tcg_date`, `ocg_date`). required: false schema: type: string example: tcg_date - name: num in: query description: Page size (results per page). Pair with `offset` for pagination. required: false schema: type: integer minimum: 1 maximum: 100 example: 20 - name: offset in: query description: Pagination offset (0-based). required: false schema: type: integer minimum: 0 example: 0 responses: '200': description: A page of matching cards. content: application/json: schema: $ref: '#/components/schemas/CardSearchResponse' examples: SearchCards200Example: summary: Default searchCards 200 response x-microcks-default: true value: data: - id: 46986414 name: Dark Magician typeline: - Spellcaster - Normal type: Normal Monster humanReadableCardType: Normal Monster frameType: normal desc: The ultimate wizard in terms of attack and defense. race: Spellcaster atk: 2500 def: 2100 level: 7 attribute: DARK archetype: Dark Magician ygoprodeck_url: https://ygoprodeck.com/card/dark-magician-4087 card_sets: - set_name: Legend of Blue Eyes White Dragon set_code: LOB-EN005 set_rarity: Ultra Rare set_rarity_code: (UR) set_price: '12.99' card_images: - id: 46986414 image_url: https://images.ygoprodeck.com/images/cards/46986414.jpg image_url_small: https://images.ygoprodeck.com/images/cards_small/46986414.jpg image_url_cropped: https://images.ygoprodeck.com/images/cards_cropped/46986414.jpg card_prices: - cardmarket_price: '0.02' tcgplayer_price: '0.24' ebay_price: '0.99' amazon_price: '14.45' coolstuffinc_price: '0.39' meta: current_rows: 1 total_rows: 1 rows_remaining: 0 total_pages: 1 pages_remaining: 0 '400': description: Invalid request — an unknown parameter value was supplied. The error message typically suggests valid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: SearchCards400Example: summary: Default searchCards 400 error response x-microcks-default: true value: error: No card matching your query was found in the database. Please ensure your search query is correct. x-microcks-operation: delay: 0 dispatcher: FALLBACK /randomcard.php: get: tags: - Cards operationId: getRandomCard summary: YGOPRODeck Get Random Card description: | Return a single random Yu-Gi-Oh! card. The endpoint accepts no parameters and its response is intentionally uncached so each call returns a different card. responses: '200': description: A single random card. content: application/json: schema: $ref: '#/components/schemas/Card' examples: GetRandomCard200Example: summary: Default getRandomCard 200 response x-microcks-default: true value: id: 89631146 name: Blue-Eyes White Dragon typeline: - Dragon - Normal type: Normal Monster humanReadableCardType: Normal Monster frameType: normal desc: This legendary dragon is a powerful engine of destruction. Virtually invincible, very few have faced this awesome creature and lived to tell the tale. race: Dragon atk: 3000 def: 2500 level: 8 attribute: LIGHT archetype: Blue-Eyes ygoprodeck_url: https://ygoprodeck.com/card/blue-eyes-white-dragon-4001 x-microcks-operation: delay: 0 dispatcher: FALLBACK /cardsets.php: get: tags: - Card Sets operationId: listCardSets summary: YGOPRODeck List Card Sets description: | Return every Yu-Gi-Oh! card set known to YGOPRODeck — over 1,000 entries — with set name, set code, card count, TCG release date, and set image URL. Takes no parameters. responses: '200': description: The complete card set catalog. content: application/json: schema: type: array items: $ref: '#/components/schemas/CardSet' examples: ListCardSets200Example: summary: Default listCardSets 200 response x-microcks-default: true value: - set_name: Legend of Blue Eyes White Dragon set_code: LOB num_of_cards: 126 tcg_date: '2002-03-08' set_image: https://images.ygoprodeck.com/images/sets/LOB.jpg - set_name: Metal Raiders set_code: MRD num_of_cards: 144 tcg_date: '2002-06-26' set_image: https://images.ygoprodeck.com/images/sets/MRD.jpg x-microcks-operation: delay: 0 dispatcher: FALLBACK /cardsetsinfo.php: get: tags: - Card Sets operationId: getCardSetInfo summary: YGOPRODeck Get Card Set Print Info description: | Look up the per-print details for a specific set-code (e.g. `LOB-EN001`) — the card id, card name, set name, set code, rarity, and market price. parameters: - name: setcode in: query description: Set code identifying a specific card printing (e.g. `LOB-EN001`). required: true schema: type: string example: LOB-EN001 responses: '200': description: Print details for the requested set code. content: application/json: schema: $ref: '#/components/schemas/CardSetPrint' examples: GetCardSetInfo200Example: summary: Default getCardSetInfo 200 response x-microcks-default: true value: id: 89631146 name: Blue-Eyes White Dragon set_name: Legend of Blue Eyes White Dragon set_code: LOB-EN001 set_rarity: Ultra Rare set_price: '253.34' '400': description: No card matching the requested set code. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: GetCardSetInfo400Example: summary: Default getCardSetInfo 400 error response x-microcks-default: true value: error: No card matching your query was found in the database x-microcks-operation: delay: 0 dispatcher: FALLBACK /archetypes.php: get: tags: - Archetypes operationId: listArchetypes summary: YGOPRODeck List Archetypes description: | Return every recognised Yu-Gi-Oh! archetype name. Useful to populate archetype pickers and to validate the `archetype` parameter on `/cardinfo.php`. responses: '200': description: The complete archetype catalog. content: application/json: schema: type: array items: $ref: '#/components/schemas/Archetype' examples: ListArchetypes200Example: summary: Default listArchetypes 200 response x-microcks-default: true value: - archetype_name: Blue-Eyes - archetype_name: Dark Magician - archetype_name: Red-Eyes x-microcks-operation: delay: 0 dispatcher: FALLBACK /cardvalues.php: get: tags: - Reference Data operationId: getCardValues summary: YGOPRODeck Get Valid Card Filter Values description: | Return the canonical valid value enumerations used by the search engine — every card type, monster race, monster attribute, level, link marker, and the per-card-class (MONSTER / SPELL / TRAP / SKILL) breakdowns. Drives client-side dropdowns and validates cardinfo query parameters before submission. responses: '200': description: Valid value enumerations. content: application/json: schema: $ref: '#/components/schemas/CardValues' examples: GetCardValues200Example: summary: Default getCardValues 200 response x-microcks-default: true value: types: - name: Effect Monster group: MONSTER sortGroup: 2 area: - MAIN - SIDE - name: Link Monster group: MONSTER sortGroup: 7 area: - EXTRA - SIDE - name: Spell Card group: SPELL sortGroup: 8 area: - MAIN - SIDE MONSTER: type: - Effect Monster - Normal Monster - Link Monster - XYZ Monster - Synchro Monster - Fusion Monster race: - Dragon - Spellcaster - Warrior - Beast attributes: - DARK - LIGHT - WATER - FIRE - WIND - EARTH - DIVINE level: - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 linkmarkers: - Top - Bottom - Left - Right - Top-Left - Top-Right - Bottom-Left - Bottom-Right SPELL: type: - Spell Card race: - Continuous - Equip - Field - Normal - Quick-Play - Ritual TRAP: type: - Trap Card race: - Continuous - Counter - Normal SKILL: type: - Skill Card race: - Jaden Yuki - Seto Kaiba - Yami Yugi x-microcks-operation: delay: 0 dispatcher: FALLBACK /checkDBVer.php: get: tags: - Database operationId: getDatabaseVersion summary: YGOPRODeck Get Database Version description: | Return the current YGOPRODeck card database version and last-updated timestamp. Clients should poll this endpoint and invalidate their local cache when the version changes. responses: '200': description: Current database version and last-update timestamp. content: application/json: schema: type: array items: $ref: '#/components/schemas/DatabaseVersion' examples: GetDatabaseVersion200Example: summary: Default getDatabaseVersion 200 response x-microcks-default: true value: - database_version: '145.46' last_update: '2026-05-22 16:00:23' x-microcks-operation: delay: 0 dispatcher: FALLBACK components: schemas: Card: type: object description: A single Yu-Gi-Oh! card, including metadata, set printings, image URLs, and marketplace prices. properties: id: type: integer description: 8-digit Yu-Gi-Oh! card passcode (unique per card). example: 46986414 name: type: string description: Card name (in the requested language). example: Dark Magician typeline: type: array description: Type line tokens (e.g. `["Spellcaster", "Normal"]`). items: type: string example: - Spellcaster - Normal type: type: string description: Card type (e.g. `Normal Monster`, `Effect Monster`, `Spell Card`, `Trap Card`, `Link Monster`). example: Normal Monster humanReadableCardType: type: string description: Human-friendly version of the card type. example: Normal Monster frameType: type: string description: The card frame style (e.g. `normal`, `effect`, `synchro`, `xyz`, `link`, `spell`, `trap`). example: normal desc: type: string description: Card effect / flavour text. example: The ultimate wizard in terms of attack and defense. race: type: string description: Monster race (e.g. `Spellcaster`, `Dragon`) or Spell/Trap sub-type (`Continuous`, `Quick-Play`, `Counter`). example: Spellcaster atk: type: integer description: Attack value (monsters only). example: 2500 def: type: integer description: Defense value (non-Link monsters only). example: 2100 level: type: integer description: Card level or rank (monsters only). example: 7 attribute: type: string description: Monster attribute. enum: - DARK - LIGHT - WATER - FIRE - WIND - EARTH - DIVINE example: DARK linkval: type: integer description: Link rating (Link Monsters only). example: 4 linkmarkers: type: array description: Link marker positions (Link Monsters only). items: type: string enum: - Top - Bottom - Left - Right - Top-Left - Top-Right - Bottom-Left - Bottom-Right example: - Top - Bottom-Left - Bottom-Right scale: type: integer description: Pendulum scale value (Pendulum monsters only). example: 4 archetype: type: string description: Archetype the card belongs to (e.g. `Blue-Eyes`, `Dark Magician`). example: Dark Magician ygoprodeck_url: type: string format: uri description: Canonical YGOPRODeck card page URL. example: https://ygoprodeck.com/card/dark-magician-4087 card_sets: type: array description: Every set printing this card has appeared in. items: $ref: '#/components/schemas/CardPrintingEntry' card_images: type: array description: Available image URLs for each artwork variant of this card. items: $ref: '#/components/schemas/CardImage' card_prices: type: array description: Marketplace prices aggregated across Cardmarket, TCGplayer, eBay, Amazon, and CoolStuffInc. items: $ref: '#/components/schemas/CardPrice' misc_info: type: array description: Extended metadata, present only when the search was made with `misc=yes`. items: $ref: '#/components/schemas/CardMiscInfo' required: - id - name - type - frameType - desc CardPrintingEntry: type: object description: A single set printing of a card. properties: set_name: type: string description: Set name (e.g. `Legend of Blue Eyes White Dragon`). example: Legend of Blue Eyes White Dragon set_code: type: string description: Set code identifying this printing (e.g. `LOB-EN001`). example: LOB-EN001 set_rarity: type: string description: Rarity of this printing. example: Ultra Rare set_rarity_code: type: string description: Short rarity code (e.g. `(UR)`). example: (UR) set_price: type: string description: Price of this printing (USD, stringified decimal). example: '6.97' required: - set_name - set_code - set_rarity CardImage: type: object description: Image URLs for a single artwork variant of a card. properties: id: type: integer description: Image id (matches the card id for the default artwork; differs for alternate artworks). example: 46986414 image_url: type: string format: uri description: Full-size card image URL. Do not hotlink — download and self-host. example: https://images.ygoprodeck.com/images/cards/46986414.jpg image_url_small: type: string format: uri description: Small / thumbnail image URL. example: https://images.ygoprodeck.com/images/cards_small/46986414.jpg image_url_cropped: type: string format: uri description: Cropped artwork-only image URL (no frame). example: https://images.ygoprodeck.com/images/cards_cropped/46986414.jpg required: - id - image_url - image_url_small - image_url_cropped CardPrice: type: object description: Marketplace prices for a card (USD, stringified decimal). properties: cardmarket_price: type: string description: Cardmarket price (USD). example: '0.02' tcgplayer_price: type: string description: TCGplayer price (USD). example: '0.24' ebay_price: type: string description: eBay price (USD). example: '0.99' amazon_price: type: string description: Amazon price (USD). example: '14.45' coolstuffinc_price: type: string description: CoolStuffInc price (USD). example: '0.39' CardMiscInfo: type: object description: Extended per-card metadata returned only when `misc=yes` is passed to `/cardinfo.php`. properties: beta_name: type: string description: Original beta name (if different from the released name). views: type: integer description: YGOPRODeck card page view count. example: 152340 viewsweek: type: integer description: YGOPRODeck card page view count over the last 7 days. example: 421 upvotes: type: integer description: Community upvote count. example: 540 downvotes: type: integer description: Community downvote count. example: 12 formats: type: array description: Tournament formats the card is legal in. items: type: string example: - TCG - OCG - Master Duel treated_as: type: string description: An alternate card name this card is officially treated as (for ruling purposes). tcg_date: type: string format: date description: TCG (English) release date. example: '2002-03-08' ocg_date: type: string format: date description: OCG (Japanese) release date. example: '1999-02-04' konami_id: type: integer description: Internal Konami card id. example: 4007 has_effect: type: integer description: 1 if the card has an actual rules effect; 0 if not. example: 0 md_rarity: type: string description: Master Duel rarity (if applicable). example: UR genesys_points: type: integer description: GenesYS-format point cost. Only returned when `format=genesys` is passed. example: 100 question_atk: type: integer description: 1 if the card has `?` as ATK (special-case Pendulum/Effect ATK). question_def: type: integer description: 1 if the card has `?` as DEF. staple: type: string description: '`yes` if YGOPRODeck classifies this card as a staple in any format.' CardSet: type: object description: A Yu-Gi-Oh! card set (booster pack, structure deck, tin, etc.). properties: set_name: type: string description: Set name. example: Legend of Blue Eyes White Dragon set_code: type: string description: Set code prefix (e.g. `LOB`). example: LOB num_of_cards: type: integer description: Number of cards in the set. example: 126 tcg_date: type: string format: date description: TCG release date. example: '2002-03-08' set_image: type: string format: uri description: Set image URL. example: https://images.ygoprodeck.com/images/sets/LOB.jpg required: - set_name - set_code CardSetPrint: type: object description: Per-print details for a specific set code (single card printing). properties: id: type: integer description: Card id (passcode). example: 89631146 name: type: string description: Card name. example: Blue-Eyes White Dragon set_name: type: string description: Set name. example: Legend of Blue Eyes White Dragon set_code: type: string description: Full set code identifying this printing. example: LOB-EN001 set_rarity: type: string description: Rarity of this printing. example: Ultra Rare set_price: type: string description: Price of this printing (USD, stringified decimal). example: '253.34' required: - id - name - set_name - set_code - set_rarity Archetype: type: object description: A recognised Yu-Gi-Oh! archetype. properties: archetype_name: type: string description: Archetype name. example: Blue-Eyes required: - archetype_name CardValues: type: object description: Valid value enumerations used by the search engine, broken down by card class. properties: types: type: array description: Every card type with its group and sort order. items: $ref: '#/components/schemas/CardTypeEntry' MONSTER: $ref: '#/components/schemas/MonsterValues' SPELL: $ref: '#/components/schemas/CardClassValues' TRAP: $ref: '#/components/schemas/CardClassValues' SKILL: $ref: '#/components/schemas/CardClassValues' CardTypeEntry: type: object description: Metadata for a single card type used by sort/filter UIs. properties: name: type: string description: Card type name. example: Effect Monster group: type: string description: Top-level card class. enum: - MONSTER - SPELL - TRAP - SKILL example: MONSTER sortGroup: type: integer description: Sort order for displaying types together. example: 2 area: type: array description: Deck areas where this type may be placed. items: type: string enum: - MAIN - EXTRA - SIDE example: - MAIN - SIDE MonsterValues: type: object description: Valid values for monster filters. properties: type: type: array description: All monster types. items: type: string race: type: array description: All monster races. items: type: string attributes: type: array description: All monster attributes. items: type: string level: type: array description: Valid monster levels / ranks. items: type: integer linkmarkers: type: array description: Valid link marker positions. items: type: string CardClassValues: type: object description: Valid values for a non-monster card class (Spell, Trap, or Skill). properties: type: type: array description: Types within this card class. items: type: string race: type: array description: Sub-types or races within this card class. items: type: string DatabaseVersion: type: object description: Current YGOPRODeck card database version. properties: database_version: type: string description: Database version (semver-like). example: '145.46' last_update: type: string description: Last update timestamp (`YYYY-MM-DD HH:MM:SS`, UTC). example: '2026-05-22 16:00:23' required: - database_version - last_update CardSearchResponse: type: object description: Wrapper response for `/cardinfo.php` queries. properties: data: type: array description: The matched cards. items: $ref: '#/components/schemas/Card' meta: $ref: '#/components/schemas/SearchMeta' required: - data SearchMeta: type: object description: Pagination metadata included when `num` and `offset` are used. properties: current_rows: type: integer description: Number of rows in the current page. example: 20 total_rows: type: integer description: Total number of rows matched by the query. example: 144 rows_remaining: type: integer description: Rows remaining after this page. example: 124 total_pages: type: integer description: Total number of pages. example: 8 pages_remaining: type: integer description: Pages remaining after this one. example: 7 next_page: type: string format: uri description: URL for the next page. next_page_offset: type: integer description: Offset value for the next page. ErrorResponse: type: object description: Standard YGOPRODeck error envelope. Returned with HTTP 400 for invalid requests. properties: error: type: string description: Human-readable error message. Often includes suggested valid values. example: No card matching your query was found in the database. required: - error