Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: YGOPRODeck Yu-Gi-Oh! Card Database Cards API
version: v7
description: YGOPRODeck is a free, community-run REST API for the complete Yu-Gi-Oh!
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
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
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
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.'
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'
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.
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
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/