---
title: "Read the project cast canon (pinned portrait, body, and character-sheet assets)."
method: GET
path: "/story-projects/{projectId}/cast-canon"
tags: ["Projects"]
---

# Read the project cast canon (pinned portrait, body, and character-sheet assets).

`GET /story-projects/{projectId}/cast-canon`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/story-projects/{projectId}/cast-canon`
- Auth: HTTP bearer

Owner-pinned character assets every episode of the project inherits at creation, with each person's aliases, voice and signature items. Project-wide visual direction lives in the Series Bible. A project with no canon returns an empty document. `identity` warns when one name reaches two people or two people share a body figure, lists characters with no Series Bible appearance, and lists Series Bible names no canon person answers to (`unresolvedBibleNames`, e.g. "Foma Stepanovich" beside FOMA, with the people each probably is; add the Bible name to that person's `aliases`); it is read-only.

## Response `200`

Cast canon envelope.

- CastCanonEnvelope
  - `identity` CastIdentityReport, required: Identity warnings on a cast read. Read-only: nothing is merged, generated or charged.
    - `duplicates` object[], required: One name that reaches two or more canon people (a key two people claim, or a person with no name of their own beside another, like FYODOR beside Fyodor Karamazov), or two people sharing one body figure. Fix it by keeping one person and listing the other names as aliases.
      - `kind` 'one_character_two_people' | 'shared_figure', required
      - `character` string, nullable, required: The name that reaches more than one person; null for a shared figure.
      - `people` string[], required: The people involved, by display name.
      - `figureUrl` string, nullable, required: The shared body figure; null for one_character_two_people.
      - `message` string, required
    - `noBibleAppearance` object[], required: Characters with no appearance or wardrobe in the Series Bible: a video would describe them by name only.
      - `character` string, required
      - `message` string, required
    - `unresolvedBibleNames` object[], required: Series Bible names that no cast canon person answers to by name or alias ("Foma Stepanovich" beside the canon's FOMA), each with the canon people it probably is. A voice or body shot asked for under the Bible name is not found. Fix it by adding the Bible name to that person's `aliases` on the cast canon; nothing is resolved automatically.
      - `bibleName` string, required: The Series Bible's name for the character.
      - `candidates` string[], required: Canon people (display names) one of whose names is wholly contained in the Bible name.
      - `message` string, required
  - `canon` object, required
    - `projectId` string, required
    - `content` CastCanonContent, required
      - `characters` CastCanonCharacter[]
        - `name` string, required: The name a human reads ("Ivan Karamazov"). A save naming a person by any of their names or aliases updates that person.
        - `aliases` string[]: Every other name this person answers to, the script cue included ("IVAN"). Declaring the cue here is what makes a script character and a canon person one identity; the cast read warns when one name reaches two people.
        - `id` string: Stable identity assigned on save. Send it with a new `name` to rename a person instead of creating a stranger.
        - `avatarUrl` string: Canonical portrait; https only. Seeded before generation, so the pipeline never renders a replacement.
        - `avatarPrompt` string
        - `bodyFigureUrl` string: Canonical full-body figure; https only.
        - `characterSheetUrl` string: Canonical turnaround/model sheet; https only.
        - `voiceId` string: The pinned voice every episode and every video uses for this person.
        - `voiceName` string
        - `voiceProvider` string
        - `voiceGender` string
        - `signatureItems` string[]: What only this person wears or carries ("round wire spectacles"), at most 8 items of at most 120 characters. A video with two or more people states who owns each item, so it cannot move onto another person; such a video needs signature items for every person in it. The list you send replaces the saved one; an empty list clears it.
        - `lookDirection` string: How this person should look on camera, in the writer's words ("22, a merchant's kept woman, striking but not modern, natural skin, period dress"). Every headshot, portrait candidate, body shot and sheet drawn for them reads it, and it outranks the Series Bible's appearance. `PATCH /story-projects/{projectId}/cast-look` sets or clears it alone.
        - `age` string: The age this person is played at ("22"), outranking the Series Bible and an episode roster.
    - `currentVersion` integer, required
    - `updatedAt` string, date-time, required

## Other responses

- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `404`: The named project or source does not exist or is owned by another account.
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/4534f5d25540?raw)