Timelines and storyboards.

Timeline and storyboard documents describe editable media work. They are separate from the rendered movie, uploaded source files, and Studio's live editor state. All routes below are relative to /api/v1.

#Choose the document you intend to change

Read the saved storyboard or timeline document before changing it. A storyboard describes scenes and shots; a timeline describes ordered media and timing. Save edits through the guarded project contract. Rendering creates a separate execution and artifact; an edited document does not prove that a media file was rendered. Preserve the local document when a save outcome is unresolved.

The authored shot 01 image and shot 02 video still carry the same identities into the converted timeline; shot 03 has missing media and is absent from that strip. Parsing interchange, persisting imported media and rendering final.mp4 are separate actions.

#Validate a document first

Read the public JSON Schemas at GET /timelines/schema/kaitoi-timeline-document.v1 and GET /storyboards/schema/kaitoi-storyboard-document.v1. Validate {document} through POST /timelines/validate or POST /storyboards/validate using the corresponding read scope. Read the normalized document, summary, and warnings rather than assuming raw JSON was accepted unchanged.

#Read or replace project media documents

GET /projects/{id}/timeline requires projects:read plus timelines:read; the storyboard equivalent requires storyboards:read. Writes through PUT /projects/{id}/timeline or /storyboard require the corresponding project/media write scopes and {expectedVersion,document}.

Timeline replacement collapses a multiple-scene project timeline into one replacement scene. Storyboard replacement supports explicit mode:"replace"|"append". Inspect the current version and content before choosing a broad replacement. Reconcile conflicts instead of copying a new version onto stale content. If the project reports an in-progress, unresolved or unavailable save state, preserve your local document and follow guarded project recovery before another write; those refusals do not authorize automatic retry.

#Convert or exchange supported material

POST /storyboards/to-timeline requires both media read scopes and converts {document} without mutating a saved project. Read warnings: unresolved, unsupported, URL-only or document-like material can be skipped. Conversion does not fetch arbitrary remote media or generate missing footage.

POST /timelines/export/otio exports a supported interchange ZIP; POST /timelines/import/otio/parse parses a multipart file without storing media. POST /timelines/import/otio requires timelines:write and persists included media into the caller's Library. Keep parsing, persistence and final rendering distinct. A missing interchange dependency can make export unavailable.

#Choose the intended operation

Validate: normalize and inspect an editable document without rendering. Convert: storyboard-to-timeline produces supported sequence data and warnings without changing a saved project. Import: parse-only and a media- persisting import are distinct operations. Whole timeline replacement can collapse multiple scenes. None of these operations is a final video render.

#Inspect the destination

After conversion or import, compare clip timing, media references, audio, and warnings with the source. Interchange does not guarantee every external editor interprets every effect identically. For live attached Studio media editing, use MCP media tools rather than confusing document replacement with editor commands.