# Timelines and storyboards

> Validate editable timeline and storyboard documents, convert supported shots, manage versioned project media, and distinguish interchange import from rendering.

Source: https://kaitoi.io/docs/core/timelines-and-storyboards/
Section: Kaitoi Core / REST API
Written for: Developers managing editable sequences and shot documents.
Last reviewed: 2026-10-24

---

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.

*Figure: Storyboard planning, timeline editing and rendering are separate operations.*

## 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](/docs/core/errors-and-retries/#recover-a-guarded-project-save)
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](/docs/core/mcp-media/) rather than confusing
document replacement with editor commands.