Scripts

Upload a screenplay.

The Writers Lab's upload, through its core: a new script WITH ITS PROJECT — it joins the project named in projectId (400 if that project is not the writer's live one; 409 project_precondition_failed with the gate's reason while that project cannot start an episode, as for POST /story-projects/{projectId}/episodes), or gets a new project named after the script — with its first version, parsed and its characters analysed in the background (read GET /scripts/{scriptId} until parseStatus is complete). With projectId, seasonNumber files it in that season (a planned episode already says its own season), and episodeId links it to a planned episode of the project's Series Bible by that stable id — refused with 400 validation_failed for an episode no longer in the Bible, and with 409 script_state_invalid when that episode already has a script (upload a new version of THAT script with POST /scripts/{scriptId}/versions instead); a title or label matching exactly one UNWRITTEN planned episode links by id on its own. A new screenplay can come from a file (a PDF, a Final Draft .fdx, or a Fountain or plain-text script) instead of its text. The file belongs to a project, so projectId is required: 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 screenplay. A source that is already READY becomes the screenplay at once, and one source makes its screenplay once (sending it again is refused, naming the script it already made). The body goes through the same parser as the Writers Lab, so a bad title, content or format is refused with the same sentence. Refused with 403 plan_limit_reached past the plan's page allowance. Free. Requires Idempotency-Key.

post/scripts

Request

  • Base URL: https://docs.sleeperhit.studio/api/v1
  • URL: https://docs.sleeperhit.studio/api/v1/scripts
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

Customer-generated stable identifier for safe retries of idempotent POST requests.

Request body

titlestring required
contentstring

The screenplay text.

sourceIdstring

A source of the named project whose text becomes the screenplay once it is READY. Needs projectId.

fileUrlstring uri

A link to the file (PDF, .fdx, .fountain or .txt), read in the background as a source of the named project. Needs projectId.

fileNamestring

The file's name; its extension says what it is.

format'text' | 'fountain' | 'fdx'

How the text is written (default text; for a file, its own else text).

projectIdstring

The project to file the script in; required for a file source, and without it a new project is named after the script.

seasonNumberinteger

The season to file the script in (a planned episode already says its own season). Needs projectId.

episodeIdstring

The Series Bible planned-episode id this upload IS (plannedEpisodes[].episodeId from GET /story-projects/{projectId}/episodes): the script is linked to it by id. Needs projectId.

Response

The new script and its first version, or waiting while its file is still being read.

OR

Changes

No recorded changes to this operation across all 1 revision of this API.