Context API Reference

Welcome to the NPC Builder Context API documentation. This API allows you to manage characters, worlds, regions, and locations within your game. Below you’ll find detailed information on how to use each endpoint, including request and response examples.

Login to NPC Builder app #

Access NPC Builder web app by entering this link: https://app.npcbuilder.com.

Navigate to developers section #

Click on developers section icon at the navigation bar.

Generate auth token #

Click the generate bearer token button and copy the result. Save it for later!

I case you would like to use API Keys for authentication, you should pass the following headers:

{
"clientId": "<api_key_id>",
"clientSecret": "<api_key_secret>"
}

Obtain game and world IDs #

Find in the tree below the game and the world IDs where your character is located in.

Technical limitations #

  • You must stick to the data structure defined, otherwise you may encounter unhandled errors.
  • Please check the schemas of each request to find the allowed values for certain properties.
  • Character’s knowledge and relationships updating and deleting are not available through the API. They must be managed through our app’s frontend.

Build your API request #

For the full details please refer to the complete API definition Swagger.

Update Character Details #

Allowed properties:

  • age: a string representing the age of the character. Possible values are:
    • “infant”
    • “child”
    • “teenager”
    • “youngAdult”
    • “adult”
    • “middleAged”
    • “elderly”
  • description: a string describing the character. Maximum length is 1400 characters.
  • gender: a string representing the gender of the character. It can be “Male”, “Female”, or any other value. If “Male” or “Female” is provided, it should be capitalized.
  • items: an array of objects representing items the character possesses. Each item has:
    • itemName: a string representing the name of the item. Maximum length is 25 characters.
    • unit: a string representing the unit of the item. Maximum length is 25 characters.
    • value: a string representing the value of the item. Maximum length is 25 characters.
  • name: a string representing the name of the character. Maximum length is 25 characters.
  • quests: an array of objects representing quests associated with the character. Each quest has:
    • description: a string representing the quest description. Maximum length is 125 characters.
    • objective: a string representing the quest objective. Maximum length is 125 characters.
    • reward: a string representing the quest reward. Maximum length is 125 characters.
  • role: a string representing the role of the character. Possible values are:
    • “noRole”
    • “protagonist”
    • “antagonist”
    • “secondaryCharacter”
    • “tertiaryCharacter”
    • “mentor”
    • “enemy”
    • “villain”
    • “rival”
    • “shopkeeper”
    • “healer”
    • “questGiver”
    • “innkeeper”
    • “guard”
    • “familyMember”
    • “loveInterest”
    • “scientist”
    • “politician”
    • “criminal”
    • “explorer”
    • “wizard”
    • “ghost”
    • “animalCompanion”
    • “artificialIntelligence”
  • tone: a string representing the tone of the character. Possible values are:
    • “formal”
    • “casual”
    • “sarcastic”
    • “mysterious”
    • “emotive”
  • traits: an array of strings representing the character traits. Each trait can be any string, but pairs of opposite traits cannot be included together. Possible opposites include:
    • “funny” / “serious”
    • “kind” / “cruel”
    • “generous” / “selfish”
    • “optimistic” / “pessimistic”
    • “brave” / “coward”
    • “arrogant” / “humble”
    • “calm” / “nervous”
    • “polite” / “rude”
    • “joyful” / “sad”
    • “extroverted” / “introverted”
PATCH /characters/{game_id}/{world_id}/{character_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "age": "adult",
  "description": "A brave warrior with a mysterious past.",
  "gender": "Male",
  "items": [
    {
      "itemName": "Sword",
      "unit": "Piece",
      "value": "100"
    }
  ],
  "name": "Aragorn",
  "quests": [
    {
      "description": "Retrieve the lost artifact.",
      "objective": "Find and return the artifact.",
      "reward": "500 gold coins"
    }
  ],
  "role": "protagonist",
  "tone": "mysterious",
  "traits": ["brave"]
}
Delete Character #
DELETE /characters/{game_id}/{world_id}/{character_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Update World Details #

Allowed properties:

  • lore: a string representing the lore of the world. Maximum length is 1400 characters.
  • name: a string representing the name of the world. Maximum length is 25 characters.
  • creatures: a string representing the creatures in the world. Maximum length is 75 characters.
  • similarWorlds: an array of strings representing similar worlds.
PATCH /world/{game_id}/{world_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "lore": "A world where magic and technology coexist.",
  "name": "Eldoria",
  "creatures": "Dragons, Elves",
  "similarWorlds": ["Middle Earth"]
}
Delete World #
DELETE /world/{game_id}/{world_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Update Region Details #

Allowed properties:

  • lore: a string representing the lore of the region. Maximum length is 1400 characters.
  • name: a string representing the name of the region. Maximum length is 25 characters.
  • weather: a string representing the weather in the region. Maximum length is 25 characters.
  • culture: a string representing the culture of the region. Maximum length is 125 characters.
  • politicalStability: a string representing the political stability of the region. Possible values are:
    • “none”
    • “highlyStable”
    • “stable”
    • “moderatelyStable”
    • “unstable”
    • “highlyUnstable”
    • “anarchy”
PATCH /region/{game_id}/{world_id}/{region_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "lore": "A dense forest with hidden secrets.",
  "name": "Mystic Forest",
  "weather": "Rainy",
  "culture": "Druidic traditions",
  "politicalStability": "stable"
}
Delete Region #
DELETE /region/{game_id}/{world_id}/{region_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Update Location Details #

Allowed properties:

  • lore: a string representing the lore of the location. Maximum length is 1400 characters.
  • name: a string representing the name of the location. Maximum length is 25 characters.
  • role: a string representing the role of the location. Maximum length is 25 characters.
PATCH /location/{game_id}/{world_id}/{location_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "lore": "A bustling market town.",
  "name": "Rivertown",
  "role": "Trade hub"
}
Delete Location #
DELETE /location/{game_id}/{world_id}/{location_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>

Swagger #