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

• Little to no risk for end users.
• Allows you to keep your OAuth client credentials secure.
• You can cache content on a broader basis, reducing API calls associated with your application.

Executable apps that run independently from the game

• While not encouraged, these are permitted. They must use a public OAuth client if interacting with our APIs.
• Reading the game's log files is okay as long as the user is aware of what you are doing with that data.
• Automation of key-strokes (or other inputs) that affect the game in any way must follow our macro rules:
  • Macros must be invoked manually by the user (automated invocations such as but not limited to: timers, reacting to file changes, or from reading the screen are not allowed).
  • Each macro invocation must have one set function (it cannot cycle between actions).
  • The resulting function must only perform one action that interacts with the game (sending a single chat message or command counts as one action).
• Introducing features against these guidelines or our Terms of Use can result in account termination for you as well as your users.

Executable apps that interact with the game or game files

• This behaviour is strictly against our Terms of Use (section 7b).
• Creation or use of these type of applications will result in immediate account termination.

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:

• A basic understanding of what OAuth is and what it lets you do.
• Read and understand the different types of OAuth clients, as well as the difference in grant types available.
• Read the list of scopes and confirm that they provide access to the resources you are interested in.

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

• Keep your credentials safe.
  • Don't share your account or application's credentials with anyone else.
  • Don't include any application keys or credentials in your code.
  • Don't embed keys or credentials in a distributed binary.
• One product per registered application

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:

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:

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:

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:

• X-Rate-Limit-Policy

  The policy that applies to this request.

  Policies may be the same across different API endpoints but are treated the same for rate limiting purposes.

• X-Rate-Limit-Rules

  A comma-delimited list of applicable rules.

  This can be used to determine the header key for the next two headers.

  Common rules are: ip, account, and client.

• X-Rate-Limit-{$rule}

  A comma-delimited list of text representing the rule.

  These are made up of three numbers separated by a colon with each representing:

  1. the maximum hits
  2. the period (in seconds) tested
  3. the time restricted (in seconds) if the rule is broken

• X-Rate-Limit-{$rule}-State

  A comma-delimited list of text representing the request's current state.

  Similarly to the header above, these are made up of three numbers separated by a colon with each representing:

  1. the current hit count
  2. the period (in seconds) tested
  3. the active time restricted in seconds (this will be 0 if the request is not rate limited)

• Retry-After

  Time to wait (in seconds) until the rate limit expires.

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