Server Endpoint

Leagues

List Leagues

GET /league

Optional Query Parameters:

• realm= can be pc (default), xbox, or sony
• type= can be one of the following:
  • main retrieves permanent and current challenge leagues (default)
  • event retrieves current event leagues
  • season retrieves leagues in a particular season. Use season= to set the season to query
• limit= restricts the amount of results returned. Maximum is 50 (default)
• offset= can be used with limit above to scroll through the list

Returns:

• A list of all matching leagues up to limit (50 by default).

  Key	Type
  leagues	array of League

Get League

GET /league/<league>

• league must be the name of a league (required)

Optional Query Parameters:

• realm= can be pc (default), xbox, or sony

Returns:

• The league object requested or null if it cannot be found.

  Key	Type
  league	?League

Get League Ladder

GET /league/<league>/ladder

• league must be the name of a league (required)

Optional Query Parameters:

• realm= can be pc (default), xbox, or sony
• sort= can be one of the following:
  • xp sorts the ladder by experience
  • depth sorts the ladder by Delve depth
  • depthsolo sorts the ladder by Delve (Solo) depth
  • ancestor sorts the ladder by Ancestor rank
  • time sorts the ladder by objective finish time
  • score sorts the ladder by objective score
  • class returns characters of a specific class sorted by experience. Use class= to set the class. Options are:
    0. scion
    1. marauder
    2. ranger
    3. witch
    4. duelist
    5. templar
    6. shadow

  The default sort type will either be xp or time depending on the league.

• limit= restricts the amount of results returned. Default is 20. Maximum is 500
• offset= can be used with limit above to scroll through the list

Each ladder only contains the top 15000 entries. Attempting to fetch entries beyond this will return an empty result.

Returns:

• Key	Type	Extra Information
  league	League
  ladder	object
  ↳ total	uint
  ↳ cached_since	?string	date time (ISO8601)
  ↳ entries	array of LadderEntry

Get League Event Ladder

GET /league/<league>/event-ladder

• league must be the name of a league (required)

Optional Query Parameters:

• realm= can be pc (default), xbox, or sony
• limit= restricts the amount of results returned. Default is 20. Maximum is 500
• offset= can be used with limit above to scroll through the list

Each ladder only contains the top 15000 entries. Attempting to fetch entries beyond this will return an empty result.

Returns:

• Key	Type	Extra Information
  league	League
  ladder	object
  ↳ total	uint
  ↳ entries	array of EventLadderEntry

PvP Matches

List PvP Matches

GET /pvp-match

Optional Query Parameters:

• realm= can be pc (default), xbox, or sony
• type= can be one of the following:
  • upcoming retrieves upcoming matches (default)
  • season retrieves matches in a particular season. Use season= to set the season to query
  • league retrieves matches in a particular league. Use league= to set the league to query

Returns:

• Key	Type
  matches	array of PvPMatch

Get PvP Match

GET /pvp-match/<match>

• match must be the name of a match (required)

Optional Query Parameters:

• realm= can be pc (default), xbox, or sony

Returns:

• The PvP match object requested or null if it cannot be found.

  Key	Type
  match	?PvPMatch

Get PvP Match Ladder

GET /pvp-match/<match>/ladder

• match must be the name of a match (required)

Optional Query Parameters:

• realm= can be pc (default), xbox, or sony
• limit= restricts the amount of results returned. Default is 20. Maximum is 200
• offset= can be used with limit above to scroll through the list

Each ladder only contains the top 15000 entries. Attempting to fetch entries beyond this will return an empty result.

Returns:

• Key	Type
  match	PvPMatch
  ladder	object
  ↳ total	uint
  ↳ entries	array of PvPLadderTeamEntry

Account Profile

Get Profile

GET /profile

Returns:

• Key	Type	Extra Information
  uuid	string	UUIDv4 in canonical format
  name	string
  realm	?string	pc, xbox, or sony
  twitch	?object	present if the account is Twitch-linked
  ↳ name	string

Account Leagues

Get Leagues

GET /account/leagues[/<realm>]

• realm can either by xbox or sony. If omitted then the PC realm is assumed (optional)

Returns:

• The current leagues available to the account, including private leagues.

  Key	Type
  leagues	array of League

Account Characters

List Characters

GET /character[/<realm>]

• realm can either by xbox or sony. If omitted then the PC realm is assumed (optional)

Returns:

• A list of all the account's characters.

  Key	Type
  characters	array of Character

Get Character

GET /character[/<realm>]/<name>

• realm can either by xbox or sony. If omitted then the PC realm is assumed (optional)
• name is the name of one of the account's characters (required)

Returns:

• The character requested including their equipment, inventory, and passive skill information.

  Key	Type
  character	?Character

Account Stashes

List Stashes

GET /stash[/<realm>]/<league>

• realm can either by xbox or sony. If omitted then the PC realm is assumed (optional)
• league is the name of a Path of Exile league (required)

Returns:

• A list of all the account's stash tabs in the specified league. This includes sub-tabs and stash tabs in folders.

  Key	Type
  stashes	array of StashTab

Get Stash

GET /stash[/<realm>]/<league>/<stash_id>[/<substash_id>]

• realm can either by xbox or sony. If omitted then the PC realm is assumed (optional)
• league is the name of a Path of Exile league (required)
• stash_id is the public identifier of a stash tab (required)
• substash_id is the public identifier of a sub-tab with stash_id as a parent (optional)

Returns:

• The stash object requested, including any contained items (when applicable). If a substash_id is provided then the inner tab will be wrapped by the parent allowing you to access information of both at the same time.

  Key	Type
  stash	?StashTab

Account Item Filters

Get Item Filters

GET /item-filter

Returns:

• A list of online filters on the account.

  Key	Type
  filters	array of ItemFilter

Get Item Filter

GET /item-filter/<id>

• id is an item filter id (required)

Returns:

• Key	Type
  filter	ItemFilter

Create Item Filter

POST /item-filter

Required Headers:

• Content-Type: application/json

Optional Query Parameters:

• validate= set to true to validate the filter against the current game version

Request Body Parameters (JSON):

• For an explanation of Item Filter syntax please refer to our online guide.

  Key	Type	Extra Information
  filter_name	string
  realm	string	pc, xbox, or sony
  description	?string
  version	?string
  type	?string	either Normal or Ruthless
  public	?bool	defaults to false
  filter	string

Returns:

• Key	Type
  filter	ItemFilter

Update Item Filter

POST /item-filter/<id>

• id is an item filter id (required)

Required Headers:

• Content-Type: application/json

Optional Query Parameters:

• validate= set to true to validate the filter against the current game version

Request Body Parameters (JSON):

• This endpoint allows partial updates. Properties that are not supplied will use the current filter's values.

  Please note: A public filter cannot be made private again.

  Key	Type	Extra Information
  filter_name	?string
  realm	?string	pc, xbox, or sony
  description	?string
  version	?string
  type	?string	either Normal or Ruthless
  public	?bool	must be true if present
  filter	?string

Returns:

The updated filter.

If the HTTP response code is 202 (Accepted) then additional processing is required. In this case an error object with more information will be returned as well.

• Key	Type	Extra Information
  filter	ItemFilter
  error	?Error	an "Accepted" error object

League Accounts

Get League Account

GET /league-account[/<realm>]/<league>

• realm can either by xbox or sony. If omitted then the PC realm is assumed (optional)
• league must be the name of a league (required)

Returns:

• The matching league-specific account information for the account.

  Key	Type
  league_account	LeagueAccount

Guild Stashes

List Guild Stashes

GET /guild[/<realm>]/stash/<league>

• realm can either by xbox or sony. If omitted then the PC realm is assumed (optional)
• league is the name of a Path of Exile league (required)

Returns:

• A list of all the guild's stash tabs that the account has access to in the specified league. This includes sub-tabs and stash tabs in folders.

  Key	Type
  stashes	array of StashTab

Get Guild Stash

GET /guild[/<realm>]/stash/<league>/<stash_id>[/<substash_id>]

• realm can either by xbox or sony. If omitted then the PC realm is assumed (optional)
• league is the name of a Path of Exile league (required)
• stash_id is the public identifier of a guild stash tab (required)
• substash_id is the public identifier of a guild sub-tab with stash_id as a parent (optional)

Returns:

• The stash object requested, including any contained items (when applicable). If a substash_id is provided then the inner tab will be wrapped by the parent allowing you to access information of both at the same time.

  Key	Type
  stash	?StashTab

Public Stashes

Get Public Stashes

GET /public-stash-tabs[/<realm>]

• realm can either by xbox or sony. If omitted then the PC realm is assumed (optional)

Optional Query Parameters:

• id= is a pagination code received from this endpoint

Returns:

• A stream containing all public stashes in all leagues for the given realm. Providing the next_change_id as the id query parameter serves as a way to paginate through current and newly listed stashes.
  You can track stashes as they re-appear in the stream by comparing their PublicStashChange's id property. If a stash has been unlisted all details aside from the id and public parameters will be omitted.

  Key	Type	Extra Information
  next_change_id	string	pagination code
  stashes	array of PublicStashChange

  If the stashes array is empty then you have reached the end of the stream. Polling this endpoint with the same next_change_id will then return new results once they become available

  Please note: There is currently a 5-minute delay on results using this API. You may see more details here.

Type Definitions

The majority of our APIs return JSON content to be consumed by applications. This section details the kind of structures to expect.

Types that begin with a question mark may be null or otherwise not be present.

object League

object LeagueRule

object LadderEntry

object EventLadderEntry

object Account

object Guild

object PvPMatch

object PvPLadderTeamEntry

object PvPLadderTeamMember

object PublicStashChange

object Item

enum FrameType

object ItemSocket

object ItemProperty

enum DisplayMode

object Character

object ItemJewelData

object StashTab

object LeagueAccount

object ItemFilter

object PassiveGroup

object PassiveNode

object CrucibleNode

Extra Definitions

Some data, such as Passive Skill Tree URLs, are stored in a serialised form. This section will attempt to define such structures.

Passive Skill Tree URLs

Passive Tree URLs can be generated and loaded by the official Passive Skill Tree viewer.
The data in the URL is a base64url-encoded (as described in section 5 of RFC4648) binary stream in the formats described below.
Example: https://www.pathofexile.com/passive-skill-tree/3.15.0/AAAABQMADAQHES0fAiycLR9Ms18qg_eOvpLB37Dr5AA=

Atlas Skill Tree

The Atlas Skill Tree introduced in Path of Exile: Siege of the Atlas (3.17.0) follows the same format as the regular passive tree and can also be loaded by the official Atlas Skill Tree viewer.
The class and ascendancy bytes should be set to 0, and the extended and mastery hash lists should be empty.
Example: https://www.pathofexile.com/atlas-skill-tree/ruthless/AAAABgAAAfdPAAA=

Version 6.1

For Path of Exile: Affliction (3.23.0) we have repurposed the ascendancy field to also include the chosen Wildwood Ascendancy. This is encoded by using two currently unused bits of the field, the third and fourth from the right. For ease of understanding, here is a table:

// (in JavaScript)
const ascendancyData = 0x0E; // (unsigned 8-bit) 14
const ascendancy = ascendancyData & 0x3; // 2, the Second Ascendancy of the class
const wildwoodAscendancy = ascendancyData >>> 2; // 3, Primalist Wildwood Ascendancy

Version 6

This version was introduced with Path of Exile: Scourge (3.16.0) in order to handle the new mastery nodes.
The mastery effect pairs uint32 is actually two uint16 numbers: the first is the node skill hash and the second is the chosen effect hash for this node.

// (in JavaScript)
const masteryEffectPair = 0x910ce685; // (unsigned 32-bit) 2433541765 or (signed 32-bit) -1861425531
const nodeHash = masteryEffectPair & 0xffff; // 59013 (unsigned 16-bit) or 0xe685
const effectHash = masteryEffectPair >>> 16; // 37132 (unsigned 16-bit) or 0x910c

Version 5

This version was introduced during Path of Exile: Ritual (3.13.0) in order to support cluster jewels. We currently don't support rendering cluster jewels ourselves but, with this version, provide the character data required to do so.

Version 4