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 OAuth2 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.

Getting Started

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

Registering your Application

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

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

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. Here's a breakdown of application types and what we think of them:

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) StrictMode

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.
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 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.

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

Examples:

Code Message
1Resource not found
2Invalid query
3Rate limit exceeded
4Internal error
5Unexpected content type
8Unauthorized
6Forbidden
7Temporarily Unavailable
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.