--- title: "Put the chapters in a new order." method: POST path: "/pitch-decks/{jobId}/chapters/reorder" tags: ["Pitch Deck"] --- # Put the chapters in a new order. `POST /pitch-decks/{jobId}/chapters/reorder` ## Request - Base URL: `https://docs.sleeperhit.studio/api/v1` - URL: `https://docs.sleeperhit.studio/api/v1/pitch-decks/{jobId}/chapters/reorder` - Auth: HTTP bearer Puts the deck's chapters in a new order: `order` names every chapter's chapterIndex once, in the order they will play, or `move` puts one chapter just after another (`afterChapterIndex`) or first (`afterChapterIndex: null`). Free: nothing renders and every chapter keeps its takes; a rendered deck's video is stitched again in the new order. Chapters filmed in one render (a scene group: a chapter whose `renderedWith` names another, and that chapter) move as one block, side by side in their order; an order that pulls them apart is refused (`pitch_deck_scene_group_split`) and a move of one of them moves the whole group. The chapters are renumbered from 0 in their new order (each answer chapter's `previousChapterIndex` is its key before). How a chapter hands into the next and the black after it travel with it (a black whose chapter now ends the deck is taken out and named in `droppedInterludes`); music and sound laid on one chapter move with it, and a score composed to the old order keeps playing but no longer lands on the chapters (`score: no_longer_fits`) until it is scored again, priced. A draft plan, review or complete; on a draft the changed plan is queued for plan coverage again (`planCoverage`). A rendered deck waits while its video is being put together or its automatic fixes are running (409 `pitch_deck_reorder_assembly_running`, `pitch_deck_reorder_auto_fix_running`). A scene group pulled apart is refused with 409 `pitch_deck_state_invalid` (`details.refusal.code: pitch_deck_scene_group_split`), as is a rendered deck whose video is being put together (`pitch_deck_reorder_assembly_running`) or whose automatic fixes are reviewing or fixing it (`pitch_deck_reorder_auto_fix_running`); nothing changes. An order that does not name every chapter once is a 400. NOT metered and NOT confirmed. Requires `Idempotency-Key`. Scope: `story:write`. ## Headers - `Idempotency-Key` string, required ## Request body - PitchDeckReorderChaptersRequest: The new order: `order` (every chapter once) or one `move` — exactly one of them. - `order` integer[]: Every chapter's chapterIndex once, in the order they will play. The chapter's `chapterIndex`, exactly as the chapters read returns it: a key, not a position — a plan may key its chapters from 0 or from 1. A person's "chapter 2" is the chapter whose `chapterNumber` is 2; pass that chapter's `chapterIndex`. - `move` object: One chapter (with the scene group it belongs to) put just after another chapter, or first. - `chapterIndex` integer, required: The chapter to move. The chapter's `chapterIndex`, exactly as the chapters read returns it: a key, not a position — a plan may key its chapters from 0 or from 1. A person's "chapter 2" is the chapter whose `chapterNumber` is 2; pass that chapter's `chapterIndex`. - `afterChapterIndex` integer, nullable, required: The chapter it lands just after, or null to move it first. The chapter's `chapterIndex`, exactly as the chapters read returns it: a key, not a position — a plan may key its chapters from 0 or from 1. A person's "chapter 2" is the chapter whose `chapterNumber` is 2; pass that chapter's `chapterIndex`. ## Response `200` The chapters in their new order, and what the move did to the cut. - PitchDeckReorderChaptersAck: The chapters in their new order. Nothing was rendered and nothing was charged. - `success` boolean, required - `moved` boolean, required: False when the deck was already in that order: nothing was saved and nothing is stitched. - `chapterCount` integer, required - `chapters` object[], required: Every chapter in its new order, renumbered from 0. - `chapterIndex` integer, required: Its key now. - `chapterNumber` integer, required: Its place in the deck, from 1. - `title` string, required - `previousChapterIndex` integer, required: Its key before the move. - `restitching` boolean, required: A rendered deck that moved: its video is stitched again in the new order (free; nothing renders). - `droppedInterludes` object[], required: Blacks taken out because their chapter now ends the deck (a black only sits between two chapters). - `afterChapterNumber` integer, required: The number its chapter had before the move. - `line` string, nullable, required: The line heard over it, if it had one. - `score` 'no_longer_fits' | 'null', nullable, required: `no_longer_fits` when a score composed to the cut is laid: it still plays under the whole deck but no longer lands on the chapters until it is scored again (priced). - `bellLane` boolean, required: The deck has a bell lane: it still strikes the title sequence's beat, laid again with the new order (free). - `message` string, required: What happened, in one sentence to show the writer. - `planCoverage` 'queued' | 'current' | 'failed' | 'null', nullable: On a draft plan: the changed plan's plan coverage (`queued` for the latest edit). Null in review or complete. - `edited` 'draft_plan' | 'rendered_deck': Which version of the deck the edit changed: `draft_plan` (a `draft` deck — nothing has rendered) or `rendered_deck` (a deck in review or complete). Tell the writer which one changed. - `jobId` string: The deck that changed. - `status` 'draft' | 'review' | 'complete': The deck's status, unchanged by a reorder. ## 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. - `409`: The pitch deck exists and the request is well-formed, but the deck, its chapter, its cast or its plates are not in a state that allows it (`pitch_deck_state_invalid`), and nothing was reserved: a plan approved outside draft, a take chosen, a chapter edited or rendered outside review/complete, an export before the finish, a finish while a call has no selected take or a footage chapter has not rendered, a text-only chapter asked for footage, a changed chapter asked for one call, a delivery class changed mid-pass, a render the compile blocked, or a finish while the master failed its video coverage (`pitch_deck_video_coverage_failed`, with `details.videoCoverage`). `details.refusal` is `{ code, action, fix }` (see PitchDeckRefusalDetails): `action` is what unblocks it — `recast_figure`, `add_signature_items`, `recast_voice` or `remake_location_plate` — and `fix` names the MCP tool and CLI command that take it; `details.blocked[]` lists every chapter a blocked compile could not render. The identical request succeeds once the deck is put right. - `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/86e084144cef?raw)