Scryfall Cards API

openapi: 3.2.0
info:
  title: Scryfall Cards API
  description: 'The Scryfall API is a REST-like interface to the most comprehensive Magic: The Gathering

    card database.'
  version: '2026-05-29'
  contact:
    name: Scryfall API Support
    url: https://scryfall.com/contact
  license:
    name: Scryfall API License (Free with attribution)
    url: https://scryfall.com/docs/api
  termsOfService: https://scryfall.com/docs/api
servers:
- url: https://api.scryfall.com
  description: Production API
tags:
- name: Cards
  description: Look up, search, and fetch Magic card objects in many ways.
paths:
  /cards/search:
    get:
      tags:
      - Cards
      summary: Search Cards
      description: Returns a List of cards matching a Scryfall full-text search query.
      operationId: searchCards
      parameters:
      - name: q
        in: query
        required: true
        description: A fulltext search query.
        schema:
          type: string
      - name: unique
        in: query
        schema:
          type: string
          enum:
          - cards
          - art
          - prints
          default: cards
      - name: order
        in: query
        schema:
          type: string
          enum:
          - name
          - set
          - released
          - rarity
          - color
          - usd
          - tix
          - eur
          - cmc
          - power
          - toughness
          - edhrec
          - penny
          - artist
          - review
      - name: dir
        in: query
        schema:
          type: string
          enum:
          - auto
          - asc
          - desc
          default: auto
      - name: include_extras
        in: query
        schema:
          type: boolean
          default: false
      - name: include_multilingual
        in: query
        schema:
          type: boolean
          default: false
      - name: include_variations
        in: query
        schema:
          type: boolean
          default: false
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - csv
          default: json
      responses:
        '200':
          description: A list of matching cards.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardList'
        '404':
          description: No cards matched the query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cards/named:
    get:
      tags:
      - Cards
      summary: Get Card by Name
      description: Returns a Card based on a name search string (exact or fuzzy match).
      operationId: getCardByName
      parameters:
      - name: exact
        in: query
        description: The exact card name to search for.
        schema:
          type: string
      - name: fuzzy
        in: query
        description: A fuzzy card name to search for.
        schema:
          type: string
      - name: set
        in: query
        description: A set code to limit the search to one set.
        schema:
          type: string
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - text
          - image
          default: json
      - name: face
        in: query
        schema:
          type: string
          enum:
          - front
          - back
      - name: version
        in: query
        schema:
          type: string
          enum:
          - small
          - normal
          - large
          - png
          - art_crop
          - border_crop
      - name: pretty
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: A single Card object matching the query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '404':
          description: No card matched the name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cards/autocomplete:
    get:
      tags:
      - Cards
      summary: Autocomplete Card Names
      description: Returns a Catalog of up to 20 card-name autocompletions for a partial card-name input.
      operationId: autocompleteCardNames
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      - name: include_extras
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: A catalog of suggested card names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Catalog'
  /cards/random:
    get:
      tags:
      - Cards
      summary: Get a Random Card
      description: Returns a single random Card, optionally filtered by a Scryfall search query.
      operationId: getRandomCard
      parameters:
      - name: q
        in: query
        schema:
          type: string
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - text
          - image
          default: json
      - name: face
        in: query
        schema:
          type: string
          enum:
          - front
          - back
      - name: version
        in: query
        schema:
          type: string
          enum:
          - small
          - normal
          - large
          - png
          - art_crop
          - border_crop
      - name: pretty
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: A randomly chosen Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /cards/collection:
    post:
      tags:
      - Cards
      summary: Get a Card Collection
      description: Accepts a JSON array of card identifiers and returns a List of the requested cards. Identifiers can be id, mtgo_id, multiverse_id, oracle_id, illustration_id, name, set+name, or set+collector_number.
      operationId: getCardCollection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - identifiers
              properties:
                identifiers:
                  type: array
                  maxItems: 75
                  items:
                    type: object
      responses:
        '200':
          description: The requested cards plus any unresolvable identifiers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardList'
  /cards/{id}:
    get:
      tags:
      - Cards
      summary: Get a Card by Scryfall ID
      description: Returns a single Card with the given Scryfall ID.
      operationId: getCardById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - text
          - image
          default: json
      - name: face
        in: query
        schema:
          type: string
          enum:
          - front
          - back
      - name: version
        in: query
        schema:
          type: string
          enum:
          - small
          - normal
          - large
          - png
          - art_crop
          - border_crop
      - name: pretty
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: The requested Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '404':
          description: No card with that ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cards/{code}/{number}:
    get:
      tags:
      - Cards
      summary: Get a Card by Set Code and Collector Number
      description: Returns a single Card with the given set code and collector number.
      operationId: getCardBySetAndNumber
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
      - name: number
        in: path
        required: true
        schema:
          type: string
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - text
          - image
          default: json
      responses:
        '200':
          description: The requested Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /cards/{code}/{number}/{lang}:
    get:
      tags:
      - Cards
      summary: Get a Localized Card by Set, Number, and Language
      description: Returns a single Card with the given set code, collector number, and language code.
      operationId: getLocalizedCard
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
      - name: number
        in: path
        required: true
        schema:
          type: string
      - name: lang
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The localized Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /cards/multiverse/{id}:
    get:
      tags:
      - Cards
      summary: Get a Card by Multiverse ID
      description: Returns the Card with the given Gatherer multiverse ID.
      operationId: getCardByMultiverseId
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The requested Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /cards/mtgo/{id}:
    get:
      tags:
      - Cards
      summary: Get a Card by MTGO ID
      description: Returns the Card with the given Magic Online catalog ID.
      operationId: getCardByMtgoId
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The requested Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /cards/arena/{id}:
    get:
      tags:
      - Cards
      summary: Get a Card by Arena ID
      description: Returns the Card with the given Magic Arena ID.
      operationId: getCardByArenaId
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The requested Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /cards/tcgplayer/{id}:
    get:
      tags:
      - Cards
      summary: Get a Card by TCGplayer ID
      description: Returns the Card with the given TCGplayer product ID.
      operationId: getCardByTcgplayerId
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The requested Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /cards/cardmarket/{id}:
    get:
      tags:
      - Cards
      summary: Get a Card by Cardmarket ID
      description: Returns the Card with the given Cardmarket idProduct.
      operationId: getCardByCardmarketId
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The requested Card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
components:
  schemas:
    CardFace:
      type: object
      description: One face of a multi-faced Magic card.
      properties:
        object:
          type: string
          enum:
          - card_face
        name:
          type: string
        mana_cost:
          type: string
        type_line:
          type: string
        oracle_text:
          type: string
        colors:
          type: array
          items:
            type: string
        power:
          type: string
        toughness:
          type: string
        loyalty:
          type: string
        defense:
          type: string
        flavor_text:
          type: string
        artist:
          type: string
        artist_id:
          type: string
          format: uuid
        illustration_id:
          type: string
          format: uuid
        image_uris:
          $ref: '#/components/schemas/ImageUris'
        watermark:
          type: string
    ImageUris:
      type: object
      description: URIs for card image renderings at multiple sizes.
      properties:
        small:
          type: string
          format: uri
        normal:
          type: string
          format: uri
        large:
          type: string
          format: uri
        png:
          type: string
          format: uri
        art_crop:
          type: string
          format: uri
        border_crop:
          type: string
          format: uri
    Legalities:
      type: object
      description: Format-by-format legality of a card; values are legal, not_legal, restricted, or banned.
      additionalProperties:
        type: string
        enum:
        - legal
        - not_legal
        - restricted
        - banned
      properties:
        standard:
          type: string
        future:
          type: string
        historic:
          type: string
        timeless:
          type: string
        gladiator:
          type: string
        pioneer:
          type: string
        explorer:
          type: string
        modern:
          type: string
        legacy:
          type: string
        pauper:
          type: string
        vintage:
          type: string
        penny:
          type: string
        commander:
          type: string
        oathbreaker:
          type: string
        standardbrawl:
          type: string
        brawl:
          type: string
        alchemy:
          type: string
        paupercommander:
          type: string
        duel:
          type: string
        oldschool:
          type: string
        premodern:
          type: string
        predh:
          type: string
    List:
      type: object
      description: A generic Scryfall List object wrapping a paginated collection of any type.
      properties:
        object:
          type: string
          enum:
          - list
        total_cards:
          type: integer
        has_more:
          type: boolean
        next_page:
          type: string
          format: uri
        data:
          type: array
          items:
            type: object
    Catalog:
      type: object
      description: A Scryfall Catalog object containing an array of Magic datapoints (names, types, etc.).
      properties:
        object:
          type: string
          enum:
          - catalog
        uri:
          type: string
          format: uri
        total_values:
          type: integer
        data:
          type: array
          items:
            type: string
    Card:
      type: object
      description: 'A Scryfall Card object representing a Magic: The Gathering card printing.'
      properties:
        object:
          type: string
          enum:
          - card
        id:
          type: string
          format: uuid
          description: A unique ID for this card in Scryfall's database.
        oracle_id:
          type: string
          format: uuid
          description: A unique ID for this card's oracle identity.
        multiverse_ids:
          type: array
          items:
            type: integer
        mtgo_id:
          type: integer
        mtgo_foil_id:
          type: integer
        arena_id:
          type: integer
        tcgplayer_id:
          type: integer
        cardmarket_id:
          type: integer
        name:
          type: string
        lang:
          type: string
        released_at:
          type: string
          format: date
        uri:
          type: string
          format: uri
        scryfall_uri:
          type: string
          format: uri
        layout:
          type: string
          description: normal, split, flip, transform, modal_dfc, meld, leveler, class, saga, adventure, etc.
        highres_image:
          type: boolean
        image_status:
          type: string
          enum:
          - missing
          - placeholder
          - lowres
          - highres_scan
        image_uris:
          $ref: '#/components/schemas/ImageUris'
        mana_cost:
          type: string
        cmc:
          type: number
          format: float
        type_line:
          type: string
        oracle_text:
          type: string
        colors:
          type: array
          items:
            type: string
            enum:
            - W
            - U
            - B
            - R
            - G
        color_identity:
          type: array
          items:
            type: string
            enum:
            - W
            - U
            - B
            - R
            - G
        keywords:
          type: array
          items:
            type: string
        legalities:
          $ref: '#/components/schemas/Legalities'
        games:
          type: array
          items:
            type: string
            enum:
            - paper
            - mtgo
            - arena
        reserved:
          type: boolean
        foil:
          type: boolean
        nonfoil:
          type: boolean
        finishes:
          type: array
          items:
            type: string
            enum:
            - foil
            - nonfoil
            - etched
        oversized:
          type: boolean
        promo:
          type: boolean
        reprint:
          type: boolean
        variation:
          type: boolean
        set_id:
          type: string
          format: uuid
        set:
          type: string
        set_name:
          type: string
        set_type:
          type: string
        set_uri:
          type: string
          format: uri
        set_search_uri:
          type: string
          format: uri
        scryfall_set_uri:
          type: string
          format: uri
        rulings_uri:
          type: string
          format: uri
        prints_search_uri:
          type: string
          format: uri
        collector_number:
          type: string
        digital:
          type: boolean
        rarity:
          type: string
          enum:
          - common
          - uncommon
          - rare
          - special
          - mythic
          - bonus
        flavor_text:
          type: string
        card_back_id:
          type: string
          format: uuid
        artist:
          type: string
        artist_ids:
          type: array
          items:
            type: string
            format: uuid
        illustration_id:
          type: string
          format: uuid
        border_color:
          type: string
        frame:
          type: string
        frame_effects:
          type: array
          items:
            type: string
        security_stamp:
          type: string
        full_art:
          type: boolean
        textless:
          type: boolean
        booster:
          type: boolean
        story_spotlight:
          type: boolean
        edhrec_rank:
          type: integer
        penny_rank:
          type: integer
        prices:
          $ref: '#/components/schemas/Prices'
        related_uris:
          type: object
          additionalProperties:
            type: string
            format: uri
        purchase_uris:
          type: object
          additionalProperties:
            type: string
            format: uri
        all_parts:
          type: array
          items:
            $ref: '#/components/schemas/RelatedCard'
        card_faces:
          type: array
          items:
            $ref: '#/components/schemas/CardFace'
        power:
          type: string
        toughness:
          type: string
        loyalty:
          type: string
        defense:
          type: string
        produced_mana:
          type: array
          items:
            type: string
        watermark:
          type: string
    CardList:
      allOf:
      - $ref: '#/components/schemas/List'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/Card'
          not_found:
            type: array
            items:
              type: object
    Prices:
      type: object
      description: Up-to-date market prices for this printing in several currencies and finishes.
      properties:
        usd:
          type: string
        usd_foil:
          type: string
        usd_etched:
          type: string
        eur:
          type: string
        eur_foil:
          type: string
        tix:
          type: string
    Error:
      type: object
      description: A Scryfall Error response object returned for any non-2xx status.
      properties:
        object:
          type: string
          enum:
          - error
        status:
          type: integer
        code:
          type: string
        details:
          type: string
        type:
          type: string
        warnings:
          type: array
          items:
            type: string
    RelatedCard:
      type: object
      description: A reference to a card related to this one (e.g., meld, token, combo).
      properties:
        object:
          type: string
          enum:
          - related_card
        id:
          type: string
          format: uuid
        component:
          type: string
          enum:
          - token
          - meld_part
          - meld_result
          - combo_piece
        name:
          type: string
        type_line:
          type: string
        uri:
          type: string
          format: uri