Storyboards

Update project storyboard

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.

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

Path parameters

project_idstring required

Headers

Idempotency-Keystring nullable
authorizationstring nullable

Request body

expectedVersioninteger required

Last project version observed by the client.

mode'replace' | 'append'

How to apply the storyboard document to the current project storyboard.

documentobject required

Kaitoi Storyboard Document v1 JSON to apply.

Example request

{
  "document": {
    "kaitoiType": "storyboard",
    "name": "Storyboard",
    "sequences": [
      {
        "id": "scene-1",
        "name": "Scene 1",
        "order": 0,
        "shots": [
          {
            "description": "A quiet establishing shot.",
            "durationSeconds": 3,
            "id": "frame-1",
            "order": 0,
            "transition": "cut"
          }
        ]
      }
    ],
    "settings": {
      "aspectRatio": "16:9",
      "defaultFrameDuration": 3
    },
    "version": 1
  },
  "expectedVersion": 7,
  "mode": "replace"
}

Response

Saved project storyboard document and apply summary.

projectIdstring required

Stable project identifier.

versioninteger required

New optimistic concurrency version after the write.

mode'replace' | 'append' required

Apply mode used for this write.

documentobject required

Resulting project storyboard exported as Kaitoi Storyboard Document v1.

Example response

{
  "document": {
    "kaitoiType": "storyboard",
    "name": "Storyboard",
    "sequences": [
      {
        "id": "scene-1",
        "name": "Scene 1",
        "order": 0,
        "shots": [
          {
            "description": "A quiet establishing shot.",
            "durationSeconds": 3,
            "id": "frame-1",
            "order": 0,
            "transition": "cut"
          }
        ]
      }
    ],
    "settings": {
      "aspectRatio": "16:9",
      "defaultFrameDuration": 3
    },
    "version": 1
  },
  "mode": "replace",
  "projectId": "proj_123",
  "summary": {
    "documentMedia": 0,
    "extraPanelMedia": 0,
    "mediaCount": 12,
    "mediaImported": 12,
    "mediaSkipped": 0,
    "sceneCount": 1,
    "shotCount": 12,
    "unresolvedMedia": 0,
    "urlMedia": 0,
    "warnings": []
  },
  "version": 8
}

Changes

No recorded changes to this operation across all 1 revision of this API.