---
title: "Start or resume scene-by-scene screenplay drafting."
method: POST
path: "/screenplay-drafts/{scriptUploadId}"
tags: ["Jobs"]
---

# Start or resume scene-by-scene screenplay drafting.

`POST /screenplay-drafts/{scriptUploadId}`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/screenplay-drafts/{scriptUploadId}`
- Auth: HTTP bearer

With `{ scenes, throughAct? }`, queues an ordered, act-ordered scene plan against an EMPTY editable draft once project setup is approved (until then — and for a script in no project — 409 `project_precondition_failed` names the stage to finish; a script in a product project is refused with 409 `project_not_story`); use `throughAct` to write Act 1 first. With `{ action: "resume" }`, continues from the next unfinished scene (also the way to write the remaining acts), preserving the writer's current draft edits. Each completed scene is saved as it lands. Requires `Idempotency-Key`.

## Headers

- `Idempotency-Key` string, required

## Request body

- union
  - object
    - `scenes` object[], required
      - `act` integer, required
      - `heading` string, required: Scene heading starting INT., EXT., INT./EXT. or I/E.
      - `direction` string, required
      - `pages` number, required
    - `throughAct` integer
  - object
    - `action` 'resume', required

## Response `200`

Screenplay drafting status after queueing.

- ScreenplayDraftStatus, nullable
  - `id` string, required
  - `status` string, required: queued, writing, interrupted (a writing lease expired), awaiting_continue (an act-first draft finished its act), paused (the screenplay changed under it), reviewing (every scene written), failed, or complete. For code: show people `nextStep`.
  - `nextStep` string, required: The draft's state in one plain sentence, the same words the editor shows, naming the writer's move when there is one: "Writing scene 4 of 12.", "Waiting to continue: Act 1 is written. Continue the episode to write Act 2.", "Draft saved. Coverage 8.2/10. Finalize the draft to cast it and start its Table Read."
  - `completedScenes` integer, required
  - `totalScenes` integer, required
  - `act` integer, required
  - `totalActs` integer, required
  - `error` string, nullable
  - `content` string, required: The saved Fountain screenplay so far.
  - `updatedAt` string, date-time, required
  - `coverage` object, nullable: Screenplay coverage started when drafting completed; null until then.
    - `id` string
    - `status` string
    - `progressDetail` string, nullable
    - `overallScore` number, nullable
    - `errorMessage` string, nullable

## 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/86e084144cef?raw)