Path of Exile Developer Docs

Introduction

Our website provides a basic set of API endpoints that allow access to various components of Path of Exile. This access is almost always a read-only snapshot of data stored on the game servers.

Although we are excited to provide these resources to you, the stability of the website and game servers are of upmost importance to us. To this end the details in this document may change without notice as we adjust to protect our backend from being overloaded. We make no guarantee of website uptime, or that API endpoints will remain available indefinitely.

We implement the OAuth 2.0 standard in order to secure access to our APIs. This allows registered applications to view private account data in a manner where the user has complete control over what they share. You can read more about this in the Authorization section of these docs.

Third-Party Policy

Applications must adhere to requirements outlined by our Terms of Service and Privacy Policy. Depending on your use case, you must also respect the privacy of players who grant you access to their personal data.

You must follow the guidelines within this document as closely as you can. We reserve the right to remove access to any or all of our APIs and services without notice at our discretion.

Our general policy is to only allow the creation of applications that run completely separate from the game. We don't encourage players to download or run "tools" on their machine as these are never guaranteed to be free from malware or nefarious practices. Even if an application performs only actions approved by us, there is nothing stopping that from changing without the user's, or our, notice.

For these reasons and more, the safest kind of application for our players is a website that interacts with our API. The following is a breakdown of application types and what we think of them.

Websites and web apps

Executable apps that run independently from the game

Executable apps that interact with the game or game files

Getting Started

Remember to read the next section (Developer Guidelines) to make sure you understand what an application can or cannot do.

In order to register you must have:

Registering your Application

Registration is currently handled by us directly at our discretion. You can make a request by emailing oauth@grindinggear.com with your details and requirements.

Things to include:

  1. Your PoE account name.
  2. Your application's name.
  3. The type of client you want to register.
  4. The grant types you require.
  5. The scopes you are interested in, and why you specifically need each one.
  6. A secure redirect URI if you plan to use the a confidential client using the authorization_code grant type OR
    a local redirect URI if you plan to use the a public client.

Please be aware that these requests are considered a low priority and we may not be able to respond in a timely manner (especially around league launches).

You can manage applications owned by your account by visiting the Manage applications link in your profile.

Available Resources

We can only support resources defined in our API Reference or listed in our Data Exports.

Requests for access to any other internal website APIs or in-game resources will be denied. It is against our Terms of Use (section 7i) to reverse-engineer endpoints outside of this documentation.

Developer Guidelines

Failing to meet any guidelines listed here may result in your application's access being revoked.

OAuth Credentials

User Agent

Any application that interacts with our API must set an identifiable User Agent header prefixed using the following format:

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

Example:

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

Third-Party Notice

Every public or widely available application should include some form of the following statement in a visible location:

This product isn't affiliated with or endorsed by Grinding Gear Games in any way.

Error Handling

The following sections in this document describe why API errors occur and what you should do when you encounter them. Please read on!

Errors

HTTP Status Codes

The Path of Exile API returns different HTTP status codes depending on whether or not the request was successful or resulted in some other error.

Examples:

Code Text Description
200OKThe request succeeded.
202AcceptedThe request was accepted but may not be processed yet.
400Bad RequestThe request was invalid. Check that all arguments are in the correct format.
404Not FoundThe requested resource was not found.
429Too many requestsYou are making too many API requests and have been rate limited.
500Internal Server ErrorWe had a problem processing your request. Please try again later or post a bug report.

Error Messages

Error responses will usually contain a JSON object such as the one below. If your application makes decisions based on the error response make sure you use the code rather than the message as the message is subject to change.

Note: Endpoints that implement the OAuth specification will return errors according to the relevant RFC.

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

Examples:

Code Message
0Accepted
1Resource not found
2Invalid query
3Rate limit exceeded
4Internal error
5Unexpected content type
6Forbidden
7Temporarily Unavailable
8Unauthorized
9Method not allowed
10Unprocessable Entity

Invalid Requests Threshold

Applications (and users) that make too many invalid requests in a short period of time will be restricted from further access to our service.

Invalid requests include any response codes in the HTTP 4xx range. This includes common codes such as 401 (Unauthorized), 403 (Forbidden), and 429 (Too Many Requests).
Reasonable attempts must be made in order to avoid passing the threshold.

Rate Limits

In order to protect our services we employ the use of rate limits on the majority of our endpoints. These limits are dynamic and can change at any time depending on our requirements.
For this reason we include headers in response headers that should be parsed and followed by your application.

Example:

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

Example that has exceeded the limit:

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

Breakdown:

Exceeding these limits frequently will result in your application access being revoked.