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
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/yu-gi-oh/refs/heads/main/openapi/yu-gi-oh-ygoprodeck-openapi.yml