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

    card database. It exposes Card, Set, Ruling, Symbology, Catalog, and Bulk Data resources

    used by community tools, deck builders, price trackers, and research projects.


    The API is provided free of charge as part of the Wizards of the Coast Fan Content Policy

    for the primary purpose of creating additional Magic software, performing research, or

    creating community content. It is served only over HTTPS (TLS 1.2+) and requires both a

    descriptive User-Agent and an Accept header on every request. Clients are expected to

    keep request rates under 10 per second (50–100 ms delay between calls), and to use the

    bulk-data downloads for any large-scale ingestion task instead of crawling Card endpoints.

    '
  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: Bulk Data
  description: Large daily exports of the entire Scryfall card database.
paths:
  /bulk-data:
    get:
      tags:
      - Bulk Data
      summary: List Bulk Data Files
      description: Returns a List of all bulk-data exports currently available from Scryfall.
      operationId: listBulkData
      responses:
        '200':
          description: A list of bulk-data files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkDataList'
  /bulk-data/{id}:
    get:
      tags:
      - Bulk Data
      summary: Get a Bulk Data File by ID
      description: Returns a single bulk-data export by its Scryfall ID.
      operationId: getBulkDataById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The requested bulk-data file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkData'
  /bulk-data/{type}:
    get:
      tags:
      - Bulk Data
      summary: Get a Bulk Data File by Type
      description: Returns a single bulk-data export by its type (oracle_cards, unique_artwork, default_cards, all_cards, rulings).
      operationId: getBulkDataByType
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
          enum:
          - oracle_cards
          - unique_artwork
          - default_cards
          - all_cards
          - rulings
      responses:
        '200':
          description: The requested bulk-data file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkData'
components:
  schemas:
    BulkData:
      type: object
      description: A Scryfall Bulk Data object describing one downloadable export of card data.
      properties:
        object:
          type: string
          enum:
          - bulk_data
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - oracle_cards
          - unique_artwork
          - default_cards
          - all_cards
          - rulings
        updated_at:
          type: string
          format: date-time
        uri:
          type: string
          format: uri
        name:
          type: string
        description:
          type: string
        compressed_size:
          type: integer
        download_uri:
          type: string
          format: uri
        content_type:
          type: string
        content_encoding:
          type: string
        size:
          type: integer
    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
    BulkDataList:
      allOf:
      - $ref: '#/components/schemas/List'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/BulkData'