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/