Path of Exile Developer Docs

Server Endpoint

https://api.pathofexile.com

Leagues

Required scope: service:leagues

List Leagues

GET /league

Optional Query Parameters:

Returns:

Get League

GET /league/<league>

Optional Query Parameters:

Returns:

Get League Ladder

Required scope: service:leagues:ladder
GET /league/<league>/ladder

Optional Query Parameters:

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

Returns:

Get League Event Ladder

Required scope: service:leagues:ladder
GET /league/<league>/event-ladder

Optional Query Parameters:

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

Returns:

PvP Matches

Required scope: service:pvp_matches

List PvP Matches

GET /pvp-match

Optional Query Parameters:

Returns:

Get PvP Match

GET /pvp-match/<match>

Optional Query Parameters:

Returns:

Get PvP Match Ladder

Required scope: service:pvp_matches:ladder
GET /pvp-match/<match>/ladder

Optional Query Parameters:

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

Returns:

Account Profile

Required scope: account:profile

Get Profile

GET /profile

Returns:

Account Leagues

Required scope: account:leagues

Get Leagues

GET /account/leagues

Returns:

Account Characters

Required scope: account:characters

List Characters

GET /character

Returns:

Get Character

GET /character/<name>

Returns:

Account Stashes

Required scope: account:stashes

List Stashes

GET /stash/<league>

Returns:

Get Stash

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

Returns:

League Accounts

Required scope: account:league_accounts

Get League Account

GET /league-account/<league>

Returns:

Account Item Filters

Required scope: account:item_filter

Get Item Filters

GET /item-filter

Returns:

Get Item Filter

GET /item-filter/<id>

Returns:

Create Item Filter

POST /item-filter

Required Headers:

Optional Query Parameters:

Request Body Parameters (JSON):

Returns:

Update Item Filter

POST /item-filter/<id>

Required Headers:

Optional Query Parameters:

Request Body Parameters (JSON):

Returns:

Public Stashes

Required scope: service:psapi

Get Public Stashes

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

Optional Query Parameters:

Returns:

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

Key Value Type Extra Information
id string the league's name
realm ?string pc, xbox, or sony
description ?string
category ?object
↳ id string the league category, e.g. Affliction
↳ active ?bool always true if present
rules ?array of LeagueRule
registerAt ?string date time (ISO8601)
event ?bool always true if present
url ?string a url link to a Path of Exile forum thread
startAt ?string date time (ISO8601)
endAt ?string date time (ISO8601)
timedEvent ?bool always true if present
scoreEvent ?bool always true if present
delveEvent ?bool always true if present
ancestorEvent ?bool always true if present
leagueEvent ?bool always true if present

object LeagueRule

Key Value Type Extra Information
id string examples: Hardcore, NoParties (SSF)
name string
description ?string

object LadderEntry

Key Value Type Extra Information
rank uint
dead ?bool
retired ?bool
ineligible ?bool
public ?bool
character object
↳ id string a unique 64 digit hexadecimal string
↳ name string
↳ level uint
↳ class string
↳ time ?uint time taken to complete the league objective in seconds
↳ score ?uint count of league objective completions
↳ progress ?object the values of this depend on the league objective
↳ experience ?uint
↳ depth ?object deepest Delve depth completed
  ↳ default ?uint
  ↳ solo ?uint
account ?Account

object EventLadderEntry

Key Value Type Extra Information
rank uint
ineligible ?bool
time ?uint time taken to complete the league objective in seconds
private_league object
↳ name string
↳ url string a url link to a Path of Exile Private League

object Account

Key Value Type Extra Information
name string
realm ?string pc, xbox, or sony
guild ?Guild
challenges ?object
↳ set string the challenge set
↳ completed uint
↳ max uint
twitch ?object
↳ name string
↳ stream ?object
  ↳ name string
  ↳ image string
  ↳ status string

object Guild

Key Value Type Extra Information
id uint
name string
tag string

object PvPMatch

Key Value Type Extra Information
id string the match's name
realm ?string pc, xbox, or sony
startAt ?string date time (ISO8601)
endAt ?string date time (ISO8601)
url ?string a url link to a Path of Exile forum thread
description string
glickoRatings bool
pvp bool always true
style string Blitz, Swiss, or Arena
registerAt ?string date time (ISO8601)
complete ?bool always true if present
upcoming ?bool always true if present
inProgress ?bool always true if present

object PvPLadderTeamEntry

Key Value Type Extra Information
rank uint
rating ?uint only present if the PvP Match uses Glicko ratings
points ?uint
games_played ?uint
cumulative_opponent_points ?uint
last_game_time ?string date time (ISO8601)
members array of PvPLadderTeamMember

object PvPLadderTeamMember

Key Value Type Extra Information
account Account
character object
↳ id string a unique 64 digit hexadecimal string
↳ name string
↳ level uint
↳ class string
↳ league ?string
↳ score ?uint count of league objective completions
public ?bool always true if present

object PublicStashChange

Key Value Type Extra Information
id string a unique 64 digit hexadecimal string
public bool if false then optional properties will be null
accountName ?string
stash ?string the name of the stash
lastCharacterName ?string not included by default. Requires extra permissions
stashType string
league ?string the league's name
items array of Item

object Item

Key Value Type Extra Information
verified bool
w uint
h uint
icon string
support ?bool always true if present
stackSize ?int
maxStackSize ?int
stackSizeText ?string
league ?string
id ?string a unique 64 digit hexadecimal string
influences ?object
elder ?bool always true if present
shaper ?bool always true if present
searing ?bool always true if present
tangled ?bool always true if present
abyssJewel ?bool always true if present
delve ?bool always true if present
fractured ?bool always true if present
synthesised ?bool always true if present
sockets ?array of ItemSocket
socketedItems ?array of Item
name string
typeLine string
baseType string
rarity ?string Normal, Magic, Rare, or Unique
identified bool
itemLevel ?int
ilvl int deprecated
note ?string user-generated text
forum_note ?string user-generated text
lockedToCharacter ?bool always true if present
lockedToAccount ?bool always true if present
duplicated ?bool always true if present
split ?bool always true if present
corrupted ?bool always true if present
unmodifiable ?bool always true if present
cisRaceReward ?bool always true if present
seaRaceReward ?bool always true if present
thRaceReward ?bool always true if present
properties ?array of ItemProperty
notableProperties ?array of ItemProperty
requirements ?array of ItemProperty
additionalProperties ?array of ItemProperty
nextLevelRequirements ?array of ItemProperty
talismanTier ?int
rewards ?array of object
↳ label string
↳ rewards dictionary of int the key is a string representing the type of reward. The value is the amount
secDescrText ?string
utilityMods ?array of string
logbookMods ?array of object
↳ name string area name
↳ faction object
  ↳ id string Faction1, Faction2, Faction3, or Faction4
  ↳ name string
↳ mods array of string
enchantMods ?array of string
scourgeMods ?array of string
implicitMods ?array of string
ultimatumMods ?array of object
↳ type string text used to display ultimatum icons
↳ tier uint
explicitMods ?array of string
craftedMods ?array of string
fracturedMods ?array of string
crucibleMods ?array of string only allocated mods are included
cosmeticMods ?array of string
veiledMods ?array of string random video identifier
veiled ?bool always true if present
descrText ?string
flavourText ?array of string
flavourTextParsed ?array of string or object
flavourTextNote ?string user-generated text
prophecyText ?string
isRelic ?bool always true if present
foilVariation ?int
replica ?bool always true if present
foreseeing ?bool always true if present
incubatedItem ?object
↳ name string
↳ level uint monster level required to progress
↳ progress uint
↳ total uint
scourged ?object
↳ tier uint 1-3 for items, 1-10 for maps
↳ level ?uint monster level required to progress
↳ progress ?uint
↳ total ?uint
crucible ?object
↳ layout string URL to an image of the tree layout
↳ nodes dictionary of CrucibleNode the key is the string value of the node index
ruthless ?bool always true if present
frameType ?uint as FrameType
artFilename ?string
hybrid ?object
↳ isVaalGem ?bool
↳ baseTypeName string
↳ properties ?array of ItemProperty
↳ explicitMods ?array of string
↳ secDescrText ?string
extended ?object only present in the Public Stash API
↳ category ?string
↳ subcategories ?array of string
↳ prefixes ?uint
↳ suffixes ?uint
x ?uint
y ?uint
inventoryId ?string
socket ?uint
colour ?string S, D, I, or G

enum FrameType

Referenced by Item→frameType.

Value Information
0 Normal frame
1 Magic frame
2 Rare frame
3 Unique frame
4 Gem frame
5 Currency frame
6 Divination Card frame
7 Quest frame
8 Prophecy frame (legacy)
9 Foil frame
10 Supporter Foil frame
11 Necropolis frame

object ItemSocket

Key Value Type Extra Information
group uint
attr ?string S, D, I, G, A, or DV
sColour ?string R, G, B, W, A, or DV

object ItemProperty

Key Value Type Extra Information
name string
values array of array
↳ 0 string
↳ 1 uint value type
displayMode ?uint as DisplayMode
progress ?double rounded to 2 decimal places
type ?uint
suffix ?string

enum DisplayMode

Referenced by ItemProperty→displayMode.

Value Information
0 Name should be followed by values
1 Values should be followed by name
2 Progress bar
3 Values should be inserted into the string by index
4 Separator

object Character

Key Value Type Extra Information
id string a unique 64 digit hexadecimal string
name string
realm string pc, xbox, or sony
class string
league ?string
level uint
experience uint
ruthless ?bool always true if present
expired ?bool always true if present
deleted ?bool always true if present
current ?bool always true if present
equipment ?array of Item
inventory ?array of Item
rucksack ?array of Item items stored in the Primalist's Rucksack
jewels ?array of Item
passives ?object
↳ hashes array of uint
↳ hashes_ex array of uint
↳ mastery_effects dictionary of int the key is the string value of the mastery node skill hash and the value is the selected effect hash
↳ skill_overrides dictionary of PassiveNode the key is the string value of the node identifier being replaced
↳ bandit_choice ?string one of Kraityn, Alira, Oak, or Eramir
↳ pantheon_major ?string one of TheBrineKing, Arakaali, Solaris, or Lunaris
↳ pantheon_minor ?string one of Abberath, Gruthkul, Yugul, Shakari, Tukohama, Ralakesh, Garukhan, or Ryslatha
↳ jewel_data dictionary of ItemJewelData the key is the string value of the x property of an item from the jewels array in this request
↳ alternate_ascendancy ?string Warden, Warlock, or Primalist
metadata ?object
↳ version ?string game version for the character's realm

object ItemJewelData

Key Value Type Extra Information
type string
radius ?uint
radiusMin ?uint
radiusVisual ?string
subgraph ?object only present on cluster jewels
↳ groups dictionary of PassiveGroup the key is the string value of the group id
↳ nodes dictionary of PassiveNode the key is the string value of the node identifier

object StashTab

Key Value Type Extra Information
id string a 10 digit hexadecimal string
parent ?string a 10 digit hexadecimal string
name string
type string
index ?uint
metadata object
↳ public ?bool always true if present
↳ folder ?bool always true if present
↳ colour ?string 6 digit hex colour
children ?array of StashTab
items ?array of Item

object LeagueAccount

Key Value Type Extra Information
atlas_passives ?object deprecated
↳ hashes array of uint
atlas_passive_trees array of object
↳ name string
↳ hashes array of uint

object ItemFilter

Key Value Type Extra Information
id string
filter_name string
realm string
description string
version string
type string either Normal or Ruthless
public ?bool always true if present
filter ?string not present when listing all filters
validation ?object not present when listing all filters
↳ valid bool
↳ version ?string game version
↳ validated ?string date time (ISO8601)

object PassiveGroup

Key Value Type Extra Information
x float
y float
orbits array of uint
isProxy ?bool always true if present
proxy ?string identifier of the placeholder node
nodes array of string the node identifiers associated with this group

object PassiveNode

Key Value Type Extra Information
skill ?uint skill hash
name ?string
icon ?string
isKeystone ?bool always true if present
isNotable ?bool always true if present
isMastery ?bool always true if present
inactiveIcon ?string inactive mastery image
activeIcon ?string active mastery image
activeEffectImage ?string active mastery or tattoo background image
masteryEffects ?array of object
↳ effect uint effect hash
↳ stats array of string stat descriptions
↳ reminderText ?array of string
isBlighted ?bool always true if present
isTattoo ?bool always true if present
isProxy ?bool always true if present
isJewelSocket ?bool always true if present
expansionJewel ?object cluster jewel information
↳ size ?uint
↳ index ?uint
↳ proxy ?uint the proxy node identifier
↳ parent ?uint the parent node identifier
recipe ?array of string components required for Blight crafting this node.
each string is one of ClearOil, SepiaOil, AmberOil, VerdantOil,
TealOil, AzureOil, IndigoOil, VioletOil, CrimsonOil,
BlackOil, OpalescentOil, SilverOil, or GoldenOil
grantedStrength ?uint sum of stats on this node that grant strength
grantedDexterity ?uint sum of stats on this node that grant dexterity
grantedIntelligence ?uint sum of stats on this node that grant intelligence
ascendancyName ?string
isAscendancyStart ?bool always true if present
isMultipleChoice ?bool always true if present
isMultipleChoiceOption ?bool always true if present
grantedPassivePoints ?uint
stats ?array of string stat descriptions
reminderText ?array of string
flavourText ?array of string
classStartIndex ?uint
group ?string the key value to look up in the groups table
orbit ?uint the orbit this node occupies within it's group
orbitIndex ?uint the index of this node in the group's orbit
out array of string node identifiers of nodes this one connects to
in array of string node identifiers of nodes connected to this one

object CrucibleNode

Referenced by Item→crucible.

Key Value Type Extra Information
skill ?uint mod hash
tier ?uint mod tier
icon ?string
allocated ?bool always true if present
isNotable ?bool always true if present
isReward ?bool always true if present
stats ?array of string stat descriptions
reminderText ?array of string
orbit ?uint the column this node occupies
orbitIndex ?uint the node's position within the column
out array of string node identifiers of nodes this one connects to
in array of string node identifiers of nodes connected to this one

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:

Value Bits Ascendancy Wildwood Ascendancy
0 00 00 00 00
1 00 00 00 01 First Ascendancy for the class
2 00 00 00 10 Second Ascendancy for the class
3 00 00 00 11 Third Ascendancy for the class
4 00 00 01 00 Warden
5 00 00 01 01 First Ascendancy for the class Warden
6 00 00 01 10 Second Ascendancy for the class Warden
7 00 00 01 11 Third Ascendancy for the class Warden
8 00 00 10 00 Warlock
9 00 00 10 01 First Ascendancy for the class Warlock
10 00 00 10 10 Second Ascendancy for the class Warlock
11 00 00 10 11 Third Ascendancy for the class Warlock
12 00 00 11 00 Primalist
13 00 00 11 01 First Ascendancy for the class Primalist
14 00 00 11 10 Second Ascendancy for the class Primalist
15 00 00 11 11 Third Ascendancy for the class Primalist
// (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
This is not a true version bump, as all existing links are backwards-compatible.

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

uint32 version (always 6)
uint8 class
uint8 ascendancy
uint8 count of node skill hashes (n)
uint16[n] hashes[n]
uint8 count of extended (cluster jewel) node skill hashes (m)
uint16[m] extended hashes[m]
uint8 count of mastery effect pairs (o)
uint32[o] mastery effect pairs[o]

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.

uint32 version (always 5)
uint8 class
uint8 ascendancy
uint8 count of hashes (n)
uint16[n] hashes[n]
uint8 count of extended hashes (m)
uint16[m] extended hashes[m]

Version 4

uint32 version (always 4)
uint8 class
uint8 ascendancy
uint8 fullscreen (0 or 1)
uint16[] hashes[]