Characters

Characters carry the Truby-style want / fear / lie axes that drive the chapter writer's sense of who the character is, plus optional aliases, role, bio, and voice profile. At least one isPov: true character is needed for multi-POV books.

List characters

GET /v1/books/{bookId}/characters
authorization: Bearer ant_live_…

→ 200 {
  "data": [
    {
      "id": "8b0c…",
      "name": "Marin",
      "aliases": ["the salt-keeper"],
      "role": "protagonist",
      "bio": "Lighthouse keeper, raised by her grandmother in Tide's Cove.",
      "voiceProfile": "Spare, water-bound, never apologetic.",
      "want": "to keep the village safe through one more storm",
      "fear": "becoming the version of her mother she swore she wouldn't",
      "lie": "love is something you earn by being useful",
      "isPov": true
    }
  ]
}

Create a character

POST /v1/books/{bookId}/characters
content-type: application/json
authorization: Bearer ant_live_…

{
  "name": "Selene",
  "role": "antagonist",
  "want": "to break the village's grip on the cove",
  "fear": "being forgotten",
  "lie": "control is the only love that doesn't decay",
  "isPov": false
}

Patch + delete one character

PATCH /v1/books/{bookId}/characters/{characterId}
content-type: application/json
authorization: Bearer ant_live_…

{
  "voiceProfile": "Clipped, generous with silence, never repeats herself."
}

DELETE /v1/books/{bookId}/characters/{characterId}
authorization: Bearer ant_live_…

→ 200 { "data": { "ok": true } }

Conflict edges that referenced the deleted character are cleaned up automatically.

Field reference

name — required, ≤ 120 chars.
aliases — up to 20 short alternate names.
role, bio, voiceProfile — free-form; bio + voiceProfile can run to 2000 chars.
want / fear / lie — one short clause each (≤ 240 chars). Setting any to null drops it from the chapter prompt.
isPov — true marks the character as a POV carrier.

From the MCP

list_characters, create_character, update_character, and delete_character are all available over the MCP server too. The conflict matrix is wrapped by list_character_conflicts, add_character_conflict, and remove_character_conflict.