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:
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:
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:
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
GET /api/char/<character ID>/calculated-stats
JSON of character's calculated stats
Read
Roll History Requests
GET /api/char/<character ID>/roll-history
JSON of character's dice roll history
Read