{{ settings.application.app_name }}

{{ settings.application.title }}

API Version {{ settings.api.version }}

API Documentation!

The KDM API at http://api.thewatcher.io is a RESTful API for campaign/settlement management in "Monster" by Kingdom Death.

The API is a fan-created and fan-maintained project that is not supported by, affiliated with or otherwise authorized by Kingdom Death.

GitHub | Twitter | Development blog

PUBLIC ROUTES

These routes DO NOT require authentication. Use them to construct dashboard, "create new whatever" type views and to look up game asset data that does not belong to any user.

RouteMethodsComment/Note
/campaign POST

Accepts a "name" or "handle" parameter included in the body of the request (which should be JSON) and returns a JSON representation of the campaign:

{"name": "People of the Lantern"}

...gets you something like this:

{"handle": "people_of_the_lantern","milestones": ["first_child", "first_death", "pop_15", "innovations_5", "game_over" ], "saviors": "1.3.1", "name": "People of the Lantern", "default": true, "principles": ["new_life", "death", "society", "conviction"], "always_available": { "location": ["Lantern Hoard"], "innovation": ["Language"]},"nemesis_monsters": [ "butcher", "kings_man","the_hand","watcher"],"quarries": [ "white_lion","screaming_antelope","phoenix", "beast_of_sorrow", "great_golden_cat", "mad_steed", "golden_eyed_king"],"type": "campaign_definition"}

NB: this also works with handles, e.g.:

{"handle": "people_of_the_stars"}
/login POST

The KD:M API uses JSON Web Tokens (https://jwt.io) to manage user sessions and user authentication.

POST to this route with JSON containing user credentials in the body of the request to get a token:

Authorization: {"username": "demo@kdm-manager.com", "password": "l33th4x0r"}

...if your credential checks out, you get a token and the the the user's ID (see below for working with users) back. Easy!

/monster POST

Accepts a "name" or "handle" parameter (via JSON) and returns a JSON representation of a monster type game asset. For example, POSTing to /monster with JSON such as this:

{"name": "White Lion Lvl. 1"}

...returns JSON like this:

{"comment": "Lvl. 1", "handle": "white_lion", "name": "White Lion", "level": 1, "levels": 3, "sort_order": 0, "type": "quarry"}

Or, with a handle:

{"handle": "manhunter"}

...you get:

{"handle": "manhunter", "name": "Manhunter", "levels": 4, "sort_order": 103, "type": "nemesis", "selectable": false, "misspellings": ["THE MANHUNTER", "MAN HUNTER"]}
/new_settlement GET Returns JSON representing available options for creating a new settlement, including expansions, pre-fab survivors, etc. Also includes subtitle/description elements. Use this to make "create new settlement" type views.
/settings.json GET Not strictly a part of the API, but sometimes useful. Hit this route to download an attachement of settings.cfg as JSON.
/settings GET Retrieve settings.cfg as JSON
/world GET Retrieve a JSON representation of aggregate/world stats.
PRIVATE ROUTES

Private routes require an Authorization header including a JWT token.

(See the documentation above for more info on how to POST user credentials to the /login route to get a token.)

Generally speaking, when you access any private route, you want your headers to look like this when using private routes:

{ 'content-type': 'application/json', 'Authorization': 'eyJhbGciOiJIUzI1NiIsInR5cCI6...' }

Finally, keep in mind that tokens are extremely short-lived, so you should be prepared to refresh them frequently. See the section below on 'Authorization Token Management' for more info on checking/refreshing tokens.

RouteMethodsComment/Note
Authorization Token Management: once you've got an authorization token, you can work with it using these routes. Most failures from these routes are reported back as 401's, since they concern authorization.
/authorization/check GET,POST GET or POST to this endpoint to determine if your Authorization header is still valid or if it has expired.
/authorization/refresh POST

Use the standard 'Authorization' header and POST an empty request to this route to recieve a new Auth token based on the previous one.

On the back end, this route reads the incoming 'Authorization' header and, even if the JWT token is expired, will check the 'login' and 'password' (hash) keys: if they check out, you get a 200 and a brand new token.

Finally, the KDM API does NOT use refresh tokens (it just feels like overkill, you know?).

Administrative views and data: If your user has the 'admin' attribute, you can hit these routes to retrieve data about application usage, etc.
/admin/view/panel GET

Admin panel. Not implemented yet.

/admin/data/recent_user_activity GET

Admin panel JSON re: usage, etc. Not implemented yet.

/admin/data/api_logs GET

Returns logs within the requested time/length params. Not implemented yet.

User Routes: all routes for working directly with a user follow a /user/<action>/<settlement_id> convention. These routes are private and require authentication.
/user/get/<user_id> GET Retrieve a serialized version of the user who owns <user_id>, to include some additional usage and meta facts about that user.
/user/set/<user_id> POST, OPTIONS

This route supports the assignment of user-specified key/value attributes to the user object.

To set an attribute, include JSON in the body of the request that indicates the key/value to set.

Supported attribute keys include:
keyvalue
current_settlement OID of an existing,non-removed settlement.
Use multiple key/value pairs to set multiple attributes in a single request, e.g. {"current_settlement": $oid, "current_session": $oid}

Important! This route does not support the assignment of arbitrary keys and will completely fail any request that includes unsupported keys!

Create Assets: To create new assets (survivor, settlement), POST JSON containing appropriate params to the /new/<asset_type> route. Invalid or unrecognized params will be ignored!
/new/settlement POST

Use 'handle' values from the /new_settlement route (see above) as params, like this:

{"campaign": "people_of_the_lantern", "expansions": ["dung_beetle_knight", "lion_god"], "survivors": ["adam", "anna"], "name": "Chicago", "special": ["create_first_story_survivors"]}

If successful, this route returns a serialized version of the new settlement, including its OID, as JSON.

The following special values are supported by the API:

valueresult
create_first_story_survivors Creates two male and two female survivors, assigns them names and places Founding Stones and Cloths in Settlement Storage.
create_seven_swordsmen Creates seven random survivors with the 'Ageless' and Sword Mastery A&Is.

Important! Unsupported special values are ignored.

/new/survivor POST

This works differently from /new/settlement in a number of significant ways.

In a nutshell, the basic idea here is that the only required key in the JSON you POST to this route is an object ID for the settlement to which the survivor belongs:

{'settlement': '59669ace4af5ca799c968c94'}

Beyond that, you are free to supply any other attributes of the survivor, so long as they comply with the data model for survivors.

Finally, here is a table of all modifiable elements of the survivor data model:

keyR/O  type  description
emailOstrDefaults to the requesting user's login.
born_in_lyOintDefaults to current LY.
settlementROID
publicOboolDefaults to Boolean false. Submitting anything that evaluates to Boolean true will be treated as such.
nameOstr
sexOstrAccepts 'M', 'F' or 'R' (for random). Defaults to 'R'.
survivalOint
hunt_xpOint
InsanityOint
HeadOint
ArmsOint
BodyOint
WaistOint
LegsOint
CourageOint
UnderstandingOint
affinitiesOdictconsider using set_affinities route after creation to set this, unless you really know what you're doing
MovementOintDefaults to 5.
AccuracyOint
StrengthOint
EvasionOint
LuckOint
SpeedOint
Weapon ProficiencyOint
weapon_proficiency_typeOstrhandle
abilities_and_impairmentsOlistNeeds a list of handles from the settlement's game_assets element, e.g. {'abilities_and_impairments': ['ageless','mastery_sword']} or similar.
cursed_itemsOlistList of handles
disordersOlistList of names (transitional: changing soon)
fighting_artsOlistList of names (transitional: changing soon)
epithetsOlistlist of handles

As a general piece of advice, it typically makes more sense to just initialize a new survivor with defaults and then operate on it using the routes below.

Important!Just like the /new/settlement route, a successful POST to the /new/survivor route will return a serialized version (i.e. JSON) of the new survivor, complete with the sheet element, etc.

Settlement Routes: all routes for working directly with a settlement follow a /settlement/<action>/<settlement_id> convention. These routes are private and require authentication.

Many operations below require asset handles. Asset handles may be found in the settlement's game_assets element, which contains dictionaries and lists of assets that are available to the settlement based on its campaign, expansions, etc.

Typical settlement JSON looks like this:


            {
                "user_assets": {...},
                "meta": {...},
                "sheet": {...},
                "game_assets": {
                    "milestones_options": {...},
                    "campaign": {...},
                    "weapon_specializations": {...},
                    "locations": {...},
                    "innovations": {...},
                    "principles_options": {...},
                    "causes_of_death": {...},
                    "quarry_options": {...},
                    "nemesis_options": {...},
                    "eligible_parents": {...},
                    ...
                },
            }
            

Important! As indicated elsewhere in this documentation, asset handles will never change. Asset names are subject to change, and, while name-based lookup methods are supported by various routes, using names instead of handles is not recommended.

/settlement/get/<settlement_id> GET Retrieve a serialized version of the settlement associated with <settlement_id> (to include all related user and game assets, including survivors).
/settlement/get_event_log/<settlement_id> GET Retrieve all settlement event log entries (in a giant hunk of JSON).
/settlement/get_innovation_deck/<settlement_id> GET Retrieve the settlement's current innovation deck (as an array).
Settlement attributes: set/update Settlement Sheet attributes, e.g. population, death count, etc.
/settlement/update_population/<settlement_id> POST

POST some JSON containing the key 'modifier' whose value is an integer that you want to add to the settlement's population number.

For example, this JSON would add two to the settlement's population number:

{'modifier': 2}

POST negative numbers to decrease.

important! Settlement population can never go below zero, so any 'modifier' values that would cause this simply cause the total to become zero.

Expansion content management: add and remove expansion content. These methods require posting lists of expansion content handles.
/settlement/add_expansions/<settlement_id> POST Add expansions to a settlement by POSTing a list of expansion handles. The body of your post should be a JSON-style list: ['beta_challenge_scenarios','dragon_king']

Note that this route not only updates the settlement sheet, but also adds/removes timeline events, updates the settlement's available game assets (e.g. items, locations, etc.).

/settlement/rm_expansions/<settlement_id> POST Remove expansions from a settlement by POSTing a list of expansion handles. The body of your post should be a JSON-style list: ['manhunter','gorm','spidicules']

Note that this route not only updates the settlement sheet, but also adds/removes timeline events, updates the settlement's available game assets (e.g. items, locations, etc.).

Important! We're all adults here, and the KDM API will not stop you from removing expansion handles for expansions that are required by your settlement's campaign. If you want to prevent users from doing this, that's got to be part of your UI/UX considerations.

Monster management: update the settlement's quarries, current quarry, nemesis info, etc.
/settlement/set_current_quarry/<settlement_id> POST

This route sets the settlement's 'current_quarry' attribute, which is the monster that the settlement's Departing Survivors are currently hunting.

POST some simple JSON containing a monster name (do not use handles for this):

{'current_quarry': 'White Lion Lvl 2'}

...or, the monster is unique:

{'current_quarry': 'Watcher'}

Important! You're typically going to want to pull monster names from the settlements' game_assets -> defeated_monsters list (which is a list of monster names created for the settlement based on expansion content, etc.)

/settlement/add_defeated_monster/<settlement_id> POST

POST a 'monster' string to this route to add it to the settlement's list of defeated monsters:

{'monster': 'White Lion (First Story)} or {'monster': 'Flower Knight Lvl 1'}

Important! Watch the strings on this one and try to avoid free text: if the API cannot parse the monster name and match it to a known monster type/name, this will fail.

/settlement/rm_defeated_monster/<settlement_id> POST

POST a 'monster' string to this route to remove it from the settlement's list of defeated monsters, i.e. the sheet.defeated_monsters array/list:

{'monster': 'Manhunter Lvl 4'}

Attempts to remove strings that do NOT exist in the list will not fail (i.e. they will be ignored and fail 'gracefully').

/settlement/add_monster/<settlement_id> POST

Use this route to add quarry or nemesis type monsters to the settlement. POST some JSON containing the handle of the monster to add it:

{'handle': 'flower_knight'}

The API will determine whether the monster is a nemesis or a quarry and add it to the appropriate list. For nemesis monsters, use the /settlement/update_nemesis_levels route (below) to manage the checked/completed levels for that nemesis.

Make sure to check the settlement JSON game_assets.monsters and use the correct handle for the desired monster.

/settlement/rm_monster/<settlement_id> POST

POST some JSON containing a quarry or nemesis type monster handle to remove it from the settlement's list:

{'handle': 'sunstalker'}

The API will determine whether the monster is a quarry or a nemesis. When a nemesis monster is removed, its level detail is also removed.

/settlement/update_nemesis_levels/<settlement_id> POST

Use this method to update the Settlement sheet's nemesis_encounters dictionary, i.e. to indicate that a nemesis encounter has occurred.

A typical dictionary might look like this:

"nemesis_encounters": {"slenderman": [], "butcher": [1,2]}

In this example, the settlement has (somehow) encountered a a level 1 Butcher, but has not yet encountered a Slenderman.

To update the dictionary, POST some JSON that includes the nemesis monster's handle and the levels that are complete.

POST this JSON to reset/undo/remove Butcher encounters:

{"handle": "butcher", "levels": []}

POST this JSON to record an encounter with a level 1 Manhunter:

{"handle": "manhunter", "levels": [1]}
Principles and Milestones: routes for setting/unsetting principles and settlement Milestones.
/settlement/set_principle/<settlement_id> POST

POST some JSON to this route to set or unset a settlement principle. Request the handle of the principle and the election you want to make:


            {
                'principle': 'conviction',
                'election': 'romantic',
            }

This route has a couple of unusual behaviors to note:

  • It requires both keys (i.e. you will get a 400 back if you POST any JSON that does not include both).
  • It will accept a Boolean for 'election', because this is how you 'un-set' a principle.

To un-set a principle, simply post the principle handle and set the 'election' key to 'false':

{'principle': 'new_life', 'election': false}

Important! Adding principles to (or removing them from) a settlement automatically modifies all current survivors, in many cases. Be sure to refresh any survivor info after POSTing JSON to this route!

Timeline controls: use these routes to manage the settlement's timeline. These are probably the most complicated controls in the API, so read the docs carefully!
/settlement/add_timeline_event/<settlement_id> POST

Adding a timeline event to a settlement's timeline requires a fairly specific bit of JSON. To add, for example, a settlement event, you need to post JSON that looks like this:

{'type': 'settlement_event', 'ly': 3, 'handle': 'core_haunted', 'name': 'Haunted', 'user_login': 'dev@kdm-manager.com'}

Event names, types, handles, etc. can be found in the settlement's game_assets -> events (which is a dictionary of settlement and story events).

Adding showdown type events works similarly:

{'type': 'showdown_event', 'name': 'White Lion Lvl 1', 'ly': 4, 'user_login': 'user@whatever.com'}

...or, for a special showdown:

{'type': 'special_showdown', 'name': 'Watcher', 'ly': 20, 'user_login': 'qa@kdm-manager.com'}

Here is a list of accepted event 'type' values:

  • showdown_event
  • special_showdown
  • nemesis_encounter
  • settlement_event
  • story_event
Important! Events without handles may be added, which means that you may absolutely add an event that does not come from the settlement's game_assets -> events. Events with neither a name nor a handle may not be added, however.

/settlement/rm_timeline_event/<settlement_id> POST

Works just like the add_timeline_event method, except in reverse. POST some JSON describing a timeline event that exists on the settlement's timeline to remove it:

{'type': 'settlement_event', 'ly': 3, 'handle': 'core_haunted', 'name': 'Haunted', 'user_login': 'dev@kdm-manager.com'}

Since the add_timeline_event method allows for events without handle attributes (i.e. since it will accept JSON with a name and no handle), events may be removed using only their name and Lantern Year ('ly' ) attribute:

{'type': 'nemesis_encounter', 'name': 'Butcher Lvl 1', 'ly': 4, 'user_login': 'user@whatever.com'}
Locations: manage settlement locations and location levels.
/settlement/add_location/<settlement_id> POST

POS aa location handle to this route to add it to the settlement's Locations:

{'handle': 'bome_smith'}
/settlement/rm_location/<settlement_id> POST

This is basically the reverse of add_location and works nearly identically. POST a JSON representation of a Location handle to remove it from the settlement's list:

{'handle': 'barber_surgeon'}
/settlement/set_location_level/<settlement_id> POST

For Locations that have a level (e.g. the People of the Sun's 'Sacred Pool'), you may set the Location's level by posting the handle of the location and the desired level:

{'handle': 'sacred_pool', 'level': 2}
Innovations: manage settlement innovations and innovation levels.
/settlement/add_innovation/<settlement_id> POST

POST an Innovation handle to this route to add it to the settlement's Innovations:

{'handle': 'hovel'}

...or:

{'handle': 'mastery_club'}
/settlement/rm_innovation/<settlement_id> POST

This is basically the reverse of add_innovation and works nearly identically. POST a JSON representation of an Innovation handle to remove it from the settlement's list:

{'handle': 'mastery_club'}
/settlement/set_innovation_level/<settlement_id> POST

For Innovations that have a level (e.g. the Slenderman's 'Dark Water Research'), you may set the Innovation's level by posting the handle of the innovation and the level:

{'handle': 'dark_water_research', 'level': 2}
Other: update the settlement's endeavor token count, lost settlements and other miscellaneous Settlement attributes.
/settlement/update_endeavor_tokens/<settlement_id> POST

Use this route to change a settlement's endeavor token count.

POST some JSON containing the number to modify by:

{"modifier": 2}

The above code would add two to the settlement's current total, whereas the code below would decrement by one:

{"modifier": -1}
/settlement/set_lost_settlements/<settlement_id> POST

Use this route to set a settlement's Lost Settlements total.

POST some JSON containing the new value to set it to:

{"value": 2}

The above code would set the settlement's Lost Settlements total to two; negative numbers will default to zero.

Meta and admin controls: manage settlement meta data, including adding/removing settlement notes, changing the list of settlement admins, etc.
/settlement/add_settlement_note/<settlement_id> POST Documentation coming soon!
/settlement/rm_settlement_note/<settlement_id> POST Documentation coming soon!
Survivor Routes: all routes for working directly with an individual survivor follow a /settlement/<action>/<settlement_id> convention. Like settlement routes, these routes are private and require authentication.
GET routes: retrieve various types of survivor data.
/survivor/get/<survivor_id> GET Retrieve a serialized version of the survivor.
/survivor/get_survival_actions/<survivor_id> GET

Retrieve JSON representing the Survival Actions currently available to the survivor:


    [
        {
            "available": false,
            "sort_order": 0,
            "handle": "dodge",
            "name": "Dodge",
            "type": "survival_action",
            "title_tip": "Impairment 'Broken hip' prevents Wallace from using this ability."
        },
        {
            "available": true,
            "handle": "embolden",
            "name": "Embolden",
            "sort_order": 2,
            "type": "survival_action",
            "title_tip": "Settlement innovation 'Sun Language' unlocks this ability."
        },
        {
            "available": false,
            "handle": "overcharge",
            "name": "Overcharge",
            "sort_order": 5,
            "type": "survival_action",
            "title_tip": "Not unlocked."
        }
    ]

This JSON is updated automatically whenever the the settlement's innovations are update or the survivor's abilities are updated.

Asset management: routes for adding, removing and modifying Survivor Sheet game asset info, e.g. Fighting Arts, Disorders, Abilities & Impairments, etc.

Important! Most of these routes have back-end business logic "baked" into them, so it is highly recommended that you reload/re-get your survivor's JSON after POSTing commands to these routes!

/survivor/add_game_asset/<survivor_id> POST

Use this route to add an asset 'handle' of whatever 'type' to a survivor.

Requires both the 'handle' and 'type' keys:

{'handle': 'blind', 'type': 'abilities_and_impairments'} {'handle': 'crossarm_block', 'type': 'fighting_arts'}

Important! This method enforces many of the incoming asset's attributes, including max, epithet, and so on.

/survivor/rm_game_asset/<survivor_id> POST

The exact inverse of add_game_asset, POSTing to this route requires both 'handle' and 'type' keys and removes a game asset handle from a survivor.

/survivor/add_cursed_item/<survivor_id> POST

POST a cursed item 'handle' to this route to add that cursed item to the survivor:

{'handle': 'thunder_maul'}

Important! This will automatically apply any A&Is and epithets related to the curse to the survivor.

/survivor/rm_cursed_item/<survivor_id> POST

POST a cursed item 'handle' to this route to remove that cursed item from the survivor:

{'handle': 'husk_of_destiny'}

Important! This will automatically apply remove any epithets A&Is, etc. from the survivor (but will not remove any that are still effective, e.g. because another cursed item also requires them.

/survivor/set_weapon_proficiency_type/<survivor_id> POST

POST some JSON containing a weapon proficiency type handle (from the settlement's game_assets to set it as the survivor's weapon type:

{'handle': 'sword'}
Sheet Attributes: routes for updating Survivor Sheet attributes
/survivor/set_attribute/<survivor_id> POST

Use this route to set an arbitrary survivor attribute to an arbitrary value. Requires 'attribute' and 'value' keys.

POST some JSON containing the 'attrib' name and the new 'value' like so:

{'attribute': 'Strength', 'value': 3}

The JSON above would set the survivor's Strength to three. The 'value' should always be an integer. Negative numbers are supported:

{'attribute': 'Evasion', 'value': -2}
/survivor/set_attribute_detail/<survivor_id> POST

All survivors have an attribute_detail element in their sheet JSON:

        "attribute_detail": {
            "Strength": {
                "tokens": 0,
                "gear": 0
            },
            "Evasion": {
                "tokens": 0,
                "gear": 0
            },
            "Movement": {
                "tokens": 0,
                "gear": 0
            },
            "Luck": {
                "tokens": 0,
                "gear": 0
            },
            "Speed": {
                "tokens": 0,
                "gear": 0
            },
            "Accuracy": {
                "tokens": 1,
                "gear": 0
            }
        },

This is used to manage attribute info that is NOT the base attribute value (see set_attribute and update_attribute for updating base values).

To update attribute_detail info, POST some JSON that includes an 'attribute', 'detail' and 'value':

{'attribute': 'Luck', 'detail': 'tokens', 'value': 2}

The sample code above would set the survivor's 'Luck' attribute detail for 'tokens' to two.

/survivor/update_attribute/<survivor_id> POST

Supports arbitrary survivor attribute updates. Requires JSON contianing an 'attribute' and a 'modifier'. Adds the value of 'modifier' to the current value of 'attribute'.

Sample JSON to increase strength by two:

{'attribute': 'Strength', 'modifier': 2}

Sample JSON to decrease Insanity by 1:

{'attribute': 'Insanity', 'modifier': -1}
/survivor/set_name/<survivor_id> POST

POST some JSON containing the survivor's new name like so:

{'name': 'Adam'}

Important! POSTing a blank string as the value of 'name' will result in the survivor's name defaulting to 'Anonymous':

{'name': ''}
/survivor/set_retired/<survivor_id> POST

POST some JSON containing a Boolean value representing whether the survivor is retired or not:

{'retired': true}

The 'retired' value will be duck-typed to a Boolean, so posting anything that evaluates true (e.g. 'checked') will count as a Boolean true, for the intents and purposes of this route.

/survivor/set_sex/<survivor_id> POST

Modify the survivor's sex by POSTing a simple JSON object containing the key 'sex' and a value of either 'M' or 'F'.

{'sex': 'M'}
Survival: routes for managing the survivor's Survival value.
/survivor/update_survival/<survivor_id> POST

POST a 'modifier' integer to this route to add that number to the survivor's Survival:

{"modifier": 2}

...or:

{"modifier": -1}

Important! The API will only allow values greater than the settlement's Survival Limit if expansion (or other) content requires the settlement to NOT enforce Survival Limit.

Important! The API will normalize negative numbers to zero automatically.

/survivor/set_survival/<survivor_id> POST

POST a 'value' integer to this route to set that integer as the survivor's Survival value.:

{"value": 6}

Important! The API will only allow values greater than the settlement's Survival Limit if expansion (or other) content requires the settlement to NOT enforce Survival Limit.

Important! The API will normalize negative numbers to zero automatically.

Specialty routes and 'meta' data controllers: these routes allow the management of data beyond the standard Survivor Sheet fields. These routes typically expect detailed/complex JSON, so read carefully!
/survivor/controls_of_death/<survivor_id> POST

This route is the all-purpose route for managing aspects of a survivor's death, including when it happened, how it happened and so on.

Supported key/value info:

keyR/Ovalue
dead R Boolean. Set to 'true' if the survivor is dead.
died_in O Integer. The Lantern Year in which the survivor died.
cause_of_death O String. Can be anything, but check the settlement's assets for some recommended values: game_assets.causes_of_death

Here is some example JSON for marking a survivor dead:


            {
                "dead": true,
                "died_in": 4,
                "cause_of_death": "Hack City",
            }
            

To resurrect a survivor (i.e. undo their death), simply post some JSON with {"dead": false} ,

This will unset other death-related attributes, e.g. 'cause_of_death', 'died_in', etc.

Important! Since dead is the only required key in JSON that gets POSTed to this route, there is some defaulting that goes on if the other values are undefined. Be as explicit as possible with this route.

/survivor/update_affinities/<survivor_id> POST

Works with the Survivor's affinities dictionary, which contains their permanent, non-token affinities and looks like this by default:

{'red': 0, 'blue': 0, 'green': 0}

POST some JSON containing an optional 'operation' key whose value is 'add' or 'rm' to add or subtract an affinities dictionary called 'aff_dict' to/from the survivor.

Important! The 'operation' key is optional because the default behavior of this method/route is to add the incoming 'aff_dict'.

For example, if you wanted to add a permanent blue affinity to the survivor, you would POST this:

{'aff_dict': {'blue': 1}}

Similarly, if you wanted to add two red affinities and subtract one green affinity, you would POST a JSON object like this one:

{'aff_dict': {'red': 2, 'green': -1}, 'operation': 'add'}

If you wanted to subtract a blue and a green affinity from the survivor, you could POST a JSON object like this one:

{'aff_dict': {'blue': 1, 'green': 1}, 'operation': 'rm'}

Important! The 'operation' key's value must be 'add' or 'rm'. Anything else will get you a 400 response from this route.

/survivor/set_affinity/<survivor_id> POST

POST some JSON containing the two required keys, 'color' and 'value' to set a single survivor affinity to a new integer value.

{'color': 'blue', 'value': -2}

The 'value' key must always have an integer value.

/survivor/set_constellation/<survivor_id> POST

For survivors with Dragon Traits (i.e. PotStars), use this route to set their 'constellation':

{'constellation': 'Witch'}

Simply POST similar JSON to overwrite/change it:

{'constellation': 'Absolute'}

This one also works to unset/remove it:

{'unset': true}

Here is a list of accepted/supported values for 'constellation':

  • Absolute
  • Gambler
  • Goblin
  • Reaper
  • Rust
  • Sculptor
  • Storm
  • Witch

Flags and toggles: special routes and methods for setting/unsetting 'flag' type aspects of the Settlement Sheet.
/survivor/toggle_sotf_reroll/<survivor_id> POST

POST a blank/empty request to this route to toggle the survivor's once per lifetime Survival of the Fittest reroll on or off.

Important! The actual attribute of the survivor's sheet is sotf_reroll:

{"sheet": {"sotf_reroll": true, ...}, "meta": {...}, ...}

But since it is not part of the default data model for survivors, it will sometimes simply be undefined/unset, rather than a.) always present and b.) always a boolean.

/survivor/toggle_boolean/<survivor_id> POST

Use this route to toggle Boolean attributes of the survivor data model, such as 'public'

{'attribute': 'public'}

Important! These attributes are not the same as status flags, which also evaluate Boolean when present on the survivor. See set_status_flag and toggle_status_flag routes below for info on working with status flags.

/survivor/set_status_flag/<survivor_id> POST

This route and its related route toggle_status_flag are used to work with Survivor Sheet 'flags'. The following 'flag' attributes can be set to a boolean value:

  • cannot_spend_survival
  • cannot_use_fighting_arts
  • skip_next_hunt

To set a flag (i.e. to True/true), POST some JSON to this route that includes the 'flag' key with the value of the flag you want to set:

{'flag': 'cannot_spend_survival'}

To unset/remove a flag, POST the key/value, plus the key 'unset' with a value of True/true:

{'flag': 'skip_next_hunt', 'unset': True}
/survivor/toggle_status_flag/<survivor_id> POST

Works nearly identically to set_status_flag (see above), except toggles the flag on/off. POST simple JSON containing the target 'flag' to toggle it:

{'flag': 'cannot_use_fighting_arts'}
Meta and admin controls: manage survivor meta data, including adding/removing survivor notes, etc.
/survivor/add_survivor_note/<survivor_id> POST Documentation coming soon!
/survivor/rm_survivor_note/<survivor_id> POST Documentation coming soon!