---
title: "Rewrite a character's acting directions in a table read."
method: POST
path: "/scripts/{scriptUploadId}/table-read/characters/rewrite-directions"
tags: ["Scripts"]
---

# Rewrite a character's acting directions in a table read.

`POST /scripts/{scriptUploadId}/table-read/characters/rewrite-directions`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/scripts/{scriptUploadId}/table-read/characters/rewrite-directions`
- Auth: HTTP bearer

Rewrites EVERY acting direction of ONE character in a table read — the ONE thing that decides how their lines are performed (there are no emotion tags). Generates new directions for the character's lines (with an optional creative direction), in bounded batches so a feature-length part is handled, and writes them onto the read; `apply: false` previews evenly-spaced samples and writes nothing. On a Cartesia voice each new direction is mapped to one emotion when the line is next SPOKEN, so the rewrite changes the written direction now and NEVER re-records audio by itself — the line shows the new `sentAs` on its next voice pass; re-voice or update the recording separately to hear it. The read is resolved from `scriptUploadId` (the caller's latest read for that script; a script that is not yours, has no read, or has no such character is 404 `script_not_found`). An unknown field, a missing/blank `character`, a non-string `direction` or a non-boolean `apply` is refused with 400 `validation_failed` — the same validation the Writers Lab, MCP `rewrite_character_acting_directions` and `sleeperhit script table-read rewrite-directions` go through. FREE: it reserves no credits and renders nothing. Scope: `story:write`.

## Request body

- RewriteActingDirectionsRequest
  - `character` string, required: The character's name (or cue) as it appears in the read, or "NARRATOR" for narration. A name, not an id.
  - `direction` string: Optional creative direction in the writer's words, e.g. "more subdued", "angrier", "playful irony".
  - `apply` boolean, required: false previews evenly-spaced samples and writes nothing; true saves the rewrite to every line of the character.

## Response `200`

The rewrite was previewed (apply false) or saved (apply true).

- RewriteActingDirectionsResult
  - `preview` boolean, required: True when nothing was written (apply was false): the samples are a preview.
  - `character` string, required: The character whose directions were rewritten.
  - `total` integer, required: Every line of the character in the read.
  - `processed` integer, required: The lines this pass touched: every line when applying, the sampled lines when previewing.
  - `samples` object[], required
    - `line` string, required: The line's words, cut to 80 characters.
    - `oldActingDirection` string: The direction the line had, when it had one.
    - `newActingDirection` string, required: The rewritten direction.
  - `direction` string, nullable, required: The creative direction the rewrite was asked for, or null.
  - `ttsProvider` string, required: The read's voice provider whose context shaped the directions.

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