---
title: "Update project storyboard"
method: PUT
path: "/api/v1/projects/{project_id}/storyboard"
tags: ["Storyboards"]
---

# Update project storyboard

`PUT /api/v1/projects/{project_id}/storyboard`

## Request

- Base URL: `https://api.studio.kaitoi.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.studio.kaitoi.io/api/v1/projects/{project_id}/storyboard`
- Auth: HTTP bearer

Applies a Kaitoi Storyboard Document v1 to a saved project using optimistic concurrency. Supports replacing the current storyboard or appending imported scenes. Use Idempotency-Key so network retries can replay the saved response.

## Path parameters

- `project_id` string, required

## Headers

- `Idempotency-Key` string, nullable
- `authorization` string, nullable

## Request body

- PublicProjectStoryboardReplaceRequest
  - `expectedVersion` integer, required: Last project version observed by the client.
  - `mode` 'replace' | 'append': How to apply the storyboard document to the current project storyboard.
  - `document` object, required: Kaitoi Storyboard Document v1 JSON to apply.

## Response `200`

Saved project storyboard document and apply summary.

- PublicProjectStoryboardApplyResponse
  - `projectId` string, required: Stable project identifier.
  - `version` integer, required: New optimistic concurrency version after the write.
  - `mode` 'replace' | 'append', required: Apply mode used for this write.
  - `document` object, required: Resulting project storyboard exported as Kaitoi Storyboard Document v1.
  - `summary` PublicStoryboardApplySummary, required
    - `sceneCount` integer, required: Number of sequences/scenes in the storyboard.
    - `shotCount` integer, required: Number of shots/frames in the storyboard.
    - `mediaCount` integer, required: Number of panel and audio media references.
    - `mediaImported` integer, required: Number of media references imported into internal storyboard frame slots.
    - `mediaSkipped` integer, required: Number of media references skipped during apply.
    - `unresolvedMedia` integer, required: Number of skipped unresolved media placeholders.
    - `urlMedia` integer, required: Number of skipped URL media references.
    - `documentMedia` integer, required: Number of skipped document media references.
    - `extraPanelMedia` integer, required: Number of skipped extra panel media references.
    - `warnings` PublicStoryboardWarning[]: Non-fatal apply warnings.
      - `code` string, required: Stable warning code.
      - `message` string, required: Human-readable warning message.
      - `path` string, required: Path to the affected storyboard document field.

## Other responses

- `400`: The storyboard document is invalid.
- `401`: Missing, malformed, expired, or revoked bearer token.
- `403`: The API key lacks the required scope or account capability.
- `404`: Project not found.
- `409`: The expected project version is stale.
- `422`: Validation Error
- `429`: The client or API key exceeded the REST API rate limit.
- `503`: The shared REST API rate limiter is temporarily unavailable.

---

[API](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api.md) · [All operations](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/revisions/239a74aa2c64?raw)