---
title: "Generate trailer plan coverage."
method: POST
path: "/trailers/{jobId}/storyboard/coverage"
tags: ["Trailer"]
---

# Generate trailer plan coverage.

`POST /trailers/{jobId}/storyboard/coverage`

## Request

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

Queues a pre-render report for the exact current beat plan. It grades the PLAN, never a rendered frame, so it spends no render credits and is the cheap step before the expensive one. Requires at least one planned beat. The gate is 7.0, and Series Bible consistency fails the report on its own whatever the other dimensions score. Requires `Idempotency-Key`. Scope: `story:write`.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `focusPrompt` string: Optional writer focus for this coverage pass.

## Response `200`

Queued trailer plan coverage envelope.

- object
  - `coverage` object, required
    - `status` 'missing' | 'queued' | 'generating' | 'complete' | 'failed', required: `queued`: the latest draft edit's coverage waits to start — it starts once the plan has been left alone for three minutes (a burst of edits is one run, on the revision it ends on), and the plan approval starts it at once. `generating`: scoring — including while the same revision is judged again near the bar (`judging.pending`), when the approval waits for the median. A run a later edit replaced is dropped, never stored, and never the status.
    - `planKind` 'pitch_deck' | 'trailer', required
    - `jobId` string, required
    - `current` boolean, required: The stored report graded the plan as it stands right now (a `queued` run is for the plan as it stands).
    - `stale` boolean, required: The plan changed after this report was produced.
    - `gatePassed` boolean, required: Complete, current, over threshold, and no veto dimension or blocking defect. A stale pass reads false.
    - `gateThreshold` number, required: The score this report had to clear (7.0 by default; a veto dimension below it fails the report whatever the overall score, because renders cost money).
    - `gateReasons` string[], required: Every reason the gate withheld a pass, in the order they were checked. Empty when it passed.
    - `reportId` string, nullable, required
    - `planRevision` integer, required: Fingerprint of the plan as it stands right now.
    - `reportedPlanRevision` integer, nullable, required: Fingerprint of the plan the stored report actually graded.
    - `reportVersion` integer, nullable, required
    - `rubricVersion` integer, nullable, required: The rubric version the report was graded with. A report graded under an older rubric than the current one cannot authorize a render.
    - `bibleVersion` integer, nullable, required: The Series Bible revision the report was graded against, when the project has one.
    - `exemplarIds` string[], required: Ids of the benchmark exemplars the report was calibrated against; empty when the surface has no corpus.
    - `gateNotes` string[], required: Vetoes that were suppressed by policy, surfaced beside the reasons and never merged into them — the finding a reader most often wants when a gate passed narrowly.
    - `heldBy` union[], required: What holds the plan beside its overall score, structured: each dimension that fails the plan on its own and sits under the bar (a story check such as `buildup`; `score` null when the judge gave it no usable score), then each blocking plan defect. Empty on a pass and on a report that does not describe the plan as it stands. A plan whose overall clears the bar is still held by any of these: say "7.6 overall, but Buildup scored 6.5, below the 7.0 bar", never that 7.6 is below the bar.
      - union
        - object
          - `kind` 'dimension', required
          - `dimension` string, required
          - `label` string, required: The dimension as the app names it, e.g. "Buildup".
          - `score` number, nullable, required
        - object
          - `kind` 'defect', required
          - `code` string, required
          - `detail` string, required
    - `overallScore` number, nullable, required
    - `progressDetail` string, nullable, required
    - `failureMessage` string, nullable, required
    - `report` object, nullable, required: The graded report (rubric v13): overallScore, verdict, oneLineDiagnosis, canonSummary, showSold, opening (the judge's note on the deck's opening title sequence: present, whatItSays, servesIntent, nextMove; null on a report judged before it existed), the twenty scored dimensions — first the four that judge the plan against its intent and veto in every mode (intentClarity, centralQuestion, buildup, themeCarried), then subtext (does the plan pose its question rather than recite its plot; a veto in every mode), transitions (does every part follow the one before it for a reason a first-time viewer can feel; a veto in every mode) and voices (do the characters speak, rather than the narrator carrying everything), then sequenceArchitecture, storyThroughLine, seriesRepresentation, emotionalArchitecture, narrativeVoice, promiseControl, beatDistinctness, characterIntroduction, seriesBibleConsistency, referenceCompleteness, motionDirection, shotLadderLegibility, continuity — exemplarComparisons, emotionalJourney, narrationThroughline, beatNotes, characterNotes, weakTransitions (the weakest cuts, worst first: toBeatIndex — the unit the cut goes into — problem and fix), strengths, risks, priorityFixes, and viewerTakeaway: what a first-time viewer takes away from the plan (aboutTheShow, centralQuestion, whereItBuilds, toldVersusShown — how much of it was told in words rather than shown — and lostTheThread — where they could not tell why one part came after the last), written BEFORE the judge was shown the intent.
      - `viewerTakeaway` VideoViewerTakeaway: 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: 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."
    - `judgingIncomplete` object, nullable, required: A revision near the bar whose median could not be completed: the further judgments it needed could not run, even queued again. The report is `failed` and is NEITHER a pass nor a veto ("Plan coverage couldn't finish judging — Score again"); `judging` lists the judgments that ran, with `stoppedBecause: judging_incomplete`. Score the plan again. Null otherwise.
      - `judgments` integer, required: The judgments that did run (their scores are on `judging`).
      - `maxJudgments` integer, required: The most judgments one revision takes.
    - `judging` StoryboardCoverageJudging, required: HOW A PLAN COVERAGE VERDICT WAS REACHED. One judgment is too noisy to gate a paid render on near the bar (near-identical plans have scored 6.2 and 7.4), so a revision whose first judgment lands within `nearGateBand` of a gating line — the composed overall against the bar, or a veto dimension against its veto line — is judged again: the SAME revision, up to `maxJudgments`, a third only when two disagree. The gate reads the MEDIAN of each score, vetoes included. A plan edit starts a fresh set. Every judgment is free to the writer. The band, the cap and the spend cap are the `storyboard_coverage_judging` site setting.
      - `pending` boolean, required: True while another judgment of this revision is queued or running: the gate has not decided yet (the approval waits).
      - `planRevision` integer, nullable, required: The plan revision (fingerprint) every judgment scored.
      - `judgments` StoryboardCoverageJudgment[], required
        - `judgment` integer, required: 1, 2, 3 — in the order taken.
        - `reason` 'first' | 'near_bar' | 'disagreement', required: `first`; `near_bar`: the first sat within the band of a gating line; `disagreement`: two sat on opposite sides of a line, so a third breaks the tie.
        - `model` string, required
        - `judgedAt` string, date-time, required
        - `overallScore` number, nullable, required: The judge's own overall on this judgment.
        - `composedScore` number, nullable, required: The score the gate reads for this judgment alone: the lower of its overall and its weighted dimensions.
        - `gatePassed` boolean, required: Whether this judgment alone cleared the gate.
        - `dimensions` object, required: Each rubric dimension as this judgment scored it.
        - `costUsd` number, required: What this judgment cost us (USD) — never the writer.
        - `priced` boolean, required: False when the model has no price on file and `costUsd` is the flat per-judgment estimate.
        - `prompts` object, nullable, required: Which prompt text this judgment ran on: the first 16 hex characters of the sha256 of the judge's exact system text (the rubric, then the showcase rubric for a showcase deck) and of the blind first-time viewer's rubric. Null on a judgment recorded before these were kept.
          - `judge` string, required
          - `viewerTakeaway` string, required
      - `overall` StoryboardCoverageScoreDistribution, required: One plan-coverage score across the judgments of a revision.
        - `scores` number[], required: The readable scores, in judgment order.
        - `median` number, nullable, required: Their median (an even count: the mean of the middle two) — the number the gate reads. Null when none could be read.
      - `dimensions` object, required: Each rubric dimension across the judgments; the report's dimension scores are these medians.
      - `medianScore` number, nullable, required: The score the gate read: the composed score of the median report (null while pending).
      - `decidedOnMedian` boolean, required: True when the gate read the median of more than one judgment.
      - `stoppedBecause` 'decisive' | 'agreement' | 'max_judgments' | 'spend_cap' | 'judging_incomplete' | 'judgment_failed' | 'null', nullable, required: `decisive`: one judgment clear of every line by the band (or a blocking defect, or an unreadable score); `agreement`: two on the same side of every line; `max_judgments`; `spend_cap`; `judging_incomplete`: another was wanted near the bar and could not run even queued again, so nothing was decided (the report is `failed`, neither a pass nor a veto: score again); `judgment_failed`: written before `judging_incomplete`: another could not run, so the recorded ones decided. Null while pending.
      - `nearGateBand` number, required: Within this many points of a gating line, one judgment is not trusted on its own.
      - `maxJudgments` integer, required: The most judgments one revision takes.
      - `extraSpendUsd` number, required: What the judgments beyond the first cost us (USD).
      - `extraSpendCapUsd` number, required: The most the judgments beyond the first may cost for one revision (USD).
    - `defects` object[], required: Plan defects decided in code, not by a model. `blocking` ones fail the gate on their own; `advisory` ones are evidence handed to the rubric.
      - `code` 'missing_motion_direction' | 'missing_shot_type' | 'missing_location' | 'shot_ladder_collapsed' | 'shot_ladder_duplicate_framing' | 'location_flip_flop' | 'missing_character_reference' | 'missing_location_plate' | 'character_never_featured' | 'opens_on_arrival' | 'ends_on_exit' | 'cut_ladder_no_range' | 'promised_never_shown' | 'canon_lead_absent' | 'canon_lead_never_subject' | 'canon_character_not_castable' | 'approved_beat_dropped_silently' | 'video_intent_missing' | 'arc_stage_missing' | 'question_not_advanced' | 'arc_out_of_order' | 'arc_stage_unserved' | 'ending_off_question' | 'transition_unexplained' | 'characters_never_speak' | 'character_lines_under_share' | 'story_film_product_carries_feeling' | 'story_film_feature_name_spoken' | 'story_film_product_beats_stacked', required
      - `severity` 'blocking' | 'advisory', required
      - `beatIndexes` integer[], required
      - `subject` string, required
      - `detail` string, required
    - `gateOverride` object, required: Whether a failed gate may be rendered over on the writer's word (`acknowledgePlanCoverage` on the plan approval). Allowed ONLY when a complete report of the plan as it stands, scored on the current rubric, failed on the judge's scores alone (the overall score, or a judged veto dimension, under the bar); never over a blocking defect decided in code, and never for a missing, queued, running, failed, stale or old-rubric report. `why` says which, in the writer's terms.
      - `allowed` boolean, required
      - `why` string, required
    - `writerOverride` PlanCoverageOverride, required: A render over a failed plan gate on the writer's word: the report it overrode, the plan revision it graded, its score, the bar, and the reasons it gave. A recorded override (on the confirmed approval and on the coverage read) also carries `at` and `by`.
      - `reason` string, required
      - `reportId` string, required
      - `planRevision` integer, required
      - `overallScore` number, nullable, required
      - `gateThreshold` number, required
      - `gateReasons` string[], required
      - `at` string, date-time: Recorded overrides only: when the confirmed approval recorded it.
      - `by` object: Recorded overrides only: who approved it — `api` (the Story API: MCP and the CLI) with the API key or `oauth:…` connection, or `app` (the Writers Lab).
        - `userId` string, required
        - `surface` 'api' | 'app', required
        - `keyId` string, nullable, required
    - `createdAt` string, date-time, nullable, required
    - `updatedAt` string, date-time, nullable, required

## Other responses

- `400`: Request payload failed validation. The error message names the offending field.
- `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)