openapi: 3.0.3
info:
title: YGOPRODeck Yu-Gi-Oh! Card Database Archetypes Cards 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'
servers:
- url: https://db.ygoprodeck.com/api/v7
description: YGOPRODeck v7 production API
tags:
- name: Cards
description: Card search, filtering, and metadata retrieval.
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
components:
schemas:
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
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
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.
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'
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
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.'
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
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
externalDocs:
description: YGOPRODeck API Guide
url: https://ygoprodeck.com/api-guide/