---
title: "Start a Series Bible episode as a draft."
method: POST
path: "/story-projects/{projectId}/episodes"
tags: ["Projects"]
---

# Start a Series Bible episode as a draft.

`POST /story-projects/{projectId}/episodes`

## Request

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

The Series Bible page's and project page's "Start", through their core: mints the planned episode's empty draft (titled, summarized, in its label's season, linked to the Bible entry), or returns the script that already covers it with `created: false` — never a second draft. Write into `scriptUploadId` scene by scene with POST /screenplay-drafts/{scriptUploadId}, or whole with PATCH /scripts/{scriptUploadId}/content, then finish it with POST /scripts/{scriptUploadId}/finish. Refused with 409 `project_precondition_failed` until the project can start an episode, and 400 for an episode no longer in the Bible. Free. Requires `Idempotency-Key`.

## Headers

- `Idempotency-Key` string, required

## Request body

- StartPlannedEpisodeRequest
  - `episodeId` string, required: The Series Bible episode's id: `plannedEpisodes[].episodeId` in the episode listing.

## Response `200`

The draft, or the script that already covers the episode.

- StartPlannedEpisodeResponse
  - `created` boolean, required: False when the episode was already written: the script that covers it comes back.
  - `script` WriterScript, required
    - `scriptId` string, required
    - `routeId` string, required: The id in its Writers Lab URL.
    - `projectId` string, nullable, required: Its project, or null for a script in no project.
    - `title` string, required: The stored title.
    - `label` string, required: The name the episode is listed by everywhere, e.g. "S1E1 — The Return": its season and number with its title (a leading project name and episode code taken off); a script in no project is its title. Display only.
    - `slug` string, nullable, required: Its URL slug.
    - `logline` string, nullable, required: The writer's one-sentence logline — the same one Slug and the Writers Lab read and write.
    - `mediaType` string, nullable, required: `film` or `tv`.
    - `genre` string, nullable, required: Free text, in the writer's words.
    - `seasonNumber` integer, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `workspacePath` string, required: Where it opens in the Writers Lab, relative to the site origin.
    - `versions` WriterScriptVersion[], required: Newest first.
      - `scriptUploadId` string, required: The version's id: what coverage, overrides, table reads and exports take.
      - `versionNumber` integer, required
      - `title` string, required
      - `status` string, required: `draft` while it is being written; otherwise a locked version.
      - `parseStatus` string, nullable, required: Where the screenplay parse stands (`queued`, `parsing`, `complete`, `failed`); null when none ran.
      - `slug` string, nullable, required
      - `wordCount` integer, required
      - `pageCount` integer, nullable, required
      - `format` string, required: How it was written: text, fountain or fdx.
      - `createdAt` string, date-time, required
      - `counts` object, required: How much has been made from this version.
        - `coverageReports` integer, required
        - `tableReadJobs` integer, required
        - `pitchDeckJobs` integer, required
        - `visualizerJobs` integer, required
  - `scriptUploadId` string, required: The draft to write into (for an episode already written, its latest version).

## 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 project has not reached the development stage this call needs (`project_precondition_failed`), and nothing was created, queued or charged. `details` is ProjectPreconditionDetails: `stage` names the stage to finish, `missingFields` what it still lacks, `canPlan` / `canStartEpisode` what the project can do now. Finish the named stage — do not retry; the identical call refuses the same way until it is done.
- `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)