---
title: "Set the deck's visual grammar."
method: POST
path: "/pitch-decks/{jobId}/visual-grammar"
tags: ["Pitch Deck"]
---

# Set the deck's visual grammar.

`POST /pitch-decks/{jobId}/visual-grammar`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/pitch-decks/{jobId}/visual-grammar`
- Auth: HTTP bearer

Replaces the deck's visual grammar (the chapters read returns the current one as `visualGrammar`). The visual grammar is the deck's one camera language across every chapter: how its world is lit and framed, how the camera moves or holds, and how chapters hand off. It is plan words: plan coverage judges every chapter against it, and nothing rendered reads it, so changing it never makes a take out of date. An unknown field is refused by name (400). Free. On a draft plan the changed plan is queued for plan coverage again (`planCoverage`); in review or complete it is saved on the plan and nothing else happens. The answer's `edited` says which version changed. Refused while a render or finish pass runs (409). Requires `Idempotency-Key`. Scope: `story:write`.

## Headers

- `Idempotency-Key` string, required

## Request body

- PitchDeckVisualGrammarUpdateRequest
  - `visualGrammar` string, required: The deck's whole visual grammar, as it should read (spacing is collapsed). The visual grammar is the deck's one camera language across every chapter: how its world is lit and framed, how the camera moves or holds, and how chapters hand off. It is plan words: plan coverage judges every chapter against it, and nothing rendered reads it, so changing it never makes a take out of date.

## Response `200`

The deck's visual grammar, as saved.

- PitchDeckVisualGrammarUpdateAck
  - `success` true, required
  - `jobId` string, required
  - `status` 'draft' | 'review' | 'complete', required
  - `edited` 'draft_plan' | 'rendered_deck', required: Which version changed: the draft plan, or a rendered deck's plan. Tell the writer which one.
  - `visualGrammar` string, required: The visual grammar the stored plan now holds (read back).
  - `changed` boolean, required: False when the deck already said exactly this: nothing was written and nothing queued.
  - `planCoverage` 'queued' | 'current' | 'failed' | 'null', nullable, required: On a draft: the changed plan's coverage (`queued` for the latest edit). Null otherwise.

## 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.
- `409`: The pitch deck exists and the request is well-formed, but the deck, its chapter, its cast or its plates are not in a state that allows it (`pitch_deck_state_invalid`), and nothing was reserved: a plan approved outside draft, a take chosen, a chapter edited or rendered outside review/complete, an export before the finish, a finish while a call has no selected take or a footage chapter has not rendered, a text-only chapter asked for footage, a changed chapter asked for one call, a delivery class changed mid-pass, a render the compile blocked, or a finish while the master failed its video coverage (`pitch_deck_video_coverage_failed`, with `details.videoCoverage`). `details.refusal` is `{ code, action, fix }` (see PitchDeckRefusalDetails): `action` is what unblocks it — `recast_figure`, `add_signature_items`, `recast_voice` or `remake_location_plate` — and `fix` names the MCP tool and CLI command that take it; `details.blocked[]` lists every chapter a blocked compile could not render. The identical request succeeds once the deck is put right.
- `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)