---
title: "Share a table read."
method: POST
path: "/scripts/{scriptUploadId}/share"
tags: ["Scripts"]
---

# Share a table read.

`POST /scripts/{scriptUploadId}/share`

## Request

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

Create — or reuse — ONE screenplay version's (`scriptUploadId`) table-read share link: a public, signed URL that plays (theater) or streams (audio) the read. The body is optional; with none it is a public whole-read theater share for the studio's 30-day window. Pass `audience` (public, private_review, team), `includeOnProfile`, `expiresInDays` (1–365) or a `descriptor` (`mode` theater|audio, `scope` whole|scene|entries|conversation, `sceneIndex`, `startEntry`/`endEntry`, `conversationId`) to shape it. Pass `tableReadJobId` to share an exact read; omitted, the script's newest read WITH voices is used. A create identical to the script's active link reuses that link unchanged; ANY difference mints a new link and leaves the sent one alone, so a sent URL never silently re-scopes — no `Idempotency-Key`. A script with no performed read is 400 `validation_failed`; a script that is not yours is 404. Free: a theater MP4 renders only when asked, an audio share's scoped MP3 renders by itself. The same write the Writers Lab's share dialog, MCP `share_script` and `sleeperhit script share create` make.

## Request body

- CreateScriptShareRequest: The share options to create with. Every field is optional; an empty body is the public, whole-read theater share for the studio's 30-day window.
  - `audience` 'public' | 'private_review' | 'team': Who can use the link. Default `public`.
  - `includeOnProfile` boolean: Show the share on the writer's public profile (only honored for a public share). Default false.
  - `descriptor` ScriptShareDescriptor: The playback a share describes. Every field is optional; a create with none is the whole-read theater share the dialog's default is.
    - `mode` 'theater' | 'audio': `theater`: an MP4 link that plays the read. `audio`: a scoped full-mix MP3. Default `theater`.
    - `source` 'recording' | 'adhoc': Where the recording comes from: the job's recording, or an ad-hoc performance. Default `recording`.
    - `scope` 'whole' | 'scene' | 'entries' | 'conversation': What the share plays: the whole read, one scene, a band of entries, or one conversation. Default `whole`.
    - `sceneIndex` integer: For `scope: scene`: which scene.
    - `conversationId` string: For `scope: conversation`: which conversation.
    - `startEntry` integer: For `scope: entries`: the first entry index.
    - `endEntry` integer: For `scope: entries`: the last entry index.
    - `withCredits` boolean: Bake the opening title + closing credits into a whole-episode theater MP4.
  - `expiresInDays` integer: How long the link works, in days. Default 30.

## Response `200`

The share link, created or reused.

- CreateScriptShareResult
  - `scriptUploadId` string, required
  - `jobId` string, required
  - `shareUrl` string, required: The public, signed watch/listen URL.
  - `share` ScriptShareLink, required
    - `id` string, required: The share link id.
    - `audience` 'public' | 'private_review' | 'team', required
    - `descriptor` ScriptShareDescriptor, required: The playback a share describes. Every field is optional; a create with none is the whole-read theater share the dialog's default is.
      - `mode` 'theater' | 'audio': `theater`: an MP4 link that plays the read. `audio`: a scoped full-mix MP3. Default `theater`.
      - `source` 'recording' | 'adhoc': Where the recording comes from: the job's recording, or an ad-hoc performance. Default `recording`.
      - `scope` 'whole' | 'scene' | 'entries' | 'conversation': What the share plays: the whole read, one scene, a band of entries, or one conversation. Default `whole`.
      - `sceneIndex` integer: For `scope: scene`: which scene.
      - `conversationId` string: For `scope: conversation`: which conversation.
      - `startEntry` integer: For `scope: entries`: the first entry index.
      - `endEntry` integer: For `scope: entries`: the last entry index.
      - `withCredits` boolean: Bake the opening title + closing credits into a whole-episode theater MP4.
    - `mode` 'theater' | 'audio', required
    - `active` boolean, required
    - `includeOnProfile` boolean, required
    - `expiresAt` string, nullable, required: When the link stops working, or null for no expiry.
    - `renderedVideoStatus` string, required: The theater MP4's render state: idle, needs_recording, queued, rendering, complete, stale or failed. A render that stopped with no job behind it reads `failed` (or `stale` over an earlier MP4) with `renderedVideoError` saying so: ask for it again.
    - `renderedVideoUrl` string, nullable, required
    - `renderedVideoDurationMs` integer, nullable, required
    - `renderedVideoError` string, nullable, required
    - `renderedAudioStatus` string, required: The scoped MP3's render state. A render that stopped with no job behind it reads `failed` (or `stale` over an earlier MP3 — or when the earlier MP3 could not be confirmed) with `renderedAudioError` saying so: share the read again to render it.
    - `renderedAudioUrl` string, nullable, required
    - `renderedAudioDurationMs` integer, nullable, required
    - `renderedAudioError` string, nullable, required
  - `dashboardPath` string, required: The Writers Lab path the owner opens to manage the share.
  - `dashboardUrl` string, required

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