---
title: "Change the table read's theater presentation."
method: POST
path: "/artifacts/{artifactId}/theater"
tags: ["Artifacts"]
---

# Change the table read's theater presentation.

`POST /artifacts/{artifactId}/theater`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/artifacts/{artifactId}/theater`
- Auth: HTTP bearer

A partial update of the whole read's presentation: keys left out are untouched and theme objects merge field by field. `applyStyleSetId` applies a built-in or saved style set and marks it active (applied first, then any theme field beside it); `styleSets` replaces the saved custom sets; `nounImagery.displayMode` sets how spoken-noun images appear. The scene soundtrack's master switch is `soundtrackEnabled` on POST /artifacts/{artifactId}/music. The same save the Table Read page's theater settings make. Free: renders nothing. Requires `Idempotency-Key`. Scope: `artifact:publish`.

## Headers

- `Idempotency-Key` string, required

## Request body

- TableReadTheaterUpdateRequest: A partial update of the whole read's presentation. Keys left out are untouched; theme objects merge field by field.
  - `theaterModeDefault` boolean: Open the read in theater mode by default.
  - `backgroundAnimationEnabled` boolean: Moving backdrops on or off.
  - `adaptiveStyleEnabled` boolean: Scene visuals (each scene's own motifs, overlay and accents) on or off.
  - `applyStyleSetId` string: Apply a built-in or saved style set (GET lists them) and mark it active.
  - `styleSets` object[]: Replaces the saved custom style sets.
    - `id` string, required
    - `name` string, required
    - `description` string
  - `fullscreenChrome` object
    - `autoHideEnabled` boolean
    - `idleDelayMs` number
    - `hoverRevealHeight` number
  - `globalSceneTheme` object
    - `mediaPreference` 'image' | 'video'
    - `transitionType` 'crossfade' | 'spotlight' | 'curtain' | 'drift' | 'hard-cut'
    - `transitionDurationMs` number
    - `transitionEasing` string
    - `artDirection` string
    - `visualStyle` TableReadVisualStyle: A theater look: gradient, colors, filter, animation, lighting, texture and intensity.
      - `bgGradient` string
      - `ambientColor` string
      - `textColor` string
      - `accentColor` string
      - `shadowColor` string
      - `filter` string
      - `animation` string
      - `lighting` string
      - `texture` string
      - `intensity` number
      - `textRevealStyle` 'fade' | 'drift' | 'spotlight': How on-screen text appears.
  - `scriptPaneTheme` object
    - `layoutMode` 'glass_panel' | 'stage_captions' | 'cinematic_dialogue'
    - `dialoguePresentation` 'bubbles' | 'captions' | 'floating'
    - `bubbleStyle` 'soft' | 'glass' | 'outline'
    - `paneOpacity` number
    - `paneBlurPx` number
    - `paneBorderOpacity` number
    - `paneShadowStrength` number
    - `isTransparent` boolean
    - `backgroundGradient` string
  - `fontTheme` object
    - `headingFontId` string
    - `dialogueFontId` string
    - `headingScale` number
    - `dialogueScale` number
    - `headingWeight` string
    - `dialogueWeight` string
    - `letterSpacingEm` number
    - `lineHeight` number
  - `titleScreen` object
    - `layout` 'center' | 'stage_left' | 'lower_third'
    - `titleOverride` string
    - `subtitle` string
  - `nounImagery` object
    - `displayMode` 'insets' | 'replace_backdrop' | 'off', required

## Response `200`

The presentation as it now stands.

- TableReadTheaterUpdateResponse
  - `artifactId` string, required
  - `presentation` object, required: The whole read's presentation as it now stands.

## 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 story artifact does not exist or is owned by another account.
- `409`: The artifact is not in a state where this operation is valid yet (e.g. requesting an MP4 render before the share link exists).
- `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)