API Documentation

Welcome to the Wanderer's Guide API! The goal of this documentation is to empower and inform developers in the ways they can utilize the resources Wanderer's Guide provides.

This API can be used in two primary ways: to access general endpoints and to access character endpoints. General endpoints are only GET requests and will return general information about Pathfinder Second Edition (such as an item, spell, or class). Character endpoints can be any kind of request and will have to do with protected information about a character within Wanderer's Guide. All general endpoints can be accessed with just an API key while character endpoints are a bit more difficult to access, they require an access_token – something acquired through successfully gaining access to a character's information via OAuth.

However, any project that uses Wanderer's Guide's API must also comply with Paizo's Community Use Policy. Failure to do so will result in, without warning, termination of the client and potentially further repercussions.

Basic Setup

The first thing you will need to do is register your client application. You can do this under your Profile page.

The information you provide when making your client will be displayed on the character authorization screen and in the character builder for any character you have been given access rights over. If you don't intend to access any character endpoints, the information you provide is not as important (although you will still need to fill in the minimum required fields – such as an app name and redirect URI – even if you won't be utilizing them).

Once created, you will be provided with a client ID and an API key. Your client ID is public information but your API key should be kept secret. If you believe your API key has been compromised, you can generate a new one by clicking refresh.

Setup - General Endpoints

To access the general endpoints you just need your API key. When you make any API request to a general endpoint, include an Authorization header and provide your API key as indicated:

Authorization: Apikey <your API key here>

And that's it! You should now be able to access and request information from any general endpoint.

Setup - Character Endpoints

For access to character endpoints, Wanderer's Guide has its own OAuth provider service — the same technology that lets you login to Reddit with Apple, Medium with Twitter, and even login to Wanderer's Guide with Google.

Below is the listed steps explaining how to establish authorization for a character and be given an access_token for said character. The steps assume a basic understanding of HTTP protocols and OAuth.

Step 1 - Your Authorization Link

The first step in getting access to a character's information is by providing a URL to where they can give your application access to their character. You usually want to have a button linking directing to this URL. Direct your users to the following URL:

wanderersguide.app/api/oauth2/authorize/<their character ID here>

With These Query Parameters:

Parameter
Description

response_type

OAuth grant type. Set this to "code".

client_id

Your client ID.

state

An optional parameter that will be transparently appended as a query parameter when redirecting to your redirect URI. This can be used as a precaution against a CSRF, and can be used as session/user identification as well.

All together your URL should look something like this:

wanderersguide.app/api/oauth2/authorize/<their character ID here>?response_type=code&client_id=<your client ID here>&state=<optional string>

On this page, users will be asked if they wish to grant your client access to their character's information. The scope of what you will be able to do with their character (what API requests you can make) is set when you made your client – the Character Access Rights. When the user clicks allow access, they will be redirected to the redirect URI you had set when creating your client.

Step 2 - Understanding the OAuth Redirect

When the user clicks allow access, they will be redirected to the redirect URI you had provided when making your client. Attached to the end of it, there will be some extra HTTPS query parameters as follows:

Parameter
Description

code

A single-use code that is used to fetch an access token for the character that was just allowed access.

state

The state parameter you provided in Step 1 (if you provided one).

The redirect URL should look something like this:

https://www.mysite.com/custom-uri?code=<single-use code>&state=<string, if you provided one>

Step 3 - Getting Your Access Token

The user has just been redirected to the redirect URI you had provided. Attached to their URL is a code query parameter, listing a single-use code. You now want to use that single-use code to get an access_token for that character.

Make a POST request to the following URL with the following query parameters:

wanderersguide.app/api/oauth2/token?code=<your single-use code>&client_id=<your client ID>

In addition, include an Authorization header in your request and provide your API key as indicated:

Authorization: Apikey <your API key here>

Your request will return a JSON response of:

{

"access_token": <the token you will use to access character information>

"expires_in": <the number of seconds before the access_token will expire>

"char_id": <the ID of the character that the access_token belongs to>

"access_rights": <your access rights for this character, using the given access_token>

"token_type": "Bearer"

}

Step 4 - Using Your Access Token

Now that you have your access_token, you can access the character endpoints for the character the access_token belongs to!

When you make any API request to a character endpoint, include an Authorization header and provide your access_token as indicated:

Authorization: Bearer <your access_token here>

And that's it! You should now be able to access and make requests for any character endpoint that you have the access rights for.

Keep in mind, an access_token is specific to one character. That access_token will only gain you access to requests that are for that character alone. You must also have the necessary access rights to perform certain requests (such as needing the right to update information if you want to call a PUT request).

The Wanderer's Guide API uses the following error codes:

Error Code
Meaning

400

Bad Request – Something was wrong with your request (syntax, size too large, etc).

401

Unauthorized – Authentication failed (bad API key, invalid OAuth token, etc).

403

Forbidden – The requested information is for administrators only.

404

Not Found – The specified resource could not be found.

429

Too Many Requests – Slow down!

General Endpoints

Example

If I wanted to get information about the item caltrops, I would make the following GET request: wanderersguide.app/api/item?name=caltrops with my API key in the Authorization header. On a success, this would return a JSON object containing all the information about the caltrops item.

Feat Requests

Returns

GET /api/feat/all

JSON of all feats

GET /api/feat?id=<feat ID>

JSON of feat data

GET /api/feat?name=<feat name>

JSON of feat data

Item Requests

Returns

GET /api/item/all

JSON of all items

GET /api/item?id=<item ID>

JSON of item data

GET /api/item?name=<item name>

JSON of item data

Spell Requests

Returns

GET /api/spell/all

JSON of all spells

GET /api/spell?id=<spell ID>

JSON of spell data

GET /api/spell?name=<spell name>

JSON of spell data

Class Requests

Returns

GET /api/class/all

JSON of all classes and class features

GET /api/class?id=<class ID>

JSON of class data and all class features

GET /api/class?name=<class name>

JSON of class data and all class features

Archetype Requests

Returns

GET /api/archetype/all

JSON of basic info on all archtypes

GET /api/archetype?id=<archetype ID>

JSON of basic archetype data

GET /api/archetype?name=<archetype name>

JSON of basic archetype data

Ancestry Requests

Returns

GET /api/ancestry/all

JSON of all ancestries

GET /api/ancestry?id=<ancestry ID>

JSON of ancestry data

GET /api/ancestry?name=<ancestry name>

JSON of ancestry data

Heritage Requests

Returns

GET /api/heritage/all

JSON of all heritages

GET /api/heritage?id=<heritage ID>

JSON of heritage data

GET /api/heritage?name=<heritage name>

JSON of heritage data

Versatile Heritage Requests

Returns

GET /api/v-heritage/all

JSON of all v-heritages

GET /api/v-heritage?id=<versatile heritage ID>

JSON of v-heritage data

GET /api/v-heritage?name=<versatile heritage name>

JSON of v-heritage data

Background Requests

Returns

GET /api/background/all

JSON of all backgrounds

GET /api/background?id=<background ID>

JSON of background data

GET /api/background?name=<background name>

JSON of background data

Condition Requests

Returns

GET /api/condition/all

JSON of all conditions

GET /api/condition?id=<condition ID>

JSON of condition data

GET /api/condition?name=<condition name>

JSON of condition data

Trait Requests

Returns

GET /api/trait/all

JSON of all traits

GET /api/trait?id=<trait ID>

JSON of trait data

GET /api/trait?name=<trait name>

JSON of trait data

Character Endpoints

Example

If I wanted to set the current HP of the character with the ID 4321 to 15 HP, I would make the following PUT request: wanderersguide.app/api/char/4321/current-hp?value=15 with my access_token in the Authorization header. I would also need the appropriate access rights, I would need the right to update character information. On a success, this would return the 200 HTTP status code (OK), meaning the update was successful.

Basic Character Requests

Returns
Access Rights

GET /api/char/<character ID>

JSON of basic character info

Read

GET /api/char/<character ID>/metadata

Array of all raw character metadata as JSON objects, this includes all feat choices and proficiencies

Read

GET /api/char/<character ID>/metadata-feats

Array of all the character's chosen feats metadata, processed to include feat details as well

Read

GET /api/char/<character ID>/current-hp

Character's current HP (integer)

Read

PUT /api/char/<character ID>/current-hp?value=<new HP>

OK

Update

GET /api/char/<character ID>/temp-hp

Character's temp HP (integer)

Read

PUT /api/char/<character ID>/temp-hp?value=<new temp HP>

OK

Update

GET /api/char/<character ID>/hero-points

Character's Hero Points (integer)

Read

PUT /api/char/<character ID>/hero-points?value=<new Hero Points>

OK

Update

GET /api/char/<character ID>/experience

Character's experience (integer)

Read

PUT /api/char/<character ID>/experience?value=<new experience>

OK

Update

Conditions Requests

Returns
Access Rights

GET /api/char/<character ID>/conditions

JSON of character's conditions data

Read

POST /api/char/<character ID>/conditions?id=<condition ID>&value=[optional, value of condition]

JSON of updated conditions data

Add

DELETE /api/char/<character ID>/conditions?id=<condition ID>

JSON of updated conditions data

Delete

Inventory Requests

Returns
Access Rights

GET /api/char/<character ID>/inventory

JSON of character's inventory data, including an array of inventory items (their "id" is the invItem ID – a unique identifier for that character's item)

Read

PUT /api/char/<character ID>/inventory/equip-armor-shield?armor_inv_item_id=[invItem ID of armor to be equipped, don't include parameter for none]&shield_inv_item_id=[invItem ID of shield to be equipped, don't include parameter for none]

OK

Update

POST /api/char/<character ID>/inventory/add-item?item_id=<item ID>&quantity=[optional, item quantity]

JSON of invItem data

Add

DELETE /api/char/<character ID>/inventory/remove-item?inv_item_id=<invItem ID>

No Content (204)

Delete

PUT /api/char/<character ID>/inventory/move-item?moving_inv_item_id=<invItem ID of item being moved>&bag_inv_item_id=[invItem ID of bag the item is being moved to, don't include parameter to make the item unstored]

OK

Update

PUT /api/char/<character ID>/inventory/drop-item?inv_item_id=<invItem ID>

OK

Update

Item Requests

Returns
Access Rights

GET /api/char/<character ID>/item?inv_item_id=<invItem ID>

JSON of invItem data

Read

PUT /api/char/<character ID>/item/qty?inv_item_id=<invItem ID>&value=<new quantity>

OK

Update

Spellcasting Requests

Returns
Access Rights

GET /api/char/<character ID>/spell

JSON of character's general spell data: spell slots, spell book, innate spells, focus spells, focus points

Read

Companion Requests

TO-DO

Calculated stats is Wanderer's Guide's solution to being able to give API users an idea of what a character's stats look like without having to manually try to calculate them based on the endless list of factors that could impact them.

Each time a character sheet is loaded and all the math to calculate the character's stats is complete, the final character stats will be sent back and updated (which is the information you would be requesting here).

Keep in mind these stats are just the final base numbers, they do not include any conditional bonuses.

Calculated Stats Requests

Returns
Access Rights

GET /api/char/<character ID>/calculated-stats

JSON of character's calculated stats

Read

Roll History Requests

Returns
Access Rights

GET /api/char/<character ID>/roll-history

JSON of character's dice roll history

Read