API Reference

This reference is generated from the live OpenAPI builder, schema registry, capabilities manifest, examples manifest, and UI/API/CLI/MCP surface registry. Do not hand-edit endpoint lists; change the contract code and regenerate.

Machine-readable surfaces

Surface	Path
Capabilities	`/api/v1/capabilities`
OpenAPI JSON	`/api/v1/openapi.json`
Examples	`/api/v1/examples`
Agent index	`/agent-index.json`
Four-surface contract	`/docs/surface-contract.json`
CLI command map	`/docs/cli-commands.json`
MCP tool map	`/docs/mcp-tools.json`

Surface coverage

Operations: 116
OpenAPI operations: 111
Complete UI/API/CLI/MCP operations: 116 / 116

Surface	Bound operations
UI	116 / 116
API	116 / 116
CLI	116 / 116
MCP	116 / 116

Development flow warnings

Complete the Series Bible before screenplay pages

Stage: before_screenplay_generation
Blocking: no
Surfaces: ui, api, cli, mcp
Guidance: Before planning or generating a screenplay-backed table_read artifact, read, save, or generate the project Series Bible and confirm the format, audience, season arc, episode map, character roster, canon/world rules, visual style, audio style, and open questions are usable. The planner and screenplay adapter auto-load the saved Series Bible as project canon; if the user proceeds anyway, carry the missing areas into the StoryPlan review instead of silently ignoring them.

Complete Series Bible Visuals before storyboarding

Stage: before_storyboard_rendering
Blocking: yes
Surfaces: ui, api, cli, mcp
Guidance: Storyboard creation and rendering are locked until the Series Bible has explicit production medium, visual style, character design, visual truths, production design, color palette, lighting rules, camera language, and location truths. Read document.readiness.visuals on the shared Series Bible response and resolve every missing field before creating the storyboard.

Run one coverage round after the screenplay exists

Stage: after_screenplay_exists
Blocking: no
Surfaces: ui, api, cli, mcp
Guidance: Once a screenplay-backed table_read artifact exists, read or poll the first coverage report before treating the script as ready for finalization, pitch packaging, or later installment generation. Table-read jobs queue the initial coverage pass when pages are created; request a new report only if none exists or the user wants another pass. Use the report, especially top fixes, to drive one revision pass. This is guidance, not an enforcement gate.

Artifacts

Endpoint	Operation ID	Scope	Idempotent	Schemas
`GET /api/v1/artifacts/{artifactId}`	`getStoryArtifact`	artifact:read	no	response:StoryArtifactEnvelope
`POST /api/v1/artifacts/{artifactId}/avatar`	`recastArtifactAvatar`	artifact:publish	yes	request:AvatarRecastRequest<br>response:AvatarRecastResponse
`GET /api/v1/artifacts/{artifactId}/cast`	`getArtifactCast`	artifact:read	no	response:CastEnvelope
`POST /api/v1/artifacts/{artifactId}/cast`	`updateArtifactCast`	artifact:publish	yes	request:CastBatchRequest<br>response:CastBatchResponse
`GET /api/v1/artifacts/{artifactId}/coverage`	`getArtifactCoverage`	artifact:read	no	response:CoverageReportEnvelope
`POST /api/v1/artifacts/{artifactId}/coverage`	`generateArtifactCoverage`	story:write	yes	response:CoverageDispatchAck
`POST /api/v1/artifacts/{artifactId}/finalize`	`finalizeArtifact`	artifact:publish	yes
`POST /api/v1/artifacts/{artifactId}/finalize/retry`	`retryArtifactFinalize`	artifact:publish	yes	response:ArtifactFinalizeAck
`GET /api/v1/artifacts/{artifactId}/music`	`getArtifactMusic`	artifact:read	no	response:MusicStatusEnvelope
`POST /api/v1/artifacts/{artifactId}/music`	`generateArtifactMusic`	artifact:publish	yes	request:MusicGenerateRequest<br>response:MusicGenerateResponse
`POST /api/v1/artifacts/{artifactId}/performance`	`updateArtifactPerformance`	artifact:publish	yes	request:PerformanceDirectiveRequest<br>response:PerformanceDirectiveResponse
`POST /api/v1/artifacts/{artifactId}/refine`	`refineArtifact`	artifact:publish	yes
`GET /api/v1/artifacts/{artifactId}/render-video`	`getArtifactRenderStatus`	artifact:read	no	response:ArtifactRenderStatus
`POST /api/v1/artifacts/{artifactId}/render-video`	`renderArtifactVideo`	artifact:publish	yes	response:ArtifactRenderAck
`GET /api/v1/artifacts/{artifactId}/script`	`getArtifactScript`	artifact:read	no	response:ArtifactScriptContentEnvelope
`POST /api/v1/artifacts/{artifactId}/script`	`replaceArtifactScript`	artifact:publish	yes	request:ArtifactScriptReplacementRequest<br>response:StoryJobEnvelope
`GET /api/v1/artifacts/{artifactId}/sfx`	`listArtifactSfx`	artifact:read	no	response:SfxListResponse
`POST /api/v1/artifacts/{artifactId}/sfx`	`manageArtifactSfx`	artifact:publish	yes	request:SfxManageRequest<br>response:SfxMutationResponse
`POST /api/v1/artifacts/{artifactId}/theater-canvas`	`applyTheaterCanvas`	artifact:publish	yes	request:TheaterCanvasRequest<br>response:TheaterMotionResult
`POST /api/v1/artifacts/{artifactId}/theater-motion-clip`	`generateTheaterMotionClip`	artifact:publish	yes	request:TheaterMotionClipRequest<br>response:TheaterMotionResult
`POST /api/v1/artifacts/{artifactId}/theater-motion`	`directTheaterMotionBeat`	artifact:publish	yes	request:TheaterMotionBeatRequest<br>response:TheaterMotionResult
`POST /api/v1/artifacts/{artifactId}/voice-modification`	`modifyArtifactVoice`	artifact:publish	yes	request:VoiceModificationRequest<br>response:VoiceModificationResponse
`POST /api/v1/artifacts/{artifactId}/voice`	`recastArtifactVoice`	artifact:publish	yes
`GET /api/v1/story-jobs/{jobId}/artifacts`	`listStoryJobArtifacts`	artifact:read	no	response:StoryArtifactListResponse

Brand

Endpoint	Operation ID	Scope	Idempotent	Schemas
`POST /api/v1/brand-coverage`	`analyzeBrandCoverage`	story:write	yes	request:BrandCoverageRequest<br>response:BrandCoverageAck
`GET /api/v1/brand-coverage/{reportId}`	`getBrandCoverage`	story:read	no	response:BrandCoverageReport
`POST /api/v1/brand-narrative`	`generateBrandNarrative`	story:write	yes	request:BrandNarrativeRequest<br>response:BrandNarrativeResponse

Credits

Endpoint	Operation ID	Scope	Idempotent	Schemas
`GET /api/v1/credits`	`getCredits`	credits:read	no	response:CreditsSummary

Discovery

Endpoint	Operation ID	Scope	Idempotent	Schemas
`GET /api/v1/agent-guidance`	`getAgentGuidance`	story:read	no	response:AgentGuidance
`GET /api/v1/capabilities`	`getCapabilities`	story:read	no	response:Capabilities

Jobs

Endpoint	Operation ID	Scope	Idempotent	Schemas
`GET /api/v1/story-jobs`	`listStoryJobs`	story:read	no	response:StoryJobList
`POST /api/v1/story-jobs`	`createStoryJob`	story:write	yes	request:StoryJobCreate<br>response:StoryJobEnvelope
`GET /api/v1/story-jobs/{jobId}`	`getStoryJob`	story:read	no	response:StoryJobEnvelope
`POST /api/v1/story-jobs/{jobId}/cancel`	`cancelStoryJob`	story:write	yes	response:StoryJobEnvelope
`POST /api/v1/story-jobs/{jobId}/resume`	`resumeStoryJob`	story:write	yes	response:StoryJobResumeResponse

Library

Endpoint	Operation ID	Scope	Idempotent	Schemas
`GET /api/v1/library/audio`	`listMyLibraryAudio`	story:read	no	response:MyLibraryAudio
`POST /api/v1/library/audio`	`importMyLibraryAudio`	story:write	yes	request:MyLibraryAudioImportRequest<br>response:MyLibraryAudioImportResponse
`GET /api/v1/library/images`	`listMyLibraryImages`	story:read	no	response:MyLibraryImages

Pitch Deck

Endpoint	Operation ID	Scope	Idempotent	Schemas
`POST /api/v1/pitch-decks/{jobId}/draft/approve`	`approvePitchDeckDraft`	story:write	yes	response:PitchDeckStageAck
`GET /api/v1/pitch-decks/{jobId}/storyboard`	`getPitchDeckStoryboard`	story:read	no	response:PitchDeckStoryboard
`POST /api/v1/pitch-decks/{jobId}/storyboard/apply-component`	`applySceneComponentToPitchDeck`	story:write	yes	request:PitchDeckApplyComponentRequest<br>response:PitchDeckFramePreview
`POST /api/v1/pitch-decks/{jobId}/storyboard/approve`	`approvePitchDeckStoryboard`	story:write	yes	response:PitchDeckStageAck
`POST /api/v1/pitch-decks/{jobId}/storyboard/refine`	`refinePitchDeckFrame`	story:write	yes	request:PitchDeckFrameRefineRequest<br>response:PitchDeckFramePreview
`POST /api/v1/pitch-decks/{jobId}/storyboard/regenerate-clip`	`regeneratePitchDeckClip`	artifact:publish	yes	request:PitchDeckFrameIndexRequest<br>response:PitchDeckRegenAck
`POST /api/v1/pitch-decks/{jobId}/storyboard/regenerate-text`	`regeneratePitchDeckText`	artifact:publish	yes	request:PitchDeckFrameIndexRequest<br>response:PitchDeckRegenAck
`POST /api/v1/pitch-decks/{jobId}/storyboard/regenerate`	`regeneratePitchDeckFrame`	artifact:publish	yes	request:PitchDeckFrameIndexRequest<br>response:PitchDeckRegenAck
`POST /api/v1/pitch-decks/{jobId}/storyboard/swap-library`	`swapPitchDeckFrameFromLibrary`	story:write	yes	request:PitchDeckSwapLibraryRequest<br>response:PitchDeckFramePreview

Plans

Endpoint	Operation ID	Scope	Idempotent	Schemas
`GET /api/v1/story-plans/{planId}`	`getStoryPlan`	story:read	no	response:StoryPlanEnvelopeResponse
`POST /api/v1/story-plans/{planId}/approve`	`approveStoryPlan`	story:write	yes	request:StoryPlanApprovalRequest<br>response:StoryPlanEnvelopeResponse
`POST /api/v1/story-plans/{planId}/reject`	`rejectStoryPlan`	story:write	yes	response:StoryPlanEnvelopeResponse
`POST /api/v1/story-plans/{planId}/resume`	`resumeStoryPlan`	story:write	yes	response:StoryPlanEnvelopeResponse
`GET /api/v1/story-projects/{projectId}/story-plans`	`listStoryPlans`	story:read	no	response:StoryPlanList
`POST /api/v1/story-projects/{projectId}/story-plans`	`createStoryPlan`	story:write	yes	request:StoryPlanCreate<br>response:StoryPlanEnvelopeResponse

Projects

Endpoint	Operation ID	Scope	Idempotent	Schemas
`GET /api/v1/story-projects`	`listStoryProjects`	story:read	no	response:StoryProjectList
`POST /api/v1/story-projects`	`createStoryProject`	story:write	yes	request:StoryProjectCreate<br>response:StoryProjectEnvelope
`DELETE /api/v1/story-projects/{projectId}`	`deleteStoryProject`	story:write	no	response:DeletionAck
`GET /api/v1/story-projects/{projectId}`	`getStoryProject`	story:read	no	response:StoryProjectEnvelope
`PATCH /api/v1/story-projects/{projectId}`	`updateStoryProject`	story:write	no	request:StoryProjectPatch<br>response:StoryProjectEnvelope
`GET /api/v1/story-projects/{projectId}/cast-canon`	`getProjectCastCanon`	story:read	no	response:CastCanonEnvelope
`PATCH /api/v1/story-projects/{projectId}/cast-canon`	`saveProjectCastCanon`	story:write	no	request:CastCanonPatch<br>response:CastCanonEnvelope
`GET /api/v1/story-projects/{projectId}/series-bible`	`getProjectSeriesBible`	story:read	no	response:SeriesBibleEnvelope
`PATCH /api/v1/story-projects/{projectId}/series-bible`	`saveProjectSeriesBible`	story:write	no	request:SeriesBiblePatch<br>response:SeriesBibleEnvelope
`POST /api/v1/story-projects/{projectId}/series-bible`	`generateProjectSeriesBible`	story:write	yes	request:SeriesBibleGenerateRequest<br>response:SeriesBibleEnvelope
`GET /api/v1/story-projects/{projectId}/series-bible/coverage`	`getProjectSeriesBibleCoverage`	story:read	no	response:SeriesBibleCoverageEnvelope
`POST /api/v1/story-projects/{projectId}/series-bible/coverage`	`generateProjectSeriesBibleCoverage`	story:write	yes	request:SeriesBibleCoverageGenerateRequest<br>response:SeriesBibleCoverageEnvelope

Publishing

Endpoint	Operation ID	Scope	Idempotent	Schemas
`GET /api/v1/publishing-feeds/{seriesSlug}.xml`	`getPublishingRssFeed`		no
`GET /api/v1/publishing-provider-configs`	`listPublishingProviderConfigs`	publishing:connect	no	response:PublishingProviderConfigList
`POST /api/v1/publishing-provider-configs`	`upsertPublishingProviderConfig`	publishing:connect	yes	request:PublishingProviderConfigUpsertRequest<br>response:PublishingProviderConfigEnvelope
`GET /api/v1/publishing-releases/{releaseId}`	`getPublishingRelease`	publishing:read	no	response:PublishingReleaseEnvelope
`PATCH /api/v1/publishing-releases/{releaseId}`	`updatePublishingRelease`	publishing:write	no	request:PublishingReleaseUpdateRequest<br>response:PublishingReleaseEnvelope
`POST /api/v1/publishing-releases/{releaseId}/cancel`	`cancelPublishingRelease`	publishing:publish	yes	response:PublishingReleaseEnvelope
`POST /api/v1/publishing-releases/{releaseId}/description/generate`	`generatePublishingReleaseDescription`	publishing:write	yes	response:PublishingReleaseEnvelope
`POST /api/v1/publishing-releases/{releaseId}/publish`	`publishPublishingRelease`	publishing:publish	yes	response:PublishingReleaseEnvelope
`POST /api/v1/publishing-releases/{releaseId}/refresh-media`	`refreshPublishedReleaseMedia`	publishing:publish	yes	request:PublishingReleaseRefreshMediaRequest<br>response:PublishingReleaseEnvelope
`POST /api/v1/publishing-releases/{releaseId}/schedule`	`schedulePublishingRelease`	publishing:publish	yes	response:PublishingReleaseEnvelope
`GET /api/v1/publishing-releases/{releaseId}/targets`	`listPublishingReleaseTargets`	publishing:read	no	response:PublishingTargetList
`GET /api/v1/publishing-series/{seriesId}`	`getPublishingSeries`	publishing:read	no	response:PublishingSeriesEnvelope
`PATCH /api/v1/publishing-series/{seriesId}`	`updatePublishingSeries`	publishing:write	no	request:PublishingSeriesUpdateRequest<br>response:PublishingSeriesEnvelope
`GET /api/v1/publishing-series/{seriesId}/analytics`	`listPublishingAnalyticsSnapshots`	publishing:analytics	no	response:PublishingAnalyticsList
`GET /api/v1/publishing-series/{seriesId}/destinations`	`listPublishingDestinations`	publishing:read	no	response:PublishingDestinationList
`POST /api/v1/publishing-series/{seriesId}/destinations`	`upsertPublishingDestination`	publishing:connect	yes	request:PublishingDestinationUpsertRequest<br>response:PublishingDestinationEnvelope
`POST /api/v1/publishing-series/{seriesId}/generate-cover-art`	`generatePublishingSeriesCoverArt`	publishing:write	no	request:PublishingCoverArtGenerateRequest<br>response:PublishingCoverArtGenerateResponse
`GET /api/v1/publishing-series/{seriesId}/releases`	`listPublishingReleases`	publishing:read	no	response:PublishingReleaseList
`POST /api/v1/publishing-series/{seriesId}/releases`	`createPublishingRelease`	publishing:write	yes	request:PublishingReleaseCreateRequest<br>response:PublishingReleaseEnvelope
`GET /api/v1/story-projects/{projectId}/publishing-series`	`listPublishingSeries`	publishing:read	no	response:PublishingSeriesList
`POST /api/v1/story-projects/{projectId}/publishing-series`	`createPublishingSeries`	publishing:write	yes	request:PublishingSeriesCreateRequest<br>response:PublishingSeriesEnvelope

Seasons

Endpoint	Operation ID	Scope	Idempotent	Schemas
`GET /api/v1/season-runs/{runId}`	`getStorySeasonRun`	story:read	no	response:SeasonRunEnvelope
`POST /api/v1/season-runs/{runId}/advance`	`advanceStorySeasonRun`	story:write, artifact:publish, publishing:write, publishing:publish	yes	request:SeasonRunAdvanceRequest<br>response:SeasonRunEnvelope
`POST /api/v1/season-runs/{runId}/approve`	`approveStorySeasonMap`	story:write	yes	request:SeasonRunApprovalRequest<br>response:SeasonRunEnvelope
`PATCH /api/v1/season-runs/{runId}/episodes/{episodeId}`	`updateStorySeasonEpisode`	story:write	no	request:SeasonRunEpisodeUpdateRequest<br>response:SeasonRunEnvelope
`GET /api/v1/story-projects/{projectId}/season-runs`	`listStorySeasonRuns`	story:read	no	response:SeasonRunList
`POST /api/v1/story-projects/{projectId}/season-runs`	`createStorySeasonRun`	story:write, publishing:write	yes	request:SeasonRunCreateRequest<br>response:SeasonRunEnvelope

Sources

Endpoint	Operation ID	Scope	Idempotent	Schemas
`GET /api/v1/story-projects/{projectId}/sources`	`listStorySources`	source:read	no	response:StorySourceList
`POST /api/v1/story-projects/{projectId}/sources`	`createStorySource`	source:write	yes	request:StorySourceCreate<br>response:StorySourceEnvelope
`DELETE /api/v1/story-projects/{projectId}/sources/{sourceId}`	`deleteStorySource`	source:write	no	response:DeletionAck
`GET /api/v1/story-projects/{projectId}/sources/{sourceId}`	`getStorySource`	source:read	no	response:StorySourceEnvelope

Trailer

Endpoint	Operation ID	Scope	Idempotent	Schemas
`POST /api/v1/trailers/{jobId}/draft/approve`	`approveTrailerDraft`	story:write	yes	response:TrailerStageAck
`GET /api/v1/trailers/{jobId}/storyboard`	`getTrailerStoryboard`	story:read	no	response:TrailerStoryboard
`POST /api/v1/trailers/{jobId}/storyboard/apply-component`	`applySceneComponentToTrailer`	story:write	yes	request:TrailerApplyComponentRequest<br>response:TrailerFramePreview
`POST /api/v1/trailers/{jobId}/storyboard/approve`	`approveTrailerStoryboard`	story:write	yes	response:TrailerStageAck
`POST /api/v1/trailers/{jobId}/storyboard/refine`	`refineTrailerFrame`	story:write	yes	request:TrailerFrameRefineRequest<br>response:TrailerFramePreview
`POST /api/v1/trailers/{jobId}/storyboard/regenerate-clip`	`regenerateTrailerClip`	artifact:publish	yes	request:TrailerBeatIndexRequest<br>response:TrailerRegenAck
`POST /api/v1/trailers/{jobId}/storyboard/regenerate-text`	`regenerateTrailerText`	artifact:publish	yes	request:TrailerBeatIndexRequest<br>response:TrailerRegenAck
`POST /api/v1/trailers/{jobId}/storyboard/regenerate`	`regenerateTrailerFrame`	artifact:publish	yes	request:TrailerBeatIndexRequest<br>response:TrailerRegenAck
`POST /api/v1/trailers/{jobId}/storyboard/swap-library`	`swapTrailerFrameFromLibrary`	story:write	yes	request:TrailerSwapLibraryRequest<br>response:TrailerFramePreview

Voices

Endpoint	Operation ID	Scope	Idempotent	Schemas
`GET /api/v1/voices`	`listStudioVoices`	story:read	no	response:StudioVoiceListResponse
`POST /api/v1/voices/clone-link`	`createVoiceCloneLink`	story:write	yes	response:VoiceCloneLinkResponse
`GET /api/v1/voices/pro/{jobId}`	`getProVoiceClone`	story:read	no	response:ProVoiceCloneStatus
`GET /api/v1/voices/pro/script`	`getProVoiceCloneScript`	story:read	no	response:ProVoiceCloneScript
`POST /api/v1/voices/pro/start`	`startProVoiceClone`	story:write	yes	request:ProVoiceCloneStartRequest<br>response:ProVoiceCloneStartResult
`POST /api/v1/voices/pro/train`	`startProVoiceCloneTraining`	story:write	yes	request:ProVoiceCloneTrainRequest<br>response:ProVoiceCloneTrainResult