Characters Service
Manage characters within a campaign, including their statistics, assets, notes, inventory, and supernatural abilities.
Usage
from vclient import characters_service
characters = characters_service(on_behalf_of="USER_ID", company_id="COMPANY_ID")
The on_behalf_of user ID is required and is sent on every request, including reads. The acting user's role determines what is visible.
Access control
Visibility of STORYTELLER characters depends on the acting user's role:
PLAYERandNPCcharacters are visible to every approved company member.STORYTELLERcharacters are visible only toSTORYTELLERandADMINroles. For aPLAYER:- List results omit
STORYTELLERcharacters (filtering withcharacter_type="STORYTELLER"returns an empty page). - Fetching a
STORYTELLERcharacter by ID, or any of its sub-resources (traits, inventory, notes, assets, statistics), raisesAuthorizationError(403). - Only
STORYTELLERandADMINroles maycreate()a character withtype="STORYTELLER"orupdate()an existing character'stypetoSTORYTELLER. APLAYERattempting either raisesAuthorizationError(403).
NPC management
NPC management is gated by the company's settings.permission_manage_npc setting (ManageNPCPermission):
UNRESTRICTED(default): any approved company member may manage NPC characters.STORYTELLER: onlySTORYTELLERandADMINroles may manage NPC characters. APLAYERattempting any of the following raisesAuthorizationError(403):- Creating an
NPCcharacter, or converting an existing character totype="NPC". - Updating or deleting an
NPCcharacter. - Adding, updating, or deleting an
NPCcharacter's traits or inventory items. - Uploading or deleting an
NPCcharacter's images.
Viewing an NPC character and rolling dice for an NPC are never affected by this setting; any approved member may always access those endpoints.
Player and creator assignment
The user_player_id and user_creator_id fields on Character are both nullable, and their values are constrained by character type:
PLAYERcharacters always have a non-nulluser_player_id.NPCandSTORYTELLERcharacters always haveuser_player_id = null.user_creator_idmay benullif the creating user was deleted.
Assignment rules are enforced server-side and surface as ValidationError (400):
- Creating a
PLAYERcharacter without auser_player_iddefaults it to the acting user. - Creating an
NPCorSTORYTELLERcharacter with a non-nulluser_player_idraisesValidationError(400). - Assigning a
user_player_idto an existingNPCorSTORYTELLERcharacter raisesValidationError(400). - Converting a
PLAYERcharacter toNPCorSTORYTELLERautomatically clearsuser_player_idtonull. No explicituser_player_id=Noneis required in the request. - Converting an
NPCorSTORYTELLERcharacter toPLAYERrequires auser_player_idin the sameupdate()call; omitting it raisesValidationError(400).
Methods
CRUD Operations
| Method | Returns | Description |
|---|---|---|
get(character_id) |
Character |
Get a character by ID |
create(CharacterCreate, **kwargs) |
Character |
Create a new character |
update(character_id, CharacterUpdate, **kwargs) |
Character |
Update a character |
delete(character_id) |
None |
Delete a character |
Pagination
| Method | Returns | Description |
|---|---|---|
get_page(limit?, offset?, campaign_id?, user_player_id?, character_class?, character_type?, status?, is_temporary?) |
PaginatedResponse[Character] |
Get a page of characters with optional filters |
list_all(...) |
list[Character] |
Get all characters (supports same filters) |
iter_all(limit?, ...) |
AsyncIterator[Character] |
Iterate through all characters |
Statistics
| Method | Returns | Description |
|---|---|---|
get_statistics(character_id, num_top_traits?) |
RollStatistics |
Get dice roll statistics |
Roll Analytics
Statistics include success rates, critical frequencies, and most-used traits. Use this data to understand how a character performs in gameplay.
Full Sheet
| Method | Returns | Description |
|---|---|---|
get_full_sheet(character_id, include_available_traits?) |
CharacterFullSheet |
Get hierarchical character sheet with all traits |
get_full_sheet_category(character_id, category_id, include_available_traits?) |
FullSheetTraitCategory |
Get a single category slice of the full sheet |
Sheet Structure
The full sheet returns all traits organized as sections > categories > subcategories > character traits. The skeleton includes all structures for the character's class and game version, even if empty. Use this to render a complete character sheet UI.
Available Traits
Set include_available_traits=True to populate the available_traits field on each category and subcategory with standard traits the character could add. When not set, these lists are always empty. Custom traits are excluded.
Assets
| Method | Returns | Description |
|---|---|---|
get_assets_page(character_id, limit?, offset?) |
PaginatedResponse[Asset] |
Get a page of assets |
list_all_assets(character_id) |
list[Asset] |
Get all assets |
iter_all_assets(character_id, limit?) |
AsyncIterator[Asset] |
Iterate through assets |
get_asset(character_id, asset_id) |
Asset |
Get an asset |
upload_asset(character_id, filename, content) |
Asset |
Upload an asset |
delete_asset(character_id, asset_id) |
None |
Delete an asset |
delete_asset raises NotFoundError when the asset belongs to a different character. Delete each asset through its own parent.
Notes
| Method | Returns | Description |
|---|---|---|
get_notes_page(character_id, limit?, offset?) |
PaginatedResponse[Note] |
Get a page of notes |
list_all_notes(character_id) |
list[Note] |
Get all notes |
iter_all_notes(character_id, limit?) |
AsyncIterator[Note] |
Iterate through notes |
get_note(character_id, note_id) |
Note |
Get a note |
create_note(character_id, NoteCreate, **kwargs) |
Note |
Create a note |
update_note(character_id, note_id, NoteUpdate, **kwargs) |
Note |
Update a note |
delete_note(character_id, note_id) |
None |
Delete a note |
Inventory
| Method | Returns | Description |
|---|---|---|
get_inventory_page(character_id, limit?, offset?) |
PaginatedResponse[InventoryItem] |
Get a page of inventory items |
list_all_inventory(character_id) |
list[InventoryItem] |
Get all inventory items |
iter_all_inventory(character_id, limit?) |
AsyncIterator[InventoryItem] |
Iterate through items |
get_inventory_item(character_id, item_id) |
InventoryItem |
Get an item |
create_inventory_item(character_id, InventoryItemCreate, **kwargs) |
InventoryItem |
Create an item |
update_inventory_item(character_id, item_id, InventoryItemUpdate, **kwargs) |
InventoryItem |
Update an item |
delete_inventory_item(character_id, item_id) |
None |
Delete an item |
Health
| Method | Returns | Description |
|---|---|---|
get_health(character_id) |
Health |
Get the character's health track |
set_health(character_id, HealthStateSet, **kwargs) |
Health |
Replace the full health state |
apply_health_action(character_id, action, amount?) |
Health |
Apply one in-play action |
Every character has a health track. The same object is on Character.health. Health is one damage count, Health.damage, from 0 to Health.size. There are no damage types, no dice penalties, and no health state. Players apply penalties to their own dice, and the Storyteller decides incapacitation and death. To record a death, set the character status.
| Game version | Track size | Health.levels |
|---|---|---|
| V4 | 7 levels plus extra_levels |
One HealthLevel per box, with name and marked |
| V5 | Stamina + 3, plus extra_levels |
None |
Use apply_health_action() with damage, heal, or reset during play. The server drops damage past a full track and healing past 0. Use set_health() to correct the full state. set_health() sends extra_levels and damage, so a field that you omit resets to 0. Each method returns the updated health, so you do not need to fetch it again.
The methods raise these errors:
NotFoundError(404): the character does not exist or has no health track.ValidationError(400): the action does not apply to health, ordamageis more than the track size.AuthorizationError(403): you are not the character's player or a storyteller.RequestValidationError: a value is negative,amountis less than 1, orset_health()receives a field other thanextra_levelsanddamage.
API version
The health endpoints need a Valentina API release later than v0.28.0. An older API returns 404, and Character.health is None. API v0.29.0 reports typed damage marks instead of one count, so Health.damage and HealthLevel.marked are None when the API is v0.29.0 or older.
from vclient.models import HealthStateSet
health = await characters.get_health(character.id)
# Take two damage
health = await characters.apply_health_action(character.id, "damage", amount=2)
print(f"{health.damage}/{health.size} damage")
# Correct the track to one damage, keeping its extra levels
health = await characters.set_health(
character.id,
HealthStateSet(damage=1, extra_levels=health.extra_levels),
)
Creating a character with starting state
CharacterCreate accepts the starting health damage and per-trait tracker state, so you can create a character who is already hurt:
from vclient.models import (
CharacterCreate,
CharacterCreateTraitAssign,
HealthStateSet,
TrackerStateSet,
)
request = CharacterCreate(
campaign_id="campaign_id",
character_class="VAMPIRE",
game_version="V4",
name_first="Marcus",
name_last="Blackwood",
health=HealthStateSet(damage=2),
traits=[
CharacterCreateTraitAssign(
trait_id=willpower_trait_id, value=6, tracker=TrackerStateSet(current=4)
),
],
)
character = await characters.create(request)
Character creation is atomic. If any part of the request fails, the server creates no character. create() raises ValidationError (400) in these cases:
- A trait has a
tracker, but the trait has no tracker for the character's game version. - A
trackerfield does not fit the tracker type, or a value is more than the tracker size. - The same
trait_idoccurs more than once intraits.
On V5, the server ignores a Willpower value in traits, because V5 Willpower equals Composure + Resolve. A tracker on V5 Willpower applies to that computed value.
Example
from datetime import date
from vclient.models import CharacterCreate, CharacterUpdate, InventoryItemCreate, NoteCreate
# Create a vampire character (preferred method: use model object)
request = CharacterCreate(
campaign_id="campaign_id",
character_class="VAMPIRE",
game_version="V5",
name_first="Marcus",
name_last="Blackwood",
date_of_birth=date(1888, 6, 15), # optional ISO 8601 calendar date
user_player_id="player_user_id",
)
character = await characters.create(request)
# Alternative: pass fields as keyword arguments
character = await characters.create(
campaign_id="campaign_id",
character_class="VAMPIRE",
game_version="V5",
name_first="Marcus",
name_last="Blackwood",
user_player_id="player_user_id",
)
# Update character details
update = CharacterUpdate(name_first="Marcus", name_last="Black")
updated = await characters.update(character.id, update)
# Clear the date of birth by passing None (omitting the field leaves it unchanged)
cleared = await characters.update(character.id, CharacterUpdate(date_of_birth=None))
# Retrieve roll statistics
stats = await characters.get_statistics(character.id)
print(f"Total rolls: {stats.total_rolls}")
print(f"Success rate: {stats.success_percentage}%")
# Add an inventory item
item_request = InventoryItemCreate(
name="Silver Dagger", type="weapon", description="An ornate blade"
)
item = await characters.create_inventory_item(character.id, item_request)
# Create a character note
note_request = NoteCreate(title="Background", content="Born in Victorian London...")
note = await characters.create_note(character.id, note_request)
See Response Models for Character and related types.