Skip to main content
POST
/
context
/
characters
/
{game_id}
/
{world_id}
Create a new character
curl --request POST \
  --url https://app.npcbuilder.com/api/context/characters/{game_id}/{world_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "age": "adult",
  "description": "A brave warrior with a mysterious past.",
  "gender": "Male",
  "model": "standard",
  "filters": {
    "active": true,
    "violence": false,
    "sexual": false,
    "drugs": true
  },
  "items": [
    {
      "type": "trade",
      "itemName": "sword",
      "unit": "Piece",
      "value": 100,
      "description": "A sharp sword."
    }
  ],
  "events": [
    {
      "type": "item",
      "eventName": "Attack",
      "description": "Act of violence against another person."
    }
  ],
  "name": "Aragorn",
  "quests": [
    {
      "description": "Retrieve the lost artifact.",
      "objective": "Find and return the artifact.",
      "reward": "500 gold coins"
    }
  ],
  "role": "protagonist",
  "tone": "mysterious",
  "traits": [
    "brave"
  ]
}
'
{
  "message": "Character: character789 has been created with the following context.",
  "character_id": "character789",
  "character_context": {
    "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"
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
game_id
string
required

The unique identifier for the game.

Example:

"game123"

​
world_id
string
required

The unique identifier for the world.

Example:

"world456"

Query Parameters

​
region_id
string

The unique identifier for the region.

Example:

"region789"

​
location_id
string

The unique identifier for the location.

Example:

"location789"

​
session_id
string

(Optional) The player's session ID.

Example:

"60Z5aZjIuFlyYbjbZZKe"

Body

application/json

The character data required to create a new character.

​
age
enum<string>

The age category of the character.

Available options:
infant,
child,
teenager,
youngAdult,
adult,
middleAged,
elderly
Example:

"adult"

​
description
string

A brief description of the character's background.

Example:

"A brave warrior with a mysterious past."

​
gender
string

The gender of the character.

Example:

"Male"

​
model
enum<string>

The AI model used to power character interactions. Premium models are available only for some subscriptions.

Available options:
standard,
premium
Example:

"standard"

​
filters
object

Structured content filters applied to the character's responses. Toggle the individual categories to restrict what the character can say.

Example:
{
  "active": true,
  "violence": false,
  "sexual": false,
  "drugs": true
}
​
items
object[]

A list of items associated with the character. Each item must follow one of the predefined schemas based on its type.

Schema for items of type "trade"

​
events
object[]

A list of events associated with the character. Each event must adhere to the schema defined for its type.

Schema for events of type "action"

​
name
string

The display name of the character.

Example:

"Aragorn"

​
quests
object[]

A list of quests associated with the character.

​
role
enum<string>

The role of the character in the game. Determines how the character interacts with the story.

Available options:
noRole,
protagonist,
antagonist,
secondaryCharacter,
tertiaryCharacter,
mentor,
enemy,
villain,
rival,
shopkeeper,
healer,
questGiver,
innkeeper,
guard,
familyMember,
loveInterest,
scientist,
politician,
criminal,
explorer,
wizard,
ghost,
animalCompanion,
artificialIntelligence
Example:

"protagonist"

​
tone
enum<string>

The tone or style of the character's dialogue.

Available options:
formal,
casual,
sarcastic,
mysterious,
emotive
Example:

"mysterious"

​
traits
string[]

A list of personality traits describing the character.

Response

Character created successfully.

​
message
string

Confirmation message with character details.

Example:

"Character: character789 has been created with the following context."

​
character_id
string

UID of the character.

Example:

"character789"

​
character_context
object

The created character context.

Example:
{
  "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"]
}