---
title: "Upload a new version of a script."
method: POST
path: "/scripts/{scriptUploadId}/versions"
tags: ["Scripts"]
---

# Upload a new version of a script.

`POST /scripts/{scriptUploadId}/versions`

## Request

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

The Writers Lab's "upload a new version", through its core: the next version number, parsed and analysed in the background, with the previous version's episode overrides copied forward. Earlier versions are kept. A new version can come from a file (a PDF, a Final Draft .fdx, or a Fountain or plain-text script) instead of its text. The file is read as a source of the script's project: `fileUrl` (a link to the file) adds it and answers `waiting` with its `sourceId`; check that source until it is READY, then send `sourceId` and its text becomes the new version. A source that is already READY becomes the version at once, and the same source makes its version once (sending it again answers that version). A script in no project has nowhere to keep the file: send its text instead. A source that could not be read is refused (400) with its reason. Refused with 403 `plan_limit_reached` on the free plan (one version per script) or past the page allowance; 404 `script_not_found` for a script that is not yours, `source_not_found` for a source that is not. Free. Requires `Idempotency-Key`.

## Headers

- `Idempotency-Key` string, required

## Request body

- ScriptVersionUploadRequest: Exactly one of `content`, `sourceId` and `fileUrl`. A new version can come from a file (a PDF, a Final Draft .fdx, or a Fountain or plain-text script) instead of its text. The file is read as a source of the script's project: `fileUrl` (a link to the file) adds it and answers `waiting` with its `sourceId`; check that source until it is READY, then send `sourceId` and its text becomes the new version. A source that is already READY becomes the version at once, and the same source makes its version once (sending it again answers that version). A script in no project has nowhere to keep the file: send its text instead.
  - `content` string: The new version's screenplay text.
  - `sourceId` string: A source of the script's project whose text becomes the version once it is READY.
  - `fileUrl` string, uri: A link to the file (PDF, .fdx, .fountain or .txt), read in the background as a source of the script's project.
  - `fileName` string: The file's name; its extension says what it is.
  - `format` 'text' | 'fountain' | 'fdx': How the text is written (default: the file's own, else `text`).

## Response `200`

The script and the version this call created (or the version its source already made), or `waiting` while its file is still being read.

- union
  - ScriptUploadResponse
    - `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 version this call created.
    - `versionNumber` integer, required
  - ScriptVersionWaiting: The file is still being read: no version is made yet. Check the source until it is READY, then send `sourceId`.
    - `waiting` true, required
    - `scriptId` string, required
    - `projectId` string, required: The project the source is in (GET /story-projects/{projectId}/sources/{sourceId}).
    - `sourceId` string, required: Send it as `sourceId` once the source is READY.
    - `sourceStatus` 'PENDING' | 'EXTRACTING', required
    - `message` string, required: What to tell the writer, and how to go on.

## 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)