openapi: 3.0.3
info:
  title: Battle.net Hearthstone Game Data API
  description: >-
    The Hearthstone Game Data API provides access to Hearthstone card data, card back
    collections, deck building, and metadata. Authenticate with OAuth 2.0 client
    credentials flow to obtain an access token for use in all requests.
  version: '1.0'
  contact:
    name: Blizzard Developer Relations
    url: https://community.developer.battle.net/
  termsOfService: https://www.blizzard.com/en-us/legal/a2989b50-54f6-43f3-b55c-fa78e0ca3b38/blizzard-developer-api-terms-of-use
  x-generated-from: documentation
servers:
  - url: https://us.api.blizzard.com
    description: US Region
  - url: https://eu.api.blizzard.com
    description: EU Region
  - url: https://apac.api.blizzard.com
    description: APAC Region
security:
  - oauth2: []
tags:
  - name: Cards
    description: Hearthstone card search and lookup
  - name: Card Backs
    description: Hearthstone card back collections
  - name: Decks
    description: Hearthstone deck lookup
  - name: Metadata
    description: Hearthstone metadata including sets, classes, types, and keywords
paths:
  /hearthstone/cards:
    get:
      operationId: searchCards
      summary: Battle.net Search Hearthstone Cards
      description: >-
        Returns an up-to-date list of all cards matching the search criteria.
        Input 1 or more search parameters to retrieve a list of cards.
      tags:
        - Cards
      parameters:
        - name: set
          in: query
          description: The slug of the set the card belongs to. If you do not supply a value, cards from all sets will be returned.
          schema:
            type: string
          example: standard
        - name: class
          in: query
          description: The slug of the card's class.
          schema:
            type: string
          example: mage
        - name: manaCost
          in: query
          description: The mana cost required to play the card. You can include multiple values in a comma-separated list of numeric values.
          schema:
            type: integer
          example: 7
        - name: attack
          in: query
          description: The attack power of the minion or weapon. You can include multiple values in a comma-separated list of numeric values.
          schema:
            type: integer
          example: 5
        - name: health
          in: query
          description: The health of the minion. You can include multiple values in a comma-separated list of numeric values.
          schema:
            type: integer
          example: 5
        - name: collectible
          in: query
          description: Whether a card is collectible. A value of 1 indicates that collectible cards are returned; 0 indicates uncollectible cards. To return all cards, use a value of 0,1.
          schema:
            type: string
          example: '1'
        - name: rarity
          in: query
          description: The rarity of a card. This value must match the rarity slugs found in metadata.
          schema:
            type: string
          example: legendary
        - name: type
          in: query
          description: The type of card (minion, spell, weapon, hero). This value must match the type slugs found in metadata.
          schema:
            type: string
          example: minion
        - name: minionType
          in: query
          description: The type of minion card (murloc, dragon, beast, etc). This value must match the minion type slugs found in metadata.
          schema:
            type: string
          example: dragon
        - name: keyword
          in: query
          description: A required keyword on the card (battlecry, deathrattle, taunt, etc). This value must match the keyword slugs found in metadata.
          schema:
            type: string
          example: battlecry
        - name: textFilter
          in: query
          description: A text string used to filter cards. You must include a locale along with the textFilter parameter.
          schema:
            type: string
          example: Fireball
        - name: gameMode
          in: query
          description: A recognized game mode (constructed or battlegrounds).
          schema:
            type: string
            enum: [constructed, battlegrounds, arena, duels, twist]
          example: constructed
        - name: page
          in: query
          description: A page number.
          schema:
            type: integer
            default: 1
          example: 1
        - name: pageSize
          in: query
          description: The number of results per page. Maximum value is 500; if pageSize is greater than 500 or not specified, it will be set to the maximum allowed value.
          schema:
            type: integer
            maximum: 500
          example: 20
        - name: sort
          in: query
          description: The field used to sort the results. Valid values include manaCost, attack, health, and name.
          schema:
            type: string
            enum: [manaCost, attack, health, name, dateAdded, groupByClass]
          example: manaCost
        - name: order
          in: query
          description: The order in which to sort the results. Valid values are asc or desc.
          schema:
            type: string
            enum: [asc, desc]
          example: asc
        - name: locale
          in: query
          description: The locale to reflect in localized data.
          schema:
            type: string
          example: en_US
      responses:
        '200':
          description: A list of Hearthstone cards matching the search criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardSearchResponse'
              examples:
                SearchCards200Example:
                  summary: Default searchCards 200 response
                  x-microcks-default: true
                  value:
                    cards:
                      - id: 52119
                        collectible: 1
                        slug: "52119-ragnaros-the-firelord"
                        classId: 12
                        multiClassIds: []
                        cardTypeId: 4
                        cardSetId: 3
                        rarityId: 5
                        artistName: "Alex Horley Orlandelli"
                        health: 8
                        attack: 8
                        manaCost: 8
                        name: "Ragnaros the Firelord"
                        text: "Can't attack. At the end of your turn, deal 8 damage to a random enemy."
                        image: "https://d15f34w2p8l1cc.cloudfront.net/hearthstone/bf5f0b3ef6d61b6bec59a7a7a1d95b8f0d9d74d2.png"
                        flavorText: "He was summoned by the Dark Iron dwarves, but he's equal opportunity. He'll destroy everyone."
                        cropImage: "https://d15f34w2p8l1cc.cloudfront.net/hearthstone/cropped/52119.jpg"
                        childIds: []
                    cardCount: 1
                    pageCount: 1
                    page: 1
        '400':
          description: Bad request due to invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /hearthstone/cards/{idOrSlug}:
    get:
      operationId: getCard
      summary: Battle.net Get Hearthstone Card
      description: Returns the card with an ID or slug that matches the one you specify.
      tags:
        - Cards
      parameters:
        - name: idOrSlug
          in: path
          required: true
          description: The ID or slug of the card to retrieve.
          schema:
            type: string
          example: "52119-ragnaros-the-firelord"
        - name: gameMode
          in: query
          description: A recognized game mode (constructed or battlegrounds).
          schema:
            type: string
            enum: [constructed, battlegrounds]
          example: constructed
        - name: locale
          in: query
          description: The locale to reflect in localized data.
          schema:
            type: string
          example: en_US
      responses:
        '200':
          description: A Hearthstone card object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
              examples:
                GetCard200Example:
                  summary: Default getCard 200 response
                  x-microcks-default: true
                  value:
                    id: 52119
                    collectible: 1
                    slug: "52119-ragnaros-the-firelord"
                    classId: 12
                    cardTypeId: 4
                    cardSetId: 3
                    rarityId: 5
                    health: 8
                    attack: 8
                    manaCost: 8
                    name: "Ragnaros the Firelord"
                    text: "Can't attack. At the end of your turn, deal 8 damage to a random enemy."
        '404':
          description: Card not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /hearthstone/cardbacks:
    get:
      operationId: searchCardBacks
      summary: Battle.net Search Hearthstone Card Backs
      description: Returns an up-to-date list of all card backs matching the search criteria.
      tags:
        - Card Backs
      parameters:
        - name: cardBackCategory
          in: query
          description: A category of card back. The category must match a valid category slug.
          schema:
            type: string
          example: fireside
        - name: textFilter
          in: query
          description: A text string used to filter card backs.
          schema:
            type: string
          example: "legend"
        - name: sort
          in: query
          description: The field used to sort the results.
          schema:
            type: string
            enum: [name, dateAdded]
          example: dateAdded
        - name: order
          in: query
          description: The order in which to sort the results.
          schema:
            type: string
            enum: [asc, desc]
          example: desc
        - name: locale
          in: query
          description: The locale to reflect in localized data.
          schema:
            type: string
          example: en_US
      responses:
        '200':
          description: A list of Hearthstone card backs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardBackSearchResponse'
              examples:
                SearchCardBacks200Example:
                  summary: Default searchCardBacks 200 response
                  x-microcks-default: true
                  value:
                    cardBacks:
                      - id: 1
                        sortCategory: 2
                        text: "The standard card back for Hearthstone."
                        name: "Classic"
                        image: "https://d15f34w2p8l1cc.cloudfront.net/hearthstone/card-backs/classic.png"
                        slug: "classic"
                    cardCount: 1
                    pageCount: 1
                    page: 1
        '401':
          description: Unauthorized. Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /hearthstone/cardbacks/{idOrSlug}:
    get:
      operationId: getCardBack
      summary: Battle.net Get Hearthstone Card Back
      description: Returns a specific card back by using a valid ID or slug.
      tags:
        - Card Backs
      parameters:
        - name: idOrSlug
          in: path
          required: true
          description: The ID or slug of the card back.
          schema:
            type: string
          example: "classic"
        - name: locale
          in: query
          description: The locale to reflect in localized data.
          schema:
            type: string
          example: en_US
      responses:
        '200':
          description: A Hearthstone card back object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardBack'
              examples:
                GetCardBack200Example:
                  summary: Default getCardBack 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    sortCategory: 2
                    text: "The standard card back for Hearthstone."
                    name: "Classic"
                    image: "https://d15f34w2p8l1cc.cloudfront.net/hearthstone/card-backs/classic.png"
                    slug: "classic"
        '404':
          description: Card back not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /hearthstone/deck:
    get:
      operationId: getDeck
      summary: Battle.net Get Hearthstone Deck
      description: Finds a deck by its deck code.
      tags:
        - Decks
      parameters:
        - name: code
          in: query
          required: true
          description: A code that identifies a deck. You can copy a deck code by right-clicking on a deck in the Hearthstone client and selecting Copy.
          schema:
            type: string
          example: "AAECAf0EAA8A"
        - name: locale
          in: query
          description: The locale to reflect in localized data.
          schema:
            type: string
          example: en_US
      responses:
        '200':
          description: A Hearthstone deck object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deck'
              examples:
                GetDeck200Example:
                  summary: Default getDeck 200 response
                  x-microcks-default: true
                  value:
                    deckCode: "AAECAf0EAA8A"
                    version: 1
                    format: "standard"
                    class:
                      slug: "mage"
                      id: 3
                      name: "Mage"
                    cards:
                      - id: 52119
                        count: 1
                        slug: "52119-ragnaros-the-firelord"
                        name: "Ragnaros the Firelord"
                    cardCount: 30
        '404':
          description: Deck not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /hearthstone/metadata:
    get:
      operationId: getMetadata
      summary: Battle.net Get Hearthstone Metadata
      description: Returns information about the categorization of cards. Metadata includes the list of sets, set groups, types, rarities, classes, keywords, and minion types.
      tags:
        - Metadata
      parameters:
        - name: locale
          in: query
          description: The locale to reflect in localized data.
          schema:
            type: string
          example: en_US
      responses:
        '200':
          description: Hearthstone metadata object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata'
              examples:
                GetMetadata200Example:
                  summary: Default getMetadata 200 response
                  x-microcks-default: true
                  value:
                    sets:
                      - id: 1
                        name: "Basic"
                        slug: "basic"
                        type: "base"
                        collectibleCount: 133
                        collectibleRevealedCount: 133
                        nonCollectibleCount: 48
                        nonCollectibleRevealedCount: 48
                    classes:
                      - id: 3
                        name: "Mage"
                        slug: "mage"
                    keywords:
                      - id: 1
                        name: "Taunt"
                        slug: "taunt"
                        text: "Enemies must attack this minion."
                    types:
                      - id: 4
                        name: "Minion"
                        slug: "minion"
                    rarities:
                      - id: 5
                        name: "Legendary"
                        slug: "legendary"
                        craftingCost: [400, 1600]
                        dustValue: [400, 1600]
                    minionTypes:
                      - id: 14
                        name: "Dragon"
                        slug: "dragon"
        '401':
          description: Unauthorized. Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /hearthstone/metadata/{type}:
    get:
      operationId: getMetadataType
      summary: Battle.net Get Hearthstone Metadata Type
      description: Returns a specific type of metadata.
      tags:
        - Metadata
      parameters:
        - name: type
          in: path
          required: true
          description: The type of metadata to retrieve (sets, setGroups, arenaIds, arenaSeasons, keywords, races, classes, cardTypes, rarities, minionTypes, spellSchools, mercenaryRoles).
          schema:
            type: string
            enum: [sets, setGroups, arenaIds, arenaSeasons, keywords, races, classes, cardTypes, rarities, minionTypes, spellSchools, mercenaryRoles]
          example: sets
        - name: locale
          in: query
          description: The locale to reflect in localized data.
          schema:
            type: string
          example: en_US
      responses:
        '200':
          description: A list of metadata items of the requested type.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetadataItem'
              examples:
                GetMetadataType200Example:
                  summary: Default getMetadataType 200 response
                  x-microcks-default: true
                  value:
                    - id: 1
                      name: "Basic"
                      slug: "basic"
                      type: "base"
        '404':
          description: Metadata type not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: Battle.net OAuth 2.0 authentication. Use client credentials flow for game data APIs.
      flows:
        clientCredentials:
          tokenUrl: https://oauth.battle.net/token
          scopes: {}

  schemas:
    Card:
      type: object
      title: Card
      description: A Hearthstone card object.
      properties:
        id:
          type: integer
          description: The card's unique ID.
          example: 52119
        collectible:
          type: integer
          description: Indicates if the card is collectible (1) or uncollectible (0).
          example: 1
        slug:
          type: string
          description: A human-readable identifier for the card.
          example: "52119-ragnaros-the-firelord"
        classId:
          type: integer
          description: The class ID of the card.
          example: 12
        multiClassIds:
          type: array
          items:
            type: integer
          description: Class IDs if the card belongs to multiple classes.
        cardTypeId:
          type: integer
          description: The card type ID.
          example: 4
        cardSetId:
          type: integer
          description: The set ID of the card.
          example: 3
        rarityId:
          type: integer
          description: The rarity ID of the card.
          example: 5
        artistName:
          type: string
          description: The name of the card's artist.
          example: "Alex Horley Orlandelli"
        health:
          type: integer
          description: The health of the minion.
          example: 8
        attack:
          type: integer
          description: The attack power of the card.
          example: 8
        manaCost:
          type: integer
          description: The mana cost to play the card.
          example: 8
        name:
          type: string
          description: The name of the card.
          example: "Ragnaros the Firelord"
        text:
          type: string
          description: The card's text.
          example: "Can't attack. At the end of your turn, deal 8 damage to a random enemy."
        image:
          type: string
          format: uri
          description: URL of the card image.
          example: "https://d15f34w2p8l1cc.cloudfront.net/hearthstone/bf5f0b3ef6d61b6bec59a7a7a1d95b8f0d9d74d2.png"
        flavorText:
          type: string
          description: Flavor text for the card.
          example: "He was summoned by the Dark Iron dwarves."
        cropImage:
          type: string
          format: uri
          description: URL of the cropped card image.
          example: "https://d15f34w2p8l1cc.cloudfront.net/hearthstone/cropped/52119.jpg"
        childIds:
          type: array
          items:
            type: integer
          description: IDs of child cards.

    CardSearchResponse:
      type: object
      title: Card Search Response
      description: A paginated list of Hearthstone cards.
      properties:
        cards:
          type: array
          items:
            $ref: '#/components/schemas/Card'
          description: List of matching cards.
        cardCount:
          type: integer
          description: Total number of matching cards.
          example: 100
        pageCount:
          type: integer
          description: Total number of pages.
          example: 5
        page:
          type: integer
          description: Current page number.
          example: 1

    CardBack:
      type: object
      title: Card Back
      description: A Hearthstone card back object.
      properties:
        id:
          type: integer
          description: The unique ID of the card back.
          example: 1
        sortCategory:
          type: integer
          description: The sort category.
          example: 2
        text:
          type: string
          description: Description of the card back.
          example: "The standard card back for Hearthstone."
        name:
          type: string
          description: The name of the card back.
          example: "Classic"
        image:
          type: string
          format: uri
          description: URL of the card back image.
          example: "https://d15f34w2p8l1cc.cloudfront.net/hearthstone/card-backs/classic.png"
        slug:
          type: string
          description: A human-readable identifier for the card back.
          example: "classic"

    CardBackSearchResponse:
      type: object
      title: Card Back Search Response
      description: A paginated list of Hearthstone card backs.
      properties:
        cardBacks:
          type: array
          items:
            $ref: '#/components/schemas/CardBack'
          description: List of matching card backs.
        cardCount:
          type: integer
          description: Total number of matching card backs.
          example: 150
        pageCount:
          type: integer
          description: Total number of pages.
          example: 8
        page:
          type: integer
          description: Current page number.
          example: 1

    DeckCard:
      type: object
      title: Deck Card
      description: A card included in a deck.
      properties:
        id:
          type: integer
          description: The card ID.
          example: 52119
        count:
          type: integer
          description: Number of copies of this card in the deck.
          example: 2
        slug:
          type: string
          description: The card slug.
          example: "52119-ragnaros-the-firelord"
        name:
          type: string
          description: The card name.
          example: "Ragnaros the Firelord"

    DeckClass:
      type: object
      title: Deck Class
      description: The class associated with a deck.
      properties:
        slug:
          type: string
          description: The class slug.
          example: "mage"
        id:
          type: integer
          description: The class ID.
          example: 3
        name:
          type: string
          description: The class name.
          example: "Mage"

    Deck:
      type: object
      title: Deck
      description: A Hearthstone deck.
      properties:
        deckCode:
          type: string
          description: The deck code string.
          example: "AAECAf0EAA8A"
        version:
          type: integer
          description: The deck version.
          example: 1
        format:
          type: string
          description: The deck format (standard, wild, classic).
          example: "standard"
        class:
          $ref: '#/components/schemas/DeckClass'
        cards:
          type: array
          items:
            $ref: '#/components/schemas/DeckCard'
          description: The cards in the deck.
        cardCount:
          type: integer
          description: Total number of cards in the deck.
          example: 30

    MetadataItem:
      type: object
      title: Metadata Item
      description: A generic metadata item.
      properties:
        id:
          type: integer
          description: The unique ID of the metadata item.
          example: 1
        name:
          type: string
          description: The name of the metadata item.
          example: "Basic"
        slug:
          type: string
          description: The slug identifier.
          example: "basic"

    Metadata:
      type: object
      title: Metadata
      description: Hearthstone metadata including sets, classes, keywords, types, and rarities.
      properties:
        sets:
          type: array
          items:
            $ref: '#/components/schemas/MetadataItem'
          description: List of card sets.
        setGroups:
          type: array
          items:
            $ref: '#/components/schemas/MetadataItem'
          description: List of set groups.
        classes:
          type: array
          items:
            $ref: '#/components/schemas/MetadataItem'
          description: List of classes.
        keywords:
          type: array
          items:
            $ref: '#/components/schemas/MetadataItem'
          description: List of keywords.
        types:
          type: array
          items:
            $ref: '#/components/schemas/MetadataItem'
          description: List of card types.
        rarities:
          type: array
          items:
            $ref: '#/components/schemas/MetadataItem'
          description: List of rarities.
        minionTypes:
          type: array
          items:
            $ref: '#/components/schemas/MetadataItem'
          description: List of minion types.

    ErrorResponse:
      type: object
      title: Error Response
      description: An error response from the API.
      properties:
        code:
          type: integer
          description: HTTP error code.
          example: 404
        type:
          type: string
          description: Error type.
          example: "BLZWEBAPI00000404"
        detail:
          type: string
          description: A description of the error.
          example: "Not Found"