---
title: "Read the trailer's intent and what a first-time viewer takes away."
method: GET
path: "/trailers/{jobId}/intent"
tags: ["Trailer"]
---

# Read the trailer's intent and what a first-time viewer takes away.

`GET /trailers/{jobId}/intent`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/trailers/{jobId}/intent`
- Auth: HTTP bearer

Returns the trailer's intent, each beat's arc stage and how it advances the central question, where the beats break the arc, and what plan coverage says: the first-time-viewer takeaway it wrote before seeing the intent, and the story checks. Every deck and trailer is planned from an explicit intent — what the video is for, its logline, theme, central question, stakes, what a first-time viewer is promised, a four-stage arc (setup, escalation, turn, closing question) and how the ending lands the question. Every chapter or beat names the arc stage it serves (`arcStage`), how it advances the central question (`advancesQuestion`) and, after the first, why it follows the one before it (`whyItFollows`: the visible link — a cause, an answer, a contrast, a match cut, a look, an object, a sound — and what it moves forward; one line, never shown on screen). Plan coverage first writes what a first-time viewer would take away from the plan without seeing the intent (`viewerTakeaway`, with how much of the story the words recited rather than let them work out: `toldVersusShown`, and where they lost the thread: `lostTheThread`), then compares it with the intent: intent clarity, the central question, the buildup and whether the theme is carried each fail the plan on their own, and so do subtext — a plan that recites its plot instead of posing its question — and transitions — a part that follows the one before it for no reason a first-time viewer can feel (`weakTransitions` names the weakest, each with its fix); voices (do the characters speak, rather than the narrator carrying everything) is scored beside them. A read. Scope: `story:read`.

## Response `200`

The intent beside what the plan says.

- VideoIntent: A deck's or trailer's intent beside what its plan says. Every deck and trailer is planned from an explicit intent — what the video is for, its logline, theme, central question, stakes, what a first-time viewer is promised, a four-stage arc (setup, escalation, turn, closing question) and how the ending lands the question. Every chapter or beat names the arc stage it serves (`arcStage`), how it advances the central question (`advancesQuestion`) and, after the first, why it follows the one before it (`whyItFollows`: the visible link — a cause, an answer, a contrast, a match cut, a look, an object, a sound — and what it moves forward; one line, never shown on screen). Plan coverage first writes what a first-time viewer would take away from the plan without seeing the intent (`viewerTakeaway`, with how much of the story the words recited rather than let them work out: `toldVersusShown`, and where they lost the thread: `lostTheThread`), then compares it with the intent: intent clarity, the central question, the buildup and whether the theme is carried each fail the plan on their own, and so do subtext — a plan that recites its plot instead of posing its question — and transitions — a part that follows the one before it for no reason a first-time viewer can feel (`weakTransitions` names the weakest, each with its fix); voices (do the characters speak, rather than the narrator carrying everything) is scored beside them.
  - `planKind` 'pitch_deck' | 'trailer', required
  - `jobId` string, required
  - `deckMode` 'pitch' | 'showcase' | 'null', nullable, required: A deck's mode (`pitch` or `showcase`); null for a trailer.
  - `status` string, required
  - `editable` boolean, required: Whether the intent can be edited now: only while the plan is a draft (approving the plan approves its intent).
  - `intent` VideoStoryIntent, required: What a deck or trailer is FOR. Every deck and trailer is planned from an explicit intent — what the video is for, its logline, theme, central question, stakes, what a first-time viewer is promised, a four-stage arc (setup, escalation, turn, closing question) and how the ending lands the question. Every chapter or beat names the arc stage it serves (`arcStage`), how it advances the central question (`advancesQuestion`) and, after the first, why it follows the one before it (`whyItFollows`: the visible link — a cause, an answer, a contrast, a match cut, a look, an object, a sound — and what it moves forward; one line, never shown on screen). Plan coverage first writes what a first-time viewer would take away from the plan without seeing the intent (`viewerTakeaway`, with how much of the story the words recited rather than let them work out: `toldVersusShown`, and where they lost the thread: `lostTheThread`), then compares it with the intent: intent clarity, the central question, the buildup and whether the theme is carried each fail the plan on their own, and so do subtext — a plan that recites its plot instead of posing its question — and transitions — a part that follows the one before it for no reason a first-time viewer can feel (`weakTransitions` names the weakest, each with its fix); voices (do the characters speak, rather than the narrator carrying everything) is scored beside them.
    - `purpose` string, required: What this video is for: a pitch sells the series, a showcase shows the world AS the story, a trailer hooks the episode.
    - `audience` string: Who it is for (a pitch's buyer, a trailer's audience). Optional.
    - `logline` string, required: What this show is about, in one sentence.
    - `theme` string, required: What it is really about underneath.
    - `centralQuestion` string, required: The dramatic question the video poses and leaves open.
    - `stakes` string, required: What is at risk, and for whom.
    - `viewerPromise` string, required: What a first-time viewer should feel and want by the end.
    - `arc` VideoIntentArcEntry[], required: The four stages, in order: setup, escalation, turn, closing_question.
      - `stage` 'setup' | 'escalation' | 'turn' | 'closing_question', required: Which stage: the arc is exactly setup, escalation, turn, closing_question, in that order.
      - `purpose` string, required: What this stage does for a first-time viewer.
      - `temperature` string, required: The emotional temperature, in words.
      - `intensity` integer, required: The same temperature on a 1–10 scale. It rises to the turn: the escalation runs hotter than the setup, and the turn is the peak of the first three (the closing question may fall quiet).
    - `ending` string, required: How the final moment lands the central question — posed, sharpened, and left open.
  - `units` object[], required: Each chapter (deck) or beat (trailer), in cut order, with the arc stage it serves, how it advances the central question and why it follows the one before it.
    - `key` integer, required: The unit's key: a deck chapter's `chapterIndex`, a trailer beat's `beatIndex` — what the refine takes.
    - `number` integer, required: Its place in the cut, from 1.
    - `title` string, required
    - `arcStage` 'setup' | 'escalation' | 'turn' | 'closing_question' | 'null', nullable, required
    - `advancesQuestion` string, nullable, required
    - `whyItFollows` string, nullable, required: Why it follows the unit before it (the visible link, and what it moves forward); null when the plan says none.
  - `arcProblems` VideoIntentArcProblem[], required: Where the units break the intent's arc (empty when they follow it, or when the plan has no intent).
    - `code` 'arc_stage_missing' | 'question_not_advanced' | 'transition_unexplained' | 'arc_out_of_order' | 'arc_stage_unserved' | 'ending_off_question', required
    - `units` integer[], required: The 1-based places in the cut the problem is about (empty for a whole-plan problem).
    - `stage` 'setup' | 'escalation' | 'turn' | 'closing_question': The arc stage it is about, when it is about one.
    - `detail` string, required: The problem and its fix, in one sentence.
  - `coverage` object, required: What plan coverage says about the plan against its intent.
    - `status` 'missing' | 'queued' | 'generating' | 'complete' | 'failed', required
    - `current` boolean, required: The report graded the plan as it stands now.
    - `gatePassed` boolean, required
    - `gateThreshold` number, required
    - `viewerTakeaway` VideoViewerTakeaway, required: What a first-time viewer takes away from the plan, written by plan coverage BEFORE it was shown the intent — the read the story checks compare with the intent.
      - `aboutTheShow` string, required: What the show is about, as a stranger would say it after one viewing.
      - `centralQuestion` string, required: The question the stranger is left holding, or a plain statement that none is posed.
      - `whereItBuilds` string, required: Where the cut builds: where tension rises, peaks, and plateaus or falls back.
      - `toldVersusShown` object, required: How much of the story the stranger was TOLD in words rather than SHOWN — what `subtext` is judged against.
        - `verdict` 'mostly_told' | 'balanced' | 'mostly_shown', required: `mostly_told` (the words recited the story), `balanced`, or `mostly_shown` (worked out from images, the characters' own lines and juxtaposition).
        - `told` string, required: The story facts the cut put into words that the pictures or the characters could have carried, quoted.
        - `shown` string, required: What the stranger worked out for themselves.
      - `lostTheThread` string: Each cut where the stranger could not tell why a part came after the one before it, by name, or "I never lost it" — what `transitions` is judged against. Empty on a read written before it was asked for.
    - `opening` StoryboardCoverageOpening, required: The report's `opening` is the judge's note on the deck's title sequence, written before it scores anything: `whatItSays` (what the epigraph, the source credit, the flash cuts and the title tell a stranger before the first chapter), `servesIntent` (whether it poses the intent's question and names the people that question is about, and whether the cut pays it off) and `nextMove`; `present` is false for a cut that opens on its first unit (every trailer), and `opening` is null on a report judged before the section existed. It is not scored on its own — it counts in intent clarity.
      - `present` boolean, required: Whether the cut opens on a title sequence before its first unit.
      - `whatItSays` string, required: What the opening tells a stranger before the first unit: the epigraph and its source, the credit, whom the flash cuts go to in order (and who is in shadow), the title. Empty when `present` is false.
      - `servesIntent` string, required: Whether it serves the intent: the question it poses, whether the people it names are the people that question is about, whether the cut pays it off. Empty when `present` is false.
      - `nextMove` string, required: The one change that would make the opening serve the intent better, or "None required."
    - `storyVetoes` object[], required: The story checks: the vetoes (intentClarity, centralQuestion, buildup, themeCarried, subtext, transitions), each of which fails the plan on its own in every mode, then voices (do the characters speak), scored and not a veto.
      - `dimension` 'intentClarity' | 'centralQuestion' | 'buildup' | 'themeCarried' | 'subtext' | 'transitions' | 'voices', required
      - `label` string, required
      - `veto` boolean, required: Whether a score under the gate fails the plan on its own (every check but voices).
      - `score` number, nullable, required
      - `finding` string, nullable, required
      - `passed` boolean, nullable, required: Whether it clears the gate on its own; null while no current report exists.
    - `weakTransitions` object[], required: The weakest cuts plan coverage named, worst first, each with its fix (empty until a current report names one).
      - `toKey` integer, required: The key of the unit the cut goes into — what the refine takes.
      - `toNumber` integer, required
      - `fromKey` integer, required
      - `fromNumber` integer, required
      - `problem` string, required: Why a first-time viewer would not know why this part follows the one before it.
      - `fix` string, required: The link to give it (a look, an object, a sound, a cause, a contrast) or the reorder.
    - `failingChapters` object[], required: The failing chapters (a deck) or beats (a trailer) the plan-coverage gate names — one entry per unit, each with the block text every surface prints (the same words as the gate refusal). Empty until a current report names one.
      - `number` integer, required: The unit's 1-based place in the cut — the way the run's prose names it ("chapter 3").
      - `title` string, nullable, required: The unit's own label — the plan's unit title, else the run's own beat note's label — else null.
      - `dimensions` object[], required: The dimensions the stored run ties to this unit (each held under the gate), each with the run's own words that tie it there.
        - `label` string, required: The held dimension's own label ("Buildup").
        - `score` number, nullable, required: Its score as the stored run holds it; null when the run gave it no usable score.
        - `because` string, required: The run's stored words tying the dimension to the unit, quoted — never a claim they do not make.
      - `notes` object[], required: The run's per-beat notes on this unit, in the order it wrote them.
        - `score` number, nullable, required
        - `finding` string, required
        - `nextMove` string, required
      - `weakCuts` object[], required: The weak cuts the run names into or after this unit, with their fixes.
        - `side` 'into' | 'after', required
        - `problem` string, required
        - `fix` string, required
      - `text` string, required: This unit's block, as every surface prints it.

## 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/64c1102ccb2f?raw)