Path of Exile Developer Docs

https://www.pathofexile.com/developer/docs
Admin
Path of Exile Developer Docs provides documentation for the Path of Exile API endpoints, detailing...
Tokens:12,052
Snippets:124
Trust Score:9.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /character

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a list of all the account's characters.

```APIDOC
## GET /character[/<realm>]

### Description
Retrieves a list of all the account's characters.

### Method
GET

### Endpoint
/character[/<realm>]

### Parameters
#### Path Parameters
- **realm** (string) - Optional - Can be 'xbox', 'sony', or 'poe2'. If omitted, PoE1 PC realm is assumed.

### Response
#### Success Response (200)
- **characters** (array of Character) - A list of all the account's characters.
```

--------------------------------

### GET /profile

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves the account profile information for the authenticated user.

```APIDOC
## GET /profile

### Description
Retrieves the account profile information for the authenticated user. Requires the 'account:profile' scope.

### Method
GET

### Endpoint
/profile

### Response
#### Success Response (200)
- **uuid** (string) - UUIDv4 in canonical format
- **name** (string) - Account name
- **locale** (?string) - Locale information
- **twitch** (?object) - Twitch link information (contains name)
```

--------------------------------

### GET /pvp-match/<match>

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves details for a specific PvP match by its name.

```APIDOC
## GET /pvp-match/<match>

### Description
Retrieves the PvP match object for a specific match name. Requires scope: service:pvp_matches.

### Method
GET

### Endpoint
/pvp-match/<match>

### Parameters
#### Path Parameters
- **match** (string) - Required - The name of the match.

#### Query Parameters
- **realm** (string) - Optional - Can be 'pc' (default), 'xbox', or 'sony'.

### Response
#### Success Response (200)
- **match** (PvPMatch) - The requested PvP match object or null if not found.
```

--------------------------------

### GET /league/<league>

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves details for a specific league by its name.

```APIDOC
## GET /league/<league>

### Description
Retrieves the league object for the specified league name.

### Method
GET

### Endpoint
/league/<league>

### Parameters
#### Path Parameters
- **league** (string) - Required - The name of the league.

#### Query Parameters
- **realm** (string) - Optional - Can be pc, xbox, sony, or poe2.

### Response
#### Success Response (200)
- **league** (object) - The requested league object or null.
```

--------------------------------

### Get PvP Match Details

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves details for a specific PvP match by name.

```http
GET /pvp-match/<match>
```

--------------------------------

### GET /character/<name>

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves details for a specific character including equipment, inventory, and passive skill information.

```APIDOC
## GET /character[/<realm>]/<name>

### Description
Retrieves the character requested including their equipment, inventory, and passive skill information.

### Method
GET

### Endpoint
/character[/<realm>]/<name>

### Parameters
#### Path Parameters
- **realm** (string) - Optional - Can be 'xbox', 'sony', or 'poe2'. If omitted, PoE1 PC realm is assumed.
- **name** (string) - Required - The name of one of the account's characters.

### Response
#### Success Response (200)
- **character** (Character) - The character object requested.
```

--------------------------------

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

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves the matching league-specific account information for the authenticated account.

```APIDOC
## GET /league-account[/<realm>]/<league>

### Description
Retrieves the matching league-specific account information for the account.

### Method
GET

### Endpoint
/league-account[/<realm>]/<league>

### Parameters
#### Path Parameters
- **realm** (string) - Optional - Can be 'xbox' or 'sony'. If omitted, the PoE1 PC realm is assumed.
- **league** (string) - Required - The name of the league.

### Response
#### Success Response (200)
- **league_account** (LeagueAccount) - The matching league-specific account information.
```

--------------------------------

### GET /oauth/authorize

Source: https://www.pathofexile.com/developer/docs/authorization

The authorization page used for obtaining user consent.

```APIDOC
## GET /oauth/authorize

### Description
Authorization page for obtaining user consent.

### Method
GET

### Endpoint
/oauth/authorize
```

--------------------------------

### Define Build Configuration JSON

Source: https://www.pathofexile.com/developer/docs/game

A complete example of a build configuration file, demonstrating the use of markup tags within the additional_text fields for passives, skills, and inventory slots.

```json
{
    "name": "Titan Warrior",
    "author": "Grinding Gear Games",
    "ascendancy": "Warrior1",
    "passives": 
    [
        "melee17",
        "melee18",
        "melee25",
        "melee44",
        "melee46",
        "marauder_brute_notable1",
        {
            "id": "strength17",
            "additional_text": "<m>{<red>{Strength +5 is recommended}}"
        },
        {
            "id": "strength16",
            "additional_text": "<m>{<red>{Strength +5 is recommended}}"
        },
        {
            "id": "strength89",
            "additional_text": "<m>{<red>{Strength +5 is recommended}}"
        },
        {
            "id": "attributes65",
            "additional_text": "<m>{<red>{Strength +5 is recommended}}"
        },
        "duration_spells5",
        "duration_spells1",
        "duration_spells6",
        "area_attacks24",
        "area_attacks32",
        "area_attacks25_",
        "melee19",
        {
            "id": "strength19",
            "additional_text": "<m>{<blue>{Intelligence +5 is recommended}}"
        },
        "fire10",
        "fire16",
        "fire38",
        {
            "id": "strength21",
            "additional_text": "<m>{<red>{Strength +5 is recommended}}"
        },
        {
            "id": "strength15",
            "additional_text": "<m>{<red>{Strength +5 is recommended}}"
        },
        {
            "id": "attributes32",
            "additional_text": "<m>{<red>{Strength +5 is recommended}}"
        },
        "warcries19_",
        "warcries20",
        "warcries21",
        "slams4",
        "slams1",
        "slams5",
        "jewel_slot1956",
        {
            "id": "strength68",
            "additional_text": "<m>{<red>{Strength +5 is recommended}}"
        },
        "AscendancyWarrior1Small3",
        "AscendancyWarrior1Notable4"
    ],
    "skills": 
    [
        {
            "id": "Metadata/Items/Gems/SkillGemEarthquake",
            "additional_text": "Intended to be taken <green>{BEFORE} BoneShatter",
            "support_skills":
            [
                "Metadata/Items/Gems/SupportGemFastForward",
                "Metadata/Items/Gems/SupportGemAftershock"
            ]
        },
        {
            "id": "Metadata/Items/Gems/SkillGemBoneshatter",
            "additional_text": "Intended to be taken <red>{AFTER} Earthquake",
            "support_skills":
            [
                {
                    "id": "Metadata/Items/Gems/SupportGemImpactShockwave",
                    "additional_text": "Intended to be taken <green>{BEFORE} Magnified Area I"
                },
                {
                    "id": "Metadata/Items/Gems/SupportGemMagnifiedEffect",
                    "additional_text": "Intended to be taken <red>{AFTER} Impact Shockwave"
                }
            ]
        },
        {
            "id": "Metadata/Items/Gems/SkillGemShockwaveTotem",
            "additional_text": "Intended to be taken <green>{BEFORE} Infernal Cry",
            "support_skills":
            [
                "Metadata/Items/Gems/SupportGemMagnifiedEffect",
                "Metadata/Items/Gems/SupportGemBrutalityTwo"
            ]
        },
        {
            "id": "Metadata/Items/Gems/SkillGemInfernalCry",
            "additional_text": "Intended to be taken <red>{AFTER} Shockwave Totem",
            "support_skills": 
            [
                "Metadata/Items/Gem/SupportGemTireless",
                "Metadata/Items/Gem/SupportGemRagingCry"
            ]
        }
    ],
    "inventory_slots": 
    [
        {
            "inventory_id": "Weapon1",
            "additional_text": "<silver>{Any Two Handed Mace}\n\n<grey>{Stat Priority\n-------------------\n1. Prioritize highest physical dps}"
        },
        {
            "inventory_id": "BodyArmour1",
```

--------------------------------

### GET /oauth/authorize

Source: https://www.pathofexile.com/developer/docs/authorization

Initiates the authorization flow by redirecting the user to the Path of Exile authorization page.

```APIDOC
## GET /oauth/authorize

### Description
Redirects the user to the authorization page to grant the application access to their account based on requested scopes.

### Method
GET

### Endpoint
https://www.pathofexile.com/oauth/authorize

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Your registered application's client id.
- **response_type** (string) - Required - Must be 'code'.
- **scope** (string) - Required - Space-separated list of requested scopes.
- **state** (string) - Required - A code or hash generated to track the request.
- **redirect_uri** (string) - Required - The URL to redirect to after authorization.
- **code_challenge** (string) - Required - The base64url-encoded SHA256 hash of the code_verifier.
- **code_challenge_method** (string) - Required - Must be 'S256'.
```

--------------------------------

### Get League Details

Source: https://www.pathofexile.com/developer/docs/reference

Fetches details for a specific league identified by its name.

```http
GET /league/<league>
```

--------------------------------

### GET /pvp-match/<match>/ladder

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves the ladder rankings for a specific PvP match.

```APIDOC
## GET /pvp-match/<match>/ladder

### Description
Retrieves the ladder entries for a specific PvP match. Requires scope: service:pvp_matches:ladder.

### Method
GET

### Endpoint
/pvp-match/<match>/ladder

### Parameters
#### Path Parameters
- **match** (string) - Required - The name of the match.

#### Query Parameters
- **realm** (string) - Optional - Can be 'pc' (default), 'xbox', or 'sony'.
- **limit** (uint) - Optional - Restricts results (default 20, max 200).
- **offset** (uint) - Optional - Used for pagination.

### Response
#### Success Response (200)
- **match** (PvPMatch) - The match object.
- **ladder** (object) - The ladder data containing 'total' (uint) and 'entries' (array of PvPLadderTeamEntry).
```

--------------------------------

### Get PvP Match Ladder

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves the ladder for a specific PvP match. Requires the service:pvp_matches:ladder scope.

```http
GET /pvp-match/<match>/ladder
```

--------------------------------

### GET /account/leagues

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves the current leagues available to the account, including private leagues.

```APIDOC
## GET /account/leagues[/<realm>]

### Description
Retrieves the current leagues available to the account, including private leagues.

### Method
GET

### Endpoint
/account/leagues[/<realm>]

### Parameters
#### Path Parameters
- **realm** (string) - Optional - Can be 'xbox' or 'sony'. If omitted, PoE1 PC realm is assumed.

### Response
#### Success Response (200)
- **leagues** (array of League) - The current leagues available to the account.
```

--------------------------------

### Get League Account

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves league-specific account information. Requires the account:league_accounts scope.

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

--------------------------------

### GET /pvp-match

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a list of PvP matches based on optional filters like realm and match type.

```APIDOC
## GET /pvp-match

### Description
Retrieves a list of PvP matches. Requires scope: service:pvp_matches.

### Method
GET

### Endpoint
/pvp-match

### Parameters
#### Query Parameters
- **realm** (string) - Optional - Can be 'pc' (default), 'xbox', or 'sony'.
- **type** (string) - Optional - Can be 'upcoming' (default), 'season', or 'league'.
- **season** (string) - Optional - Used when type is 'season'.
- **league** (string) - Optional - Used when type is 'league'.

### Response
#### Success Response (200)
- **matches** (array of PvPMatch) - List of PvP matches.
```

--------------------------------

### GET /item-filter

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a list of online item filters associated with the account.

```APIDOC
## GET /item-filter

### Description
Retrieves a list of online item filters on the account. Requires the 'account:item_filter' scope.

### Method
GET

### Endpoint
/item-filter

### Response
#### Success Response (200)
- **filters** (array) - A list of online filters on the account.
```

--------------------------------

### GET /item-filter/<id>

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a specific item filter by its ID.

```APIDOC
## GET /item-filter/<id>

### Description
Retrieves a specific item filter by its ID.

### Method
GET

### Endpoint
/item-filter/<id>

### Parameters
#### Path Parameters
- **id** (string) - Required - The item filter ID.

### Response
#### Success Response (200)
- **filter** (ItemFilter) - The requested item filter.
```

--------------------------------

### GET /league

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a list of leagues based on optional filters such as realm, type, and pagination limits.

```APIDOC
## GET /league

### Description
Retrieves a list of all matching leagues. Supports filtering by realm, type, and pagination.

### Method
GET

### Endpoint
/league

### Parameters
#### Query Parameters
- **realm** (string) - Optional - Can be pc, xbox, sony, or poe2.
- **type** (string) - Optional - Can be main, event, or season.
- **limit** (integer) - Optional - Restricts results, max 50.
- **offset** (integer) - Optional - Used for pagination.

### Response
#### Success Response (200)
- **leagues** (array) - A list of matching League objects.
```

--------------------------------

### GET https://web.poecdn.com/api/currency-exchange[/<realm>][/<id>]

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves aggregate currency exchange trade history grouped into hourly digests.

```APIDOC
## GET https://web.poecdn.com/api/currency-exchange[/<realm>][/<id>]

### Description
Allows viewing aggregate Currency Exchange trade history across all leagues grouped into hourly digests.

### Method
GET

### Endpoint
https://web.poecdn.com/api/currency-exchange[/<realm>][/<id>]

### Parameters
#### Path Parameters
- **realm** (string) - Optional - Can be 'xbox', 'sony', or 'poe2'. If omitted, PoE1 PC realm is assumed.
- **id** (string) - Optional - Unix timestamp code. If none is provided, the first hour of history is assumed.

### Response
#### Success Response (200)
- **next_change_id** (uint) - Unix timestamp truncated to the hour.
- **markets** (array) - List of market objects containing league, market_id, market_pair, volume_traded, lowest_stock, highest_stock, lowest_ratio, and highest_ratio.
```

--------------------------------

### GET /league/<league>/ladder

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves the ladder rankings for a specific league.

```APIDOC
## GET /league/<league>/ladder

### Description
Retrieves the ladder entries for a specific league, with options for sorting and pagination.

### Method
GET

### Endpoint
/league/<league>/ladder

### Parameters
#### Path Parameters
- **league** (string) - Required - The name of the league.

#### Query Parameters
- **realm** (string) - Optional - Can be pc, xbox, sony, or poe2.
- **sort** (string) - Optional - Sorting criteria (xp, depth, depthsolo, ancestor, time, score, class).
- **limit** (integer) - Optional - Restricts results, max 500.
- **offset** (integer) - Optional - Used for pagination.

### Response
#### Success Response (200)
- **league** (object) - The league object.
- **ladder** (object) - Contains total, cached_since, and entries.
```

--------------------------------

### Get Character Details

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves specific character data including equipment, inventory, and passive skills. Requires the account:characters scope.

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

--------------------------------

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

Source: https://www.pathofexile.com/developer/docs/reference

Lists all guild stash tabs accessible to the account in a specific league.

```APIDOC
## GET /guild[/<realm>]/stash/<league>

### Description
Returns a list of all the guild's stash tabs that the account has access to in the specified league.

### Method
GET

### Endpoint
/guild[/<realm>]/stash/<league>

### Parameters
#### Path Parameters
- **realm** (string) - Optional - Can be 'xbox' or 'sony'. If omitted, the PoE1 PC realm is assumed.
- **league** (string) - Required - The name of the Path of Exile league.

### Response
#### Success Response (200)
- **stashes** (array of StashTab) - A list of all the guild's stash tabs.
```

--------------------------------

### Get League Event Ladder

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves event-specific ladder rankings for PoE1 leagues.

```http
GET /league/<league>/event-ladder
```

--------------------------------

### GET /stash/<league>

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a list of all the account's stash tabs in the specified league.

```APIDOC
## GET /stash[/<realm>]/<league>

### Description
Retrieves a list of all the account's stash tabs in the specified league, including sub-tabs and folders.

### Method
GET

### Endpoint
/stash[/<realm>]/<league>

### Parameters
#### Path Parameters
- **realm** (string) - Optional - Can be 'xbox' or 'sony'. If omitted, PoE1 PC realm is assumed.
- **league** (string) - Required - The name of a Path of Exile league.

### Response
#### Success Response (200)
- **stashes** (array of StashTab) - A list of all the account's stash tabs.
```

--------------------------------

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

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a stream of public stash tabs. Use the id query parameter for pagination.

```APIDOC
## GET /public-stash-tabs[/<realm>]

### Description
Retrieves a stream containing all public stashes in all leagues for the given realm. Use the `id` query parameter to paginate through results.

### Method
GET

### Endpoint
/public-stash-tabs[/<realm>]

### Parameters
#### Path Parameters
- **realm** (string) - Optional - Can be 'xbox' or 'sony'. If omitted, PoE1 PC realm is assumed.

#### Query Parameters
- **id** (string) - Optional - Pagination code received from the endpoint.

### Response
#### Success Response (200)
- **next_change_id** (string) - Pagination code.
- **stashes** (array) - List of PublicStashChange objects.
```

--------------------------------

### Get Exchange Markets Endpoint

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves historical currency exchange market data grouped into hourly digests.

```http
GET https://web.poecdn.com/api/currency-exchange[/<realm>][/<id>]
```

--------------------------------

### GET /league/<league>/event-ladder

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves the event ladder rankings for a specific PoE1 league.

```APIDOC
## GET /league/<league>/event-ladder

### Description
Retrieves the event ladder entries for a specific PoE1 league.

### Method
GET

### Endpoint
/league/<league>/event-ladder

### Parameters
#### Path Parameters
- **league** (string) - Required - The name of the league.

#### Query Parameters
- **realm** (string) - Optional - Can be pc, xbox, or sony.
- **limit** (integer) - Optional - Restricts results, max 500.
- **offset** (integer) - Optional - Used for pagination.

### Response
#### Success Response (200)
- **league** (object) - The league object.
- **ladder** (object) - Contains total and entries.
```

--------------------------------

### Get League Ladder

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves ladder rankings for a specific league, supporting various sorting options and pagination.

```http
GET /league/<league>/ladder
```

--------------------------------

### GET /stash/<league>/<stash_id>

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a specific stash tab object, including contained items.

```APIDOC
## GET /stash[/<realm>]/<league>/<stash_id>[/<substash_id>]

### Description
Retrieves the stash object requested, including any contained items. If a substash_id is provided, the inner tab will be wrapped by the parent.

### Method
GET

### Endpoint
/stash[/<realm>]/<league>/<stash_id>[/<substash_id>]

### Parameters
#### Path Parameters
- **realm** (string) - Optional - Can be 'xbox' or 'sony'. If omitted, PoE1 PC realm is assumed.
- **league** (string) - Required - The name of a Path of Exile league.
- **stash_id** (string) - Required - The public identifier of a stash tab.
- **substash_id** (string) - Optional - The public identifier of a sub-tab.

### Response
#### Success Response (200)
- **stash** (StashTab) - The stash object requested.
```

--------------------------------

### Get Account Leagues

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves current leagues available to the account, including private leagues. Requires the account:leagues scope.

```http
GET /account/leagues[/<realm>]
```

--------------------------------

### Get Public Stashes Endpoint

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a stream of public stash tabs. Use the id query parameter for pagination.

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

--------------------------------

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

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a specific guild stash tab or sub-tab, including contained items.

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

### Description
Returns the stash object requested, including any contained items. If a substash_id is provided, the inner tab is wrapped by the parent.

### Method
GET

### Endpoint
/guild[/<realm>]/stash/<league>/<stash_id>[/<substash_id>]

### Parameters
#### Path Parameters
- **realm** (string) - Optional - Can be 'xbox' or 'sony'. If omitted, the PoE1 PC realm is assumed.
- **league** (string) - Required - The name of the Path of Exile league.
- **stash_id** (string) - Required - The public identifier of a guild stash tab.
- **substash_id** (string) - Optional - The public identifier of a guild sub-tab.

### Response
#### Success Response (200)
- **stash** (StashTab) - The requested stash object.
```

--------------------------------

### Get Guild Stash

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a specific guild stash tab or sub-tab. Requires the account:guild:stashes scope.

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

--------------------------------

### Get Stash Tab Contents

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a specific stash tab object and its contained items. Requires the account:stashes scope.

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

--------------------------------

### Inventory Item Configuration

Source: https://www.pathofexile.com/developer/docs/game

JSON objects defining inventory slots with base item types and stat priority lists.

```json
{
            "inventory_id": "Boots1",
            "additional_text": "<red>{Armour (Str Base)}\n\n<grey>{Stat Priority\n-------------------\n1. Increased Movement Speed\n2. Increased Health\n3. Increased Resistances\n4. Increased Armour}"
        }
```

```json
{
            "inventory_id": "Helm1",
            "additional_text": "<red>{Armour (Str Base)}\n\n<grey>{Stat Priority\n-------------------\n1. Increased Health\n2. Increased Resistances\n3. Increased Armour}"
        }
```

```json
{
            "inventory_id": "Gloves1",
            "additional_text": "<red>{Armour (Str Base)}\n\n<grey>{Stat Priority\n-------------------\n1. Increased Attack Speed\n2. Flat damage to attacks\n3. Increased Life\n4. Increased Resistances}"
        }
```

```json
{
            "inventory_id": "Belt1",
            "additional_text": "<silver>{Any Belt}\n\n<grey>{Stat Priority\n-------------------\n1. Increased Health\n2. Increased Resistances}"
        }
```

```json
{
            "inventory_id": "Ring1",
            "additional_text": "<silver>{Any Ring (Resistance Base)}\n\n<grey>{Stat Priority\n-------------------\n1. Flat damage to attacks\n2. Increased Life\n3. Increased Resistances}"
        }
```

```json
{
            "inventory_id": "Ring2",
            "additional_text": "<silver>{Any Ring (Resistance Base)}\n\n<grey>{Stat Priority\n-------------------\n1. Flat damage to attacks\n2. Increased Life\n3. Increased Resistances}"
        }
```

```json
{
            "inventory_id": "Amulet1",
            "additional_text": "<silver>{Any Amulet}\n\n<grey>{Stat Priority\n-------------------\n1. Level of all melee skills\n2. Increased Resistances\n3. Increased Intelligence\n4. Increased Life}"
        }
```

--------------------------------

### Generate PKCE Code Verifier and Challenge in PHP

Source: https://www.pathofexile.com/developer/docs/authorization

Creates a cryptographically secure code verifier and its corresponding SHA256 base64url-encoded challenge.

```php
// PHP example
$base64url_encode = fn(string $value): string => \rtrim(\strtr(\base64_encode($value), '+/', '-_'), '=');

$secret = \random_bytes(32);
$code_verifier = $base64url_encode($secret);
$code_challenge = $base64url_encode(\hash('sha256', $code_verifier, true));
```

--------------------------------

### POST /oauth/token

Source: https://www.pathofexile.com/developer/docs/authorization

Endpoint for creating access tokens.

```APIDOC
## POST /oauth/token

### Description
Endpoint for creating tokens.

### Method
POST

### Endpoint
/oauth/token
```

--------------------------------

### List PvP Matches

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a list of PvP matches. Requires the service:pvp_matches scope.

```http
GET /pvp-match
```

--------------------------------

### Set User-Agent Header Format

Source: https://www.pathofexile.com/developer/docs/index

Required format for the User-Agent header when interacting with the API.

```http
User-Agent: OAuth {$clientId}/{$version} (contact: {$contact}) ...
```

```http
User-Agent: OAuth mypoeapp/1.0.0 (contact: mypoeapp@gmail.com) SomeOptionalThingHere
```

--------------------------------

### POST /oauth/token (Client Credentials)

Source: https://www.pathofexile.com/developer/docs/authorization

Exchanges client credentials for an access token to access services unrelated to an individual account.

```APIDOC
## POST /oauth/token

### Description
Requests an access token using the client_credentials grant type. This token does not expire and is tied to the application owner.

### Method
POST

### Endpoint
https://www.pathofexile.com/oauth/token

### Request Body
- **client_id** (string) - Required - The application client ID.
- **client_secret** (string) - Required - The application client secret.
- **grant_type** (string) - Required - Must be set to 'client_credentials'.
- **scope** (string) - Required - The requested scope (e.g., 'service:psapi').

### Response
#### Success Response (200)
- **access_token** (string) - The bearer token.
- **expires_in** (null) - Expiration time.
- **token_type** (string) - The type of token.
- **username** (string) - The application owner username.
- **sub** (string) - The subject identifier.
- **scope** (string) - The granted scopes.
```

--------------------------------

### Parse Version 6.2 Ascendancy and Bloodline Data

Source: https://www.pathofexile.com/developer/docs/reference

Demonstrates how to extract ascendancy and bloodline information from the 8-bit ascendancy field using bitwise operations.

```javascript
// (in JavaScript)
const ascendancyData = 0x1B; // (unsigned 8-bit) 27 or (binary) 00 01 10 11
const ascendancy = ascendancyData & 0x3; // 3, the Third Ascendancy of the class
const bloodline = ascendancyData >>> 2; // 6, Nameless Bloodline
```

--------------------------------

### Request Client Credentials Token

Source: https://www.pathofexile.com/developer/docs/authorization

Use this POST request to obtain an access token for services unrelated to an individual account. Tokens generated this way do not expire.

```http
POST https://www.pathofexile.com/oauth/token
...
Content-Type: application/x-www-form-urlencoded  

 client_id=example
&client_secret=verysecret
&grant_type=client_credentials
&scope=service:psapi
```

```json
{
    "access_token": "cded8a4638ae9bc5fe6cd897890e25e41f0f4e21",
    "expires_in": null,
    "token_type": "bearer",
    "username": "Novynn",
    "sub": "c5b9c286-8d05-47af-be41-67ab10a8c53e",
    "scope": "service:psapi"
}
```

--------------------------------

### List Account Characters

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a list of all characters associated with the account. Requires the account:characters scope.

```http
GET /character[/<realm>]
```

--------------------------------

### Rate Limit Headers

Source: https://www.pathofexile.com/developer/docs/index

Explanation of the response headers used to communicate rate limit status and state.

```APIDOC
## Rate Limit Headers

### Description
API endpoints include specific headers to communicate rate limit policies and current usage state. Applications should monitor these headers to ensure compliance.

### Headers
- **X-Rate-Limit-Policy** (string) - The policy applied to the request.
- **X-Rate-Limit-Rules** (string) - Comma-delimited list of applicable rules (e.g., ip, account, client).
- **X-Rate-Limit-{$rule}** (string) - Defines the rule limits: max hits : period (seconds) : restriction time (seconds).
- **X-Rate-Limit-{$rule}-State** (string) - Defines current state: current hits : period (seconds) : active restriction time (seconds).
- **Retry-After** (integer) - Time in seconds to wait until the rate limit expires when a 429 status is received.
```

--------------------------------

### List Leagues

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves a list of leagues based on optional filters like realm, type, and pagination parameters.

```http
GET /league
```

--------------------------------

### POST /item-filter

Source: https://www.pathofexile.com/developer/docs/reference

Creates a new item filter.

```APIDOC
## POST /item-filter

### Description
Creates a new item filter. Requires the 'account:item_filter' scope.

### Method
POST

### Endpoint
/item-filter

### Parameters
#### Query Parameters
- **validate** (bool) - Optional - Set to true to validate the filter against the current game version.

#### Request Body
- **filter_name** (string) - Required
- **realm** (string) - Required - 'pc', 'xbox', 'sony', or 'poe2'
- **description** (?string) - Optional
- **version** (?string) - Optional
- **type** (?string) - Optional - 'Normal' or 'Ruthless'
- **public** (?bool) - Optional - Defaults to false
- **filter** (string) - Required

### Response
#### Success Response (200)
- **filter** (ItemFilter) - The created item filter.
```

--------------------------------

### POST /oauth/token

Source: https://www.pathofexile.com/developer/docs/authorization

Exchanges an authorization code for an access token.

```APIDOC
## POST /oauth/token

### Description
Exchanges the authorization code obtained from the redirect for an access token and refresh token.

### Method
POST

### Endpoint
https://www.pathofexile.com/oauth/token

### Parameters
#### Request Body
- **client_id** (string) - Required - Your registered application's client id.
- **client_secret** (string) - Optional - Your registered application's client secret.
- **grant_type** (string) - Required - Must be 'authorization_code'.
- **code** (string) - Required - The authorization code obtained previously.
- **scope** (string) - Required - Space-separated list of requested scopes.
- **redirect_uri** (string) - Required - The URL used in the initial authorization request.
- **code_verifier** (string) - Required - The original code_verifier generated for PKCE.

### Response
#### Success Response (200)
- **access_token** (string) - The bearer token for API access.
- **expires_in** (integer) - Token expiration time in seconds.
- **token_type** (string) - The type of token (bearer).
- **scope** (string) - The granted scopes.
- **username** (string) - The authenticated user's username.
- **sub** (string) - The user's unique identifier.
- **refresh_token** (string) - Token used to obtain new access tokens.
```

--------------------------------

### Construct Authorization URL

Source: https://www.pathofexile.com/developer/docs/authorization

The URL used to redirect users to the Path of Exile OAuth server for authorization.

```http
https://www.pathofexile.com/oauth/authorize
    ?client_id=example
    &response_type=code
    &scope=account:profile
    &state=10ceb8104963e91e47a95f4138448ecf
    &redirect_uri=https://example.com
    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
    &code_challenge_method=S256
```

--------------------------------

### Authorizing a Request

Source: https://www.pathofexile.com/developer/docs/authorization

To authenticate API requests, include the access token in the Authorization header using the Bearer scheme.

```APIDOC
## Authorization Header

### Description
All requests to the API must include an access token in the `Authorization` header to authenticate the user.

### Header Format
`Authorization: Bearer <access_token>`

### Error Handling
- **401 Unauthorized**: The token has expired or has been revoked. Generate a new token.
- **403 Forbidden**: The token lacks the required scope for the requested resource. Generate a new token with the correct scopes.
```

--------------------------------

### Access Token Response Format

Source: https://www.pathofexile.com/developer/docs/authorization

The JSON response received upon a successful token exchange, containing the access and refresh tokens.

```json
{
    "access_token": "486132c90fedb152360bc0e1aa54eea155768eb9",
    "expires_in": 2592000,
    "token_type": "bearer",
    "scope": "account:profile",
    "username": "Novynn",
    "sub": "c5b9c286-8d05-47af-be41-67ab10a8c53e",
    "refresh_token": "17abaa74e599192f7650a4b89b6e9dfef2ff68cd"
}
```

--------------------------------

### POST /oauth/token (Refresh Token)

Source: https://www.pathofexile.com/developer/docs/authorization

Exchanges a refresh token for a new access token to maintain API access without user re-consent.

```APIDOC
## POST /oauth/token

### Description
Requests a new access token using a valid refresh token. The old refresh token is invalidated upon use.

### Method
POST

### Endpoint
https://www.pathofexile.com/oauth/token

### Request Body
- **client_id** (string) - Required - The application client ID.
- **client_secret** (string) - Required - The application client secret.
- **grant_type** (string) - Required - Must be set to 'refresh_token'.
- **refresh_token** (string) - Required - The current refresh token.

### Response
#### Success Response (200)
- **access_token** (string) - The new bearer token.
- **expires_in** (integer) - Expiration time in seconds.
- **token_type** (string) - The type of token.
- **scope** (string) - The granted scopes.
- **username** (string) - The username.
- **sub** (string) - The subject identifier.
- **refresh_token** (string) - The new refresh token.
```

--------------------------------

### List Account Stashes

Source: https://www.pathofexile.com/developer/docs/reference

Retrieves all stash tabs for a specific league, including sub-tabs and folders. Requires the account:stashes scope.

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

--------------------------------

### POST /oauth/token/introspect

Source: https://www.pathofexile.com/developer/docs/authorization

Endpoint for checking the status of tokens.

```APIDOC
## POST /oauth/token/introspect

### Description
Endpoint for checking tokens. Requires the oauth:introspect scope.

### Method
POST

### Endpoint
/oauth/token/introspect
```

--------------------------------

### List Guild Stashes

Source: https://www.pathofexile.com/developer/docs/reference

Lists all guild stash tabs accessible to the account in a specific league. Requires the account:guild:stashes scope.

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

--------------------------------

### API Rate Limit Response Headers

Source: https://www.pathofexile.com/developer/docs/index

Standard response headers indicating current rate limit status and policy.

```http
HTTP/1.1 200 OK
...
X-Rate-Limit-Policy: ladder-view
X-Rate-Limit-Rules: client
X-Rate-Limit-Client: 10:5:10
X-Rate-Limit-Client-State: 1:5:0

```

```http
HTTP/1.1 429 Too Many Requests
...
X-Rate-Limit-Policy: ladder-view
X-Rate-Limit-Rules: client
X-Rate-Limit-Client: 10:5:10
X-Rate-Limit-Client-State: 11:5:10
Retry-After: 10

```

--------------------------------

### Parse Version 6 Mastery Effect Pairs

Source: https://www.pathofexile.com/developer/docs/reference

Extracts the node skill hash and effect hash from a 32-bit mastery effect pair.

```javascript
// (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
```

--------------------------------

### Exchange Authorization Code for Access Token

Source: https://www.pathofexile.com/developer/docs/authorization

A POST request to the token endpoint to exchange the authorization code and verifier for an access token.

```http
POST https://www.pathofexile.com/oauth/token
...
Content-Type: application/x-www-form-urlencoded  

 client_id=example
&client_secret=verysecret
&grant_type=authorization_code
&code=d25cc653854f1d4db9c0797a30a374c6
&redirect_uri=https://example.com
&scope=account:profile
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
```

--------------------------------

### POST /item-filter/<id>

Source: https://www.pathofexile.com/developer/docs/reference

Updates an existing item filter.

```APIDOC
## POST /item-filter/<id>

### Description
Updates an existing item filter. Allows partial updates.

### Method
POST

### Endpoint
/item-filter/<id>

### Parameters
#### Path Parameters
- **id** (string) - Required - The item filter ID.

#### Query Parameters
- **validate** (bool) - Optional - Set to true to validate the filter against the current game version.

#### Request Body
- **filter_name** (?string) - Optional
- **realm** (?string) - Optional - 'pc', 'xbox', 'sony', or 'poe2'
- **description** (?string) - Optional
- **version** (?string) - Optional
- **type** (?string) - Optional - 'Normal' or 'Ruthless'
- **public** (?bool) - Optional - Must be true if present
- **filter** (?string) - Optional

### Response
#### Success Response (200/202)
- **filter** (ItemFilter) - The updated filter.
- **error** (?Error) - Returned if status is 202 (Accepted).
```

--------------------------------

### POST /oauth/token/revoke

Source: https://www.pathofexile.com/developer/docs/authorization

Endpoint for revoking existing access tokens.

```APIDOC
## POST /oauth/token/revoke

### Description
Endpoint for revoking tokens. Requires the oauth:revoke scope.

### Method
POST

### Endpoint
/oauth/token/revoke
```

--------------------------------

### Request Refresh Token

Source: https://www.pathofexile.com/developer/docs/authorization

Exchange a valid refresh token for a new access token to maintain session access without re-prompting the user.

```http
POST https://www.pathofexile.com/oauth/token
...
Content-Type: application/x-www-form-urlencoded  

 client_id=example
&client_secret=verysecret
&grant_type=refresh_token
&refresh_token=17abaa74e599192f7650a4b89b6e9dfef2ff68cd
```

```json
{
    "access_token": "41bcefbc2f0d6ea0fa1cce10c435310d3c475e5b",
    "expires_in": 2592000,
    "token_type": "bearer",
    "scope": "account:profile"
    "username": "Novynn",
    "sub": "c5b9c286-8d05-47af-be41-67ab10a8c53e",
    "refresh_token": "4e9dbe97e038430bd943d35f8d5f8bef99699396"
}
```

--------------------------------

### Authorize a Request with Bearer Token

Source: https://www.pathofexile.com/developer/docs/authorization

Include the access token in the Authorization header for all API requests.

```http
Authorization: Bearer 486132c90fedb152360bc0e1aa54eea155768eb9
```

--------------------------------

### JSON Error Response Structure

Source: https://www.pathofexile.com/developer/docs/index

Standard format for error responses. Use the 'code' field for programmatic decision-making rather than the 'message' field.

```json
{
    "error": {
        "code": 2,
        "message": "Invalid query"
    }
}
```

--------------------------------

### Third-Party Disclaimer Statement

Source: https://www.pathofexile.com/developer/docs/index

Mandatory affiliation disclaimer for public or widely available applications.

```text
This product isn't affiliated with or endorsed by Grinding Gear Games in any way.
```
Tokens:
Raw