Battle.net Hearthstone Game Data API — Cards

naftiko: 1.0.0-alpha2
info:
  label: Battle.net Hearthstone Game Data API — Cards
  description: 'Battle.net Hearthstone Game Data API — Cards. 2 operations. Lead operation: Battle.net Search Hearthstone
    Cards. Self-contained Naftiko capability covering one Battle Net business surface.'
  tags:
  - Battle Net
  - Cards
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    BATTLE_NET_API_KEY: BATTLE_NET_API_KEY
capability:
  consumes:
  - type: http
    namespace: hearthstone-game-data-cards
    baseUri: https://us.api.blizzard.com
    description: Battle.net Hearthstone Game Data API — Cards business capability. Self-contained, no shared references.
    resources:
    - name: hearthstone-cards
      path: /hearthstone/cards
      operations:
      - name: searchcards
        method: GET
        description: Battle.net Search Hearthstone Cards
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: set
          in: query
          type: string
          description: The slug of the set the card belongs to. If you do not supply a value, cards from all sets will be
            returned.
        - name: class
          in: query
          type: string
          description: The slug of the card's class.
        - name: manaCost
          in: query
          type: integer
          description: The mana cost required to play the card. You can include multiple values in a comma-separated list
            of numeric values.
        - name: attack
          in: query
          type: integer
          description: The attack power of the minion or weapon. You can include multiple values in a comma-separated list
            of numeric values.
        - name: health
          in: query
          type: integer
          description: The health of the minion. You can include multiple values in a comma-separated list of numeric values.
        - name: collectible
          in: query
          type: string
          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 '
        - name: rarity
          in: query
          type: string
          description: The rarity of a card. This value must match the rarity slugs found in metadata.
        - name: type
          in: query
          type: string
          description: The type of card (minion, spell, weapon, hero). This value must match the type slugs found in metadata.
        - name: minionType
          in: query
          type: string
          description: The type of minion card (murloc, dragon, beast, etc). This value must match the minion type slugs found
            in metadata.
        - name: keyword
          in: query
          type: string
          description: A required keyword on the card (battlecry, deathrattle, taunt, etc). This value must match the keyword
            slugs found in metadata.
        - name: textFilter
          in: query
          type: string
          description: A text string used to filter cards. You must include a locale along with the textFilter parameter.
        - name: gameMode
          in: query
          type: string
          description: A recognized game mode (constructed or battlegrounds).
        - name: page
          in: query
          type: integer
          description: A page number.
        - name: pageSize
          in: query
          type: integer
          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.
        - name: sort
          in: query
          type: string
          description: The field used to sort the results. Valid values include manaCost, attack, health, and name.
        - name: order
          in: query
          type: string
          description: The order in which to sort the results. Valid values are asc or desc.
        - name: locale
          in: query
          type: string
          description: The locale to reflect in localized data.
    - name: hearthstone-cards-idOrSlug
      path: /hearthstone/cards/{idOrSlug}
      operations:
      - name: getcard
        method: GET
        description: Battle.net Get Hearthstone Card
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: idOrSlug
          in: path
          type: string
          description: The ID or slug of the card to retrieve.
          required: true
        - name: gameMode
          in: query
          type: string
          description: A recognized game mode (constructed or battlegrounds).
        - name: locale
          in: query
          type: string
          description: The locale to reflect in localized data.
    authentication:
      type: bearer
      token: '{{env.BATTLE_NET_API_KEY}}'
  exposes:
  - type: rest
    namespace: hearthstone-game-data-cards-rest
    port: 8080
    description: REST adapter for Battle.net Hearthstone Game Data API — Cards. One Spectral-compliant resource per consumed
      operation, prefixed with /v1.
    resources:
    - path: /v1/hearthstone/cards
      name: hearthstone-cards
      description: REST surface for hearthstone-cards.
      operations:
      - method: GET
        name: searchcards
        description: Battle.net Search Hearthstone Cards
        call: hearthstone-game-data-cards.searchcards
        with:
          set: rest.set
          class: rest.class
          manaCost: rest.manaCost
          attack: rest.attack
          health: rest.health
          collectible: rest.collectible
          rarity: rest.rarity
          type: rest.type
          minionType: rest.minionType
          keyword: rest.keyword
          textFilter: rest.textFilter
          gameMode: rest.gameMode
          page: rest.page
          pageSize: rest.pageSize
          sort: rest.sort
          order: rest.order
          locale: rest.locale
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/hearthstone/cards/{idorslug}
      name: hearthstone-cards-idorslug
      description: REST surface for hearthstone-cards-idOrSlug.
      operations:
      - method: GET
        name: getcard
        description: Battle.net Get Hearthstone Card
        call: hearthstone-game-data-cards.getcard
        with:
          idOrSlug: rest.idOrSlug
          gameMode: rest.gameMode
          locale: rest.locale
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: hearthstone-game-data-cards-mcp
    port: 9090
    transport: http
    description: MCP adapter for Battle.net Hearthstone Game Data API — Cards. One tool per consumed operation, routed inline
      through this capability's consumes block.
    tools:
    - name: battle-net-search-hearthstone-cards
      description: Battle.net Search Hearthstone Cards
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: hearthstone-game-data-cards.searchcards
      with:
        set: tools.set
        class: tools.class
        manaCost: tools.manaCost
        attack: tools.attack
        health: tools.health
        collectible: tools.collectible
        rarity: tools.rarity
        type: tools.type
        minionType: tools.minionType
        keyword: tools.keyword
        textFilter: tools.textFilter
        gameMode: tools.gameMode
        page: tools.page
        pageSize: tools.pageSize
        sort: tools.sort
        order: tools.order
        locale: tools.locale
      outputParameters:
      - type: object
        mapping: $.
    - name: battle-net-get-hearthstone-card
      description: Battle.net Get Hearthstone Card
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: hearthstone-game-data-cards.getcard
      with:
        idOrSlug: tools.idOrSlug
        gameMode: tools.gameMode
        locale: tools.locale
      outputParameters:
      - type: object
        mapping: $.