Seasons

Advance one durable step of the next season episode.

Requires story:write, artifact:publish, and publishing:write. action=publish additionally requires publishing:publish, checked per-action once the body is read, so a connector that only produces episodes never has to hold publish rights. Performs at most one idempotent queue/reconciliation step, then returns current durable state. It never crosses a human stop automatically: generated StoryPlans require POST /story-plans/{planId}/approve with userConfirmed=true; a terminal failed/rejected/superseded plan requires action=replan with explicit confirmation and can carry an optional correction instruction (a rejected plan defaults to its persisted rejection reason); the instruction is copied into the replacement StoryPlan creative brief and survives dispatch retries; a terminal failed CoverageReport requires action=retry_coverage with explicit confirmation and reuses that same report id/version; a completed report that fails the score gate requires action=revise plus the exact human-approved instruction or an exact replacement screenplay; nextAction=repair_production returns the current artifact and durable music/SFX/voice-effect blockers, which must be repaired through the artifact mutation surfaces before action=advance re-evaluates finalization; a coverage-passed, finalized MP3 requires action=publish before an RSS release is created. Episodes publish in order. The fail-closed gate checks overallScore and premise, structure, characters, dialogue, pacing, and marketFit on the 1–10 integer scale plus the allowed recommendation. Requires Idempotency-Key.

post/season-runs/{runId}/advance

Request

  • Base URL: https://docs.sleeperhit.studio/api/v1
  • URL: https://docs.sleeperhit.studio/api/v1/season-runs/{runId}/advance
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

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

Request body

episodeIdstring

Episode to advance. Omit to select the first unpublished episode. Earlier episodes must publish first.

action'advance' | 'replan' | 'retry_coverage' | 'revise' | 'publish'

advance performs one idempotent reconciliation/queue step. replan, retry_coverage, revise, and publish are explicit human-approved actions valid only at matching stop states. replan replaces a terminal failed/rejected/superseded episode plan; retry_coverage requeues the same failed current CoverageReport id/version without creating a report. Omit this field to default to advance; any other supplied value returns validation_failed.

instructionstring

Required with action=revise unless screenplay is supplied. Optional with action=replan to supply the exact correction brief; when omitted, a rejected plan reuses its persisted rejection reason. The replacement StoryPlan retains the instruction in its creativeBrief.

screenplaystring

For action=revise only: exact replacement screenplay. Bypasses the AI rewrite while retaining versioning, parsing, casting, scoring, and fresh coverage.

userConfirmedboolean

Required and true for action=replan, action=retry_coverage, action=revise, or action=publish after the user explicitly approves that exact action.

Response

Advanced or reconciled season run.

Changes

No recorded changes to this operation across all 2 revisions of this API.