---
title: "Add a blank chapter."
method: POST
path: "/pitch-decks/{jobId}/chapters/add"
tags: ["Pitch Deck"]
---

# Add a blank chapter.

`POST /pitch-decks/{jobId}/chapters/add`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/pitch-decks/{jobId}/chapters/add`
- Auth: HTTP bearer

Adds a new blank chapter: `atIndex` is the position it takes (0 = first — a position, not a key), `afterChapterIndex` puts it just after the chapter with that `chapterIndex` (its key from the chapters read), and omitting both appends it. NOT metered: it renders nothing — the new chapter has no footage until it is refined and rendered (`chapters/render-clip`, priced) — and every other chapter keeps its takes. A complete deck goes back to review. A draft plan, review or complete. On a draft plan nothing has rendered: the plan is renumbered (its black interludes follow their chapters) and the changed plan is queued for plan coverage again (`planCoverage`). Requires `Idempotency-Key`. Scope: `story:write`.

## Headers

- `Idempotency-Key` string, required

## Request body

- PitchDeckAddChapterRequest: Where the new blank chapter goes: `atIndex` or `afterChapterIndex` (not both); neither appends it.
  - `atIndex` integer: The POSITION the new chapter takes (0 = first) — a position, not a chapter key.
  - `afterChapterIndex` integer: Insert just after this chapter. 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`

Where the new chapter landed.

- PitchDeckAddChapterAck: Where the new blank chapter landed. Nothing was rendered and nothing was charged.
  - `success` boolean, required
  - `insertedChapterIndex` integer, required: The new chapter's key. The chapters are renumbered from 0 on insert, so it is chapter `insertedChapterIndex + 1` of the deck.
  - `chapterCount` integer, required
  - `planCoverage` 'queued' | 'current' | 'failed' | 'null', nullable: On a draft plan: the changed plan's plan coverage (`queued` for the latest edit, `current`, or `failed` — the approval says what is missing). 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 after the edit (a complete deck goes back to review when a chapter is added).

## 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/4534f5d25540?raw)