Card Hunter API

This is the public web API for the The Knights of Unity game, Card Hunter. By using this API, you agree to abide by the Terms of Use.

All resources below are provided with relative paths starting at this page. All resources are read-only, and should be requested using http GET. All data will be returned in JSON format.

Be Careful

Per the Terms of Use, we do not permit more than 600 http requests per hour. If you exceed these limits, your access to the service may be restricted.

If you see return code 429 (Too Many Requests), it's a safe bet that you have overrun your limits. In the event that this happens, check your headers for X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. X-RateLimit-Reset is a timestamp indicating when your request count will refresh to its maximum.

If you hit the limits frequently, it could result in a permanent block.

If you feel that you have a legitimate use for this API that must exceed these limits, please contact us at info@cardhunter.com or support@cardhunter.com to discuss your specific use case.

Pagination

To receive paginated data from root collection resources, you need only use the URL fragments provided in the meta field from the last page you requested. If a URL fragment is null, you are at one end of the list, and there is no further you can go in that direction, so you may wish to disable the respective buttons.

If you have not queried any pages yet, you can request the first page of records, using /[resource]?count=[count], where [resource] is the resource, and [count] is the number of records you would like to fetch per page. The record count limit is 100, and you will never receive more than that, no matter what you ask for. If you omit count, you will receive 10 items.

Date/Time Values

All date/time values are provided in ISO-8601 format. If you would like to use a date/time as a filter on a resource that supports it, you will need to follow the same format, and don't forget to encodeURIComponent() it!

Names

The player name returned for AI opponents is "[AI]". The player name returned for opponents who aren't listed in the name index (or if there is an internal error) is "[Unknown]". Names are returned as they were stored in our system, but like other text, you will need to use encodeURIComponent(), if you wish to put them in a URL.

Players

/players

The /players resource is for querying sets of players. They are generally returned in alphabetical order.

Output

Example:

    {
        "meta": {
            "first": "/players?count=10&page=first",
            "last": "/players?count=10&page=last",
            "prev": null,
            "next": "/players?count=10&page=next&demarc=Axelrod"
        },
        "players": [
            {
                "name": "Amy",
                "rating": 0,
                "steam_id": 12345,
                "kongregate_id": null
            },
            {
                "name": "Ancel",
                "rating": 120,
                "steam_id": null,
                "kongregate_id": 54321
            },
            {
                "name": "Annie",
                "rating": 1000,
                "steam_id": null,
                "kongregate_id": null
            },
            {
                "name": "Anson",
                "rating": 820,
                "steam_id": null,
                "kongregate_id": null
            },
            {
                "name": "Anton",
                "rating": 312,
                "steam_id": null,
                "kongregate_id": null
            },
            {
                "name": "Anvil",
                "rating": 0,
                "steam_id": null,
                "kongregate_id": null
            },
            {
                "name": "Arclight",
                "rating": 12,
                "steam_id": null,
                "kongregate_id": null
            },
            {
                "name": "Auntie",
                "rating": 729,
                "steam_id": null,
                "kongregate_id": null
            },
            {
                "name": "Avery",
                "rating": 936,
                "steam_id": null,
                "kongregate_id": null
            },
            {
                "name": "Axelrod",
                "rating": 1024,
                "steam_id": null,
                "kongregate_id": null
            }
        ]
    }

Filter by Initial Letter

You can request results filtered by initial letter. To do this, you want to use the format /players?count=[count]&initial=[letter], where [count] is the number of records you would like to fetch per page, and [letter] is the initial letter you would like to filter by. Pagination proceeds as above.

Initial letter should be provided in URL escaped format, such as what would be provided by the output of JavaScript's encodeURIComponent()

Filter by Substring

Provide a string of three or more characters, and we will return the names that contain that substring. The format is /players?count=[count]&substring=[letter]. Pagination proceeds as above.

Substring should be provided in URL escaped format, such as what would be provided by the output of JavaScript's encodeURIComponent()

above_rating

A rating you would like to use as the start of your search.

Example: /players?above_rating=1000

below_rating

A rating you would like to use as the end of your search.

Example: /players?below_rating=1600

/players/[name]

The /players/[name] resource is for fetching a single player's data. Names should be provided in URL escaped format, such as what would be provided by the output of JavaScript's encodeURIComponent().

Output

    {
      "player": {
        "name": "Borgia",
        "rating": "800",
        "steam_id": null,
        "kongregate_id": null,
        "ranked_mp_games": "66",
        "ranked_mp_wins": "27",
        "ranked_ai_games": "0",
        "ranked_ai_wins": "0"
      }
    }

Battles

/battles

/battles is for querying lists of multiplayer battles.

Output

    {
      "meta": {
        "first": "/battles?count=10&page=first",
        "last": "/battles?count=10&page=last",
        "prev": null,
        "next": "/battles?count=10&page=next&demarc=11906"
      },
      "battles": [
        {
          "id": 11915,
          "start": "2013-11-20T03:27:42.000Z",
          "duration": 13671,
          "rounds": 2,
          "scenario": "Trenchfoot Mountain",
          "scenarioHash": "865569e678ea44d2ab1b7fd9d5f98adb",
          "quest": -1,
          "gameType": "CASUAL",
          "player1": "Absalom",
          "player1Score": 0,
          "player1AvgHealth": 80,
          "player2": "Frida",
          "player2Score": 0,
          "player2AvgHealth": 50,
          "winner": 1
        },
        {
          "id": 11914,
          "start": "2013-11-20T02:57:12.000Z",
          "duration": 135,
          "rounds": 3,
          "scenario": "Pigwig's Tavern",
          "quest": -1,
          "gameType": "CASUAL",
          "player1": "Shawarma King",
          "player1Score": 3,
          "player1AvgHealth": 43,
          "player2": "Foghorn",
          "player2Score": 0,
          "player2AvgHealth": 0,
          "winner": 0
        },
        ...
      ]
    }

Supported Filters

type

The game type: RANKED, CASUAL, or LEAGUE.

Example: /battles?type=CASUAL

after

A battle ID that you would like to use as the start of your search.

Example: /battles?after=1106

before

A battle ID that you would like to use as the end of your search.

Example: /battles?before=393922

after_time

A time you would like to use as the start of your search. The supported Date/Time format is discussed earlier in this document.

Example: /battles?after_time=2013-11-20T02%3A57%3A12.000Z

before_time

A time you would like to use as the end of your search. The supported Date/Time format is discussed earlier in this document.

Example: /battles?before_time=2013-11-20T02%3A57%3A12.000Z

scenario

The name of the scenario that the battles of interest took place in.

Example: /battles?scenario=Minotaur's%20Revenge

/battles/[battle_id]

The /battles/[battle_id] resource is for fetching a single battle's data.

Ouptut

Example:

    {
        "id": 122,
        "start": "2013-04-15 01:39:54",
        "duration": 304,
        "rounds": 3,
        "scenario": "Minotaur's Revenge",
        "quest": 0,
        "gameType": "LEAGUE",
        "player1": "Able",
        "player1Score": 3,
        "player1AvgHealth": 33,
        "player2": "Baker",
        "player2Score": 4,        
        "player2AvgHealth": 0,
        "winner": 0                
    }

Characters

/characters

The /characters resource is for fetching sets of characters.

Output

Example:

    {
      "meta": {
        "first": "/characters?count=10&page=first",
        "last": "/characters?count=10&page=last",
        "prev": null,
        "next": "/characters?count=10&page=next&demarc=11912:0:2"
      },
      "characters": [
        {
          "id": "11915:0:0",
          "battleId": 11915,
          "playerIndex": 0,
          "characterIndex": 0,
          "name": "Ecrob",
          "class": "Warrior",
          "race": "Human"
        },
        {
          "id": "11915:0:1",
          "battleId": 11915,
          "playerIndex": 0,
          "characterIndex": 1,
          "name": "Agrulgit",
          "class": "Wizard",
          "race": "Dwarf"
        },
        ...
      ]
    }

Supported Filters

battle_id

Only list characters from a certain battle.

Example: /characters?battle_id=11912

player_index

Only list the characters of a particular character in the battle.

Example: /characters?battle_id=11912&player_index=0

class

Only list characters of a particular class.

Example: /characters?battle_id=11912&class=Wizard

race

Only list characters of a particular race.

Example: /characters?battle_id=11912&race=Elf

characters/[character_id]

The characters/[character_id] is for fetching information about an individual character.

Output

    {
      "character": {
        "id": "11912:0:2",
        "battleId": 11912,
        "playerIndex": 0,
        "characterIndex": 2,
        "name": "Gorblar",
        "class": "Wizard",
        "race": "Elf"
      }
    }

Items

/items

The /items resource is for fetching sets of items that characters had equipped during battles.

Output

    {
      "meta": {
        "first": "/items?count=10&page=first",
        "last": "/items?count=10&page=last",
        "prev": null,
        "next": "/items?count=10&page=next&demarc=11914:0:0:534"
      },
      "items": [
        {
          "id": "11915:0:0:335",
          "battleId": 11915,
          "playerIndex": 0,
          "characterIndex": 0,
          "itemId": 335,
          "count": 1
        },
        {
          "id": "11915:0:0:369",
          "battleId": 11915,
          "playerIndex": 0,
          "characterIndex": 0,
          "itemId": 369,
          "count": 1
        },
        ...
      ]
    }

Supported Filters

battle_id

Only list items from a certain battle.

Example: /items?battle_id=11912

player_index

Only list the items belonging to a particular player.

Example: /items?battle_id=11912&player_index=0

character_index

Only list the items equipped by a particular character.

Example: /items?battle_id=11912&player_index=0&character_index=0

/items/[item_id]

The items/[item_id] is for fetching information about an individual item usage by a particular character in a particular battle.

Output

    {
      "item": {
        "id": "11915:0:0:369",
        "battleId": 11915,
        "playerIndex": 0,
        "characterIndex": 0,
        "itemId": 369,
        "count": 1
      }
    }

Additional Notes

Errors

Errors will be returned with appropriate http statuses, and a message payload in JSON, which will contain an "error" property, with a message, if appropriate.

Example:

{
    "error": "Badly formed URL: Character index missing."
}

Questions / Bugs

If you have any questions or bugs to report, drop by the Card Hunter forums.