> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/api/reference/canvas/applycanvaschangeset.md).

# Apply a canvas changeset

Apply a canvas changeset with the FLORA API: POST /workspaces/{workspaceId}/projects/{projectId}/canvas/changeset.

Edits a project canvas: add, update, connect, disconnect and remove operations validate together before writes begin. Invalid operations reject the request, and every cause is reported with a machine-readable code in the error's fields array. Authored content lives in `document`: an add of type timeline or deck may carry one, and an update replaces a timeline or deck document wholesale, guarded by base\_revision so a write based on a stale read is rejected with revision\_conflict instead of overwriting someone else's edit. Documents are validated against their authoring limits. Deck updates require base\_revision and compare it against the live collaborative document; simultaneous collaborators and undo retain the editor's existing semantics. Deck content and Timeline drafts use separate storage, so a mixed changeset is not a cross-store transaction. Deck writes do not render or export a presentation. Operations apply in the order add, update, connect, disconnect, remove, with groups created before their members — so one call can create a group, fill it, wire the new nodes to existing ones by the ref names it chose, and delete something else. An update can move an existing node into a group frame or out to the top level (group) without moving it on the canvas, and can replace a static image, video, or audio node's media in place (content\_url or asset\_id) while keeping its id and edges; a media replacement overwrites what the node showed. Nodes are addressed by the short id or node UUID the project graph endpoint reports, or by a ref declared by an add operation in the same request. REMOVE IS IMMEDIATE AND IRREVERSIBLE through the API: there is no confirmation step and no undo, deleting a node also deletes its edges and any group members, so confirm destructive changesets with your user before sending them. The revision returned is the same change-detection marker the project graph endpoint reports, so it can be compared directly against a later read. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency\_duplicate.

```http
POST https://app.flora.ai/api/v1/workspaces/{workspaceId}/projects/{projectId}/canvas/changeset
```

* **Auth:** API key as a bearer token, `Authorization: Bearer $FLORA_API_KEY`. See [Authentication](https://docs.flora.ai/api/platform/authentication.md).
* **TypeScript SDK:** `client.projects.canvas.applyChangeset()`.
* **Idempotency:** optional `Idempotency-Key` header. See [Idempotency](https://docs.flora.ai/api/platform/idempotency.md).
* **Operation ID:** `applyCanvasChangeset`.

## Example

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST 'https://app.flora.ai/api/v1/workspaces/ws_abc123/projects/prj_abc123/canvas/changeset' \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "add": [
    {
      "ref": "hero",
      "type": "image"
    }
  ]
}'
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
import { FloraClient } from '@flora-ai/flora';

const client = new FloraClient({ apiKey: process.env['FLORA_API_KEY'] });

const canvas = await client.projects.canvas.applyChangeset({
  workspaceId: 'ws_abc123',
  projectId: 'prj_abc123',
  add: [
    {
      ref: 'hero',
      type: 'image',
    },
  ],
});
console.log(canvas);
```

{% endtab %}
{% endtabs %}

## Path parameters

| Name          | Type   | Required | Description                                                      |
| ------------- | ------ | -------- | ---------------------------------------------------------------- |
| `workspaceId` | string | Yes      | Workspace identifier. Pattern: `^ws_\S+$`. Example: `ws_abc123`. |
| `projectId`   | string | Yes      | Project identifier. Pattern: `^prj_\S+$`. Example: `prj_abc123`. |

## Request body

Optional.

| Field                    | Type             | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `add`                    | array of objects | No       | Nodes to create. Groups are created before their members. At most 200 items.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `add[].ref`              | string           | Yes      | Caller-chosen handle for the new node, echoed back in created with its real ids. Usable as a connect or group target inside this same changeset. Must not collide with a live node id. 1 to 64 characters. Example: `hero`.                                                                                                                                                                                                                                                                                              |
| `add[].type`             | string           | Yes      | Node type to create, in the agent vocabulary the graph read reports. One of: `image`, `video`, `text`, `audio`, `timeline`, `deck`, `notes`, `group`, `static_image`, `layer_editor`.                                                                                                                                                                                                                                                                                                                                    |
| `add[].label`            | string           | No       | Display label pinned on the node. At most 500 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `add[].prompt`           | string           | No       | Generation prompt, stored in the node's model parameters. Mutually exclusive with content\_url.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `add[].model`            | string           | No       | Model name or endpoint id, as the graph read reports them. Omit to take the default model for the node's modality.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `add[].params`           | object           | No       | Model parameters, validated against the model's schema. Invalid values reject the whole changeset rather than being coerced.                                                                                                                                                                                                                                                                                                                                                                                             |
| `add[].position`         | object           | No       | Absolute canvas position. Omit to place the node automatically below the existing canvas content.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `add[].position.x`       | number           | Yes      | Absolute horizontal canvas coordinate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `add[].position.y`       | number           | Yes      | Absolute vertical canvas coordinate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `add[].group`            | string           | No       | Group to parent this node into: an existing group's short id or UUID, or the ref of a group created by this same changeset. Not accepted on notes nodes (a note documents the canvas and always stays at the top level — place it beside the frame with position) or on group nodes (frames do not nest); either rejects the whole changeset.                                                                                                                                                                            |
| `add[].content_url`      | string (uri)     | No       | HTTPS URL of existing image, video, or audio to place instead of generating. The media is copied onto Flora's CDN and the node becomes a static block. Mutually exclusive with prompt, model, and params.                                                                                                                                                                                                                                                                                                                |
| `add[].document`         | object           | No       | Authored content for a timeline or deck node: the whole document, validated with the workspace's own limits before anything is written. document.kind must match the node type ("timeline" or "deck"). Rejected on every other node type. A timeline created without a document has nothing to render until one is written with an update. See the `add[].document` shapes below.                                                                                                                                        |
| `add[].text`             | string           | No       | Body of a notes node: plain text, newlines significant, at most 20000 characters. Notes are canvas documentation — they generate nothing and spend nothing. Rejected on every other node type, which take prompt instead. At most 20000 characters.                                                                                                                                                                                                                                                                      |
| `add[].size`             | object           | No       | Box of a notes node in canvas pixels. Either or both of width/height; an omitted side keeps its current (or default 320x240) value. Clamped range width 200–1024, height 120–1024; values outside reject the changeset. Rejected on every other node type.                                                                                                                                                                                                                                                               |
| `add[].size.width`       | number           | No       | Note width in canvas pixels. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `add[].size.height`      | number           | No       | Note height in canvas pixels. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `add[].fit_text`         | boolean          | No       | Notes only: size the height so the whole text body is visible without internal scrolling at the note's width (the width from size, else its current width). Computed from the note's text after any text in this same operation is applied; capped at the maximum height, with a warning when the text still overflows. Rejected on every other node type.                                                                                                                                                               |
| `update`                 | array of objects | No       | Existing nodes to modify. One operation per node. At most 200 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `update[].id`            | string           | Yes      | Node to modify: its short id or UUID. 1 to 200 characters. Example: `n7`.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `update[].label`         | string           | No       | Replacement display label. At most 500 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `update[].prompt`        | string           | No       | Replacement generation prompt                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `update[].model`         | string           | No       | Replacement model name or endpoint id                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `update[].params`        | object           | No       | Model parameters, merged key by key into the node's stored parameters. Omitted keys survive; a named key is overwritten. On an action node these are the action's own parameter values.                                                                                                                                                                                                                                                                                                                                  |
| `update[].position`      | object           | No       | New absolute canvas position                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `update[].position.x`    | number           | Yes      | Absolute horizontal canvas coordinate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `update[].position.y`    | number           | Yes      | Absolute vertical canvas coordinate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `update[].document`      | object           | No       | Replacement document for a timeline or deck node, whole-document: read it, modify it, write it back. Validated with the workspace's own limits before anything is applied. Deck replacements require base\_revision. Rejected on nodes that carry no document. Mutually exclusive with commands. Same shape as `add[].document`.                                                                                                                                                                                         |
| `update[].commands`      | array of objects | No       | Scoped edits to a Deck node, applied in order to the slides and layers they name — a single layer or slide changes without resending the whole document. Deck nodes only; requires base\_revision like a document replacement, and mutually exclusive with document. A command that cannot apply (unknown slide or layer, duplicate layer id, last-slide removal, limits) rejects the whole changeset naming the command by index. 1 to 201 items. See the `update[].commands[]` shapes below.                           |
| `update[].base_revision` | integer          | No       | The document revision read before editing. Required for Deck replacements and command batches. A differing observed revision returns revision\_conflict; read again and reapply the intended edit. Deck revisions follow real-time collaboration and undo and do not serialize simultaneous writers. Only meaningful alongside document or commands; 0 is an empty Deck's initial revision or a Timeline with no document yet. At least 0.                                                                               |
| `update[].text`          | string           | No       | Replacement body for a notes node, whole-body: at most 20000 characters. Rejected on nodes that carry no annotation body. At most 20000 characters.                                                                                                                                                                                                                                                                                                                                                                      |
| `update[].size`          | object           | No       | Box of a notes node in canvas pixels. Either or both of width/height; an omitted side keeps its current (or default 320x240) value. Clamped range width 200–1024, height 120–1024; values outside reject the changeset. Rejected on every other node type.                                                                                                                                                                                                                                                               |
| `update[].size.width`    | number           | No       | Note width in canvas pixels. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `update[].size.height`   | number           | No       | Note height in canvas pixels. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `update[].fit_text`      | boolean          | No       | Notes only: size the height so the whole text body is visible without internal scrolling at the note's width (the width from size, else its current width). Computed from the note's text after any text in this same operation is applied; capped at the maximum height, with a warning when the text still overflows. Rejected on every other node type.                                                                                                                                                               |
| `update[].group`         | string or null   | No       | Group frame to move this node into, by an existing group's short id or UUID, or null to move it out of its group to the top level. Omit to leave membership unchanged. The node keeps its canvas spot unless position is also given (absolute), and a frame it joins grows to wrap it. Rejected on group nodes (frames do not nest), on a notes node joining a group, on a node attached to another node (a pinned label follows its host), and for a group this same changeset creates or removes. 1 to 200 characters. |
| `update[].content_url`   | string (uri)     | No       | HTTPS URL of an image, video, or audio file that replaces the media of a static image, video, or audio node in place; the node keeps its id, edges, group, and label (unless group or label is also given). The file is copied onto Flora's CDN as on an add. Mutually exclusive with asset\_id, prompt, model, params, document, text, size, and fit\_text.                                                                                                                                                             |
| `update[].asset_id`      | string           | No       | A ready asset in this project's workspace that replaces the media of a static image, video, or audio node in place, keeping the node's id, edges, group, and label (unless group or label is also given). Its kind must match the node's. The asset is referenced, not copied or deleted. Mutually exclusive with content\_url, prompt, model, params, document, text, size, and fit\_text. Pattern: `^asset_\S+$`. Example: `asset_abc123`.                                                                             |
| `connect`                | array of objects | No       | Edges to create. Either endpoint may be a ref created by this same changeset. The canvas carries one edge per pair, so a duplicate pair is skipped with a warning. At most 500 items.                                                                                                                                                                                                                                                                                                                                    |
| `connect[].from`         | string           | Yes      | Source node reference. 1 to 200 characters. Example: `n7`.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `connect[].to`           | string           | Yes      | Target node reference. 1 to 200 characters. Example: `n7`.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `connect[].in`           | string           | No       | Target input slot, in the vocabulary the graph read reports: a modality word such as "image", a named action or technique input, or "enabled" for the boolean gate. Omit to let the target take the edge by modality.                                                                                                                                                                                                                                                                                                    |
| `disconnect`             | array of objects | No       | Edges to remove, addressed by their endpoints as the graph read reports them. At most 500 items.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `disconnect[].from`      | string           | Yes      | Source node reference. 1 to 200 characters. Example: `n7`.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `disconnect[].to`        | string           | Yes      | Target node reference. 1 to 200 characters. Example: `n7`.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `disconnect[].in`        | string           | No       | Input slot of the edge to remove; omit to remove every edge between the pair                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `remove`                 | array of objects | No       | Nodes to delete. Their edges and any group members go too. Removal is immediate and cannot be undone through the API. At most 200 items.                                                                                                                                                                                                                                                                                                                                                                                 |
| `remove[].id`            | string           | Yes      | Node to delete: its short id or UUID. 1 to 200 characters. Example: `n7`.                                                                                                                                                                                                                                                                                                                                                                                                                                                |

<details>

<summary>add[].document shapes</summary>

Field paths in this block are relative to `add[].document`.

`add[].document` takes one of 2 shapes, set by `kind`.

**Shape 1: `kind` is `timeline`.**

| Field                | Type             | Required | Description                                                                                                                                                                                                                               |
| -------------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind`               | string           | Yes      | Always `timeline`.                                                                                                                                                                                                                        |
| `schema_version`     | integer          | Yes      | Document schema version; currently 1. Exactly 1.                                                                                                                                                                                          |
| `fps`                | number           | Yes      | Frames per second of the composition. At least 0.                                                                                                                                                                                         |
| `composition_width`  | integer          | Yes      | Even number of pixels. At least 0.                                                                                                                                                                                                        |
| `composition_height` | integer          | Yes      | Even number of pixels. At least 0.                                                                                                                                                                                                        |
| `tracks`             | array of objects | Yes      | Lanes, first is the bottom-most. 1 to 100 items.                                                                                                                                                                                          |
| `tracks[].id`        | string           | Yes      | Caller-chosen identifier; survives verbatim and is how other fields refer to it. 1 to 200 characters.                                                                                                                                     |
| `tracks[].name`      | string           | No       | Display name of the lane. At most 200 characters.                                                                                                                                                                                         |
| `tracks[].items`     | array of string  | Yes      | Item ids in this lane, bottom to top of the z-order. Every id must exist in `items`.                                                                                                                                                      |
| `tracks[].hidden`    | boolean          | No       | Default: `false`.                                                                                                                                                                                                                         |
| `tracks[].muted`     | boolean          | No       | Default: `false`.                                                                                                                                                                                                                         |
| `items`              | map of object    | Yes      | Clips keyed by item id. At least one item is required. Keys: caller-chosen identifier; survives verbatim and is how other fields refer to it. 1 to 200 characters. See the `add[].document.items.{key}` shapes below.                     |
| `assets`             | map of object    | Yes      | Media keyed by asset id. Every media item's asset\_id must be a key here. Keys: caller-chosen identifier; survives verbatim and is how other fields refer to it. 1 to 200 characters. See the `add[].document.assets.{key}` shapes below. |

**Shape 2: `kind` is `deck`.** Authored Deck content: 1–200 slides, up to 256 layers per slide, and at most 4 MiB of UTF-8 JSON.

| Field                                      | Type              | Required | Description                                                                                      |
| ------------------------------------------ | ----------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `kind`                                     | string            | Yes      | Always `deck`.                                                                                   |
| `schema_version`                           | integer           | Yes      | Exactly 1.                                                                                       |
| `slides`                                   | array of objects  | Yes      | 1 to 200 items.                                                                                  |
| `slides[].id`                              | string            | Yes      | 1 to 128 characters.                                                                             |
| `slides[].hidden`                          | boolean           | No       | Default: `false`.                                                                                |
| `slides[].guides`                          | object            | No       | Default: `{"vertical": [], "horizontal": []}`.                                                   |
| `slides[].guides.vertical`                 | array of number   | Yes      | At most 100 items.                                                                               |
| `slides[].guides.horizontal`               | array of number   | Yes      | At most 100 items.                                                                               |
| `slides[].document`                        | object            | Yes      |                                                                                                  |
| `slides[].document.schema_version`         | integer           | Yes      | Exactly 1.                                                                                       |
| `slides[].document.frame`                  | object            | Yes      |                                                                                                  |
| `slides[].document.frame.pixel_width`      | integer           | Yes      | Exactly 1920.                                                                                    |
| `slides[].document.frame.pixel_height`     | integer           | Yes      | Exactly 1080.                                                                                    |
| `slides[].document.frame.fill`             | string            | No       |                                                                                                  |
| `slides[].document.frame.margins`          | object            | No       |                                                                                                  |
| `slides[].document.frame.margins.top`      | number            | Yes      |                                                                                                  |
| `slides[].document.frame.margins.right`    | number            | Yes      |                                                                                                  |
| `slides[].document.frame.margins.bottom`   | number            | Yes      |                                                                                                  |
| `slides[].document.frame.margins.left`     | number            | Yes      |                                                                                                  |
| `slides[].document.frame.content_offset`   | object            | No       |                                                                                                  |
| `slides[].document.frame.content_offset.x` | number            | Yes      |                                                                                                  |
| `slides[].document.frame.content_offset.y` | number            | Yes      |                                                                                                  |
| `slides[].document.frame.crop_transform`   | map of JSON value | No       |                                                                                                  |
| `slides[].document.layer_order`            | array of string   | Yes      | At most 256 items.                                                                               |
| `slides[].document.layers`                 | map of object     | Yes      | Keys: 1 to 128 characters. See the `add[].document.slides[].document.layers.{key}` shapes below. |

`add[].document.items.{key}` takes one of 7 shapes, set by `type`.

Fields every shape has:

| Field                            | Type    | Required | Description                                                                                           |
| -------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `items.{key}.id`                 | string  | Yes      | Caller-chosen identifier; survives verbatim and is how other fields refer to it. 1 to 200 characters. |
| `items.{key}.from`               | integer | Yes      | Start frame on the composition timeline. Frames, not seconds. At least 0.                             |
| `items.{key}.duration_in_frames` | integer | Yes      | Length in frames. The cut is never guessed from the media. At least 0.                                |
| `items.{key}.top`                | number  | No       | Top edge in composition pixels                                                                        |
| `items.{key}.left`               | number  | No       | Left edge in composition pixels                                                                       |
| `items.{key}.width`              | number  | No       | Width in composition pixels. At least 0.                                                              |
| `items.{key}.height`             | number  | No       | Height in composition pixels. At least 0.                                                             |
| `items.{key}.opacity`            | number  | No       | Default: `1`. 0 to 1.                                                                                 |

Fields that depend on the shape:

**Shape 1: `type` is `video`.**

| Field                                            | Type    | Required | Description                                                                            |
| ------------------------------------------------ | ------- | -------- | -------------------------------------------------------------------------------------- |
| `items.{key}.type`                               | string  | Yes      | Always `video`.                                                                        |
| `items.{key}.asset_id`                           | string  | Yes      | Key of a video asset in `assets`. 1 to 200 characters.                                 |
| `items.{key}.video_start_from_in_seconds`        | number  | No       | Offset into the source video where playback starts. Seconds. Default: `0`. At least 0. |
| `items.{key}.decibel_adjustment`                 | number  | No       | Gain in dB; 0 leaves the source as is. Default: `0`.                                   |
| `items.{key}.playback_rate`                      | number  | No       | Speed multiplier; 1 is real time. Default: `1`. At least 0.                            |
| `items.{key}.audio_fade_in_duration_in_seconds`  | number  | No       | Default: `0`. At least 0.                                                              |
| `items.{key}.audio_fade_out_duration_in_seconds` | number  | No       | Default: `0`. At least 0.                                                              |
| `items.{key}.fade_in_duration_in_seconds`        | number  | No       | Visual fade-in length in seconds. Default: `0`. At least 0.                            |
| `items.{key}.fade_out_duration_in_seconds`       | number  | No       | Visual fade-out length in seconds. Default: `0`. At least 0.                           |
| `items.{key}.crop_left`                          | number  | No       | Fraction of the item cropped from the left. Default: `0`. 0 to 1.                      |
| `items.{key}.crop_top`                           | number  | No       | Fraction of the item cropped from the top. Default: `0`. 0 to 1.                       |
| `items.{key}.crop_right`                         | number  | No       | Fraction of the item cropped from the right. Default: `0`. 0 to 1.                     |
| `items.{key}.crop_bottom`                        | number  | No       | Fraction of the item cropped from the bottom. Default: `0`. 0 to 1.                    |
| `items.{key}.border_radius`                      | number  | No       | Corner radius in composition pixels. Default: `0`. At least 0.                         |
| `items.{key}.rotation`                           | number  | No       | Rotation in degrees. Default: `0`.                                                     |
| `items.{key}.keep_aspect_ratio`                  | boolean | No       | Default: `true`.                                                                       |

**Shape 2: `type` is `image`.**

| Field                                      | Type    | Required | Description                                                         |
| ------------------------------------------ | ------- | -------- | ------------------------------------------------------------------- |
| `items.{key}.type`                         | string  | Yes      | Always `image`.                                                     |
| `items.{key}.asset_id`                     | string  | Yes      | Key of an image asset in `assets`. 1 to 200 characters.             |
| `items.{key}.fade_in_duration_in_seconds`  | number  | No       | Visual fade-in length in seconds. Default: `0`. At least 0.         |
| `items.{key}.fade_out_duration_in_seconds` | number  | No       | Visual fade-out length in seconds. Default: `0`. At least 0.        |
| `items.{key}.crop_left`                    | number  | No       | Fraction of the item cropped from the left. Default: `0`. 0 to 1.   |
| `items.{key}.crop_top`                     | number  | No       | Fraction of the item cropped from the top. Default: `0`. 0 to 1.    |
| `items.{key}.crop_right`                   | number  | No       | Fraction of the item cropped from the right. Default: `0`. 0 to 1.  |
| `items.{key}.crop_bottom`                  | number  | No       | Fraction of the item cropped from the bottom. Default: `0`. 0 to 1. |
| `items.{key}.border_radius`                | number  | No       | Corner radius in composition pixels. Default: `0`. At least 0.      |
| `items.{key}.rotation`                     | number  | No       | Rotation in degrees. Default: `0`.                                  |
| `items.{key}.keep_aspect_ratio`            | boolean | No       | Default: `true`.                                                    |

**Shape 3: `type` is `gif`.**

| Field                                      | Type    | Required | Description                                                         |
| ------------------------------------------ | ------- | -------- | ------------------------------------------------------------------- |
| `items.{key}.type`                         | string  | Yes      | Always `gif`.                                                       |
| `items.{key}.asset_id`                     | string  | Yes      | Key of a gif asset in `assets`. 1 to 200 characters.                |
| `items.{key}.gif_start_from_in_seconds`    | number  | No       | Default: `0`. At least 0.                                           |
| `items.{key}.playback_rate`                | number  | No       | Default: `1`. At least 0.                                           |
| `items.{key}.fade_in_duration_in_seconds`  | number  | No       | Visual fade-in length in seconds. Default: `0`. At least 0.         |
| `items.{key}.fade_out_duration_in_seconds` | number  | No       | Visual fade-out length in seconds. Default: `0`. At least 0.        |
| `items.{key}.crop_left`                    | number  | No       | Fraction of the item cropped from the left. Default: `0`. 0 to 1.   |
| `items.{key}.crop_top`                     | number  | No       | Fraction of the item cropped from the top. Default: `0`. 0 to 1.    |
| `items.{key}.crop_right`                   | number  | No       | Fraction of the item cropped from the right. Default: `0`. 0 to 1.  |
| `items.{key}.crop_bottom`                  | number  | No       | Fraction of the item cropped from the bottom. Default: `0`. 0 to 1. |
| `items.{key}.border_radius`                | number  | No       | Corner radius in composition pixels. Default: `0`. At least 0.      |
| `items.{key}.rotation`                     | number  | No       | Rotation in degrees. Default: `0`.                                  |
| `items.{key}.keep_aspect_ratio`            | boolean | No       | Default: `true`.                                                    |

**Shape 4: `type` is `audio`.**

| Field                                            | Type   | Required | Description                                                                            |
| ------------------------------------------------ | ------ | -------- | -------------------------------------------------------------------------------------- |
| `items.{key}.type`                               | string | Yes      | Always `audio`.                                                                        |
| `items.{key}.asset_id`                           | string | Yes      | Key of an audio asset in `assets`. 1 to 200 characters.                                |
| `items.{key}.audio_start_from_in_seconds`        | number | No       | Offset into the source audio where playback starts. Seconds. Default: `0`. At least 0. |
| `items.{key}.decibel_adjustment`                 | number | No       | Gain in dB; 0 leaves the source as is. Default: `0`.                                   |
| `items.{key}.playback_rate`                      | number | No       | Speed multiplier; 1 is real time. Default: `1`. At least 0.                            |
| `items.{key}.audio_fade_in_duration_in_seconds`  | number | No       | Default: `0`. At least 0.                                                              |
| `items.{key}.audio_fade_out_duration_in_seconds` | number | No       | Default: `0`. At least 0.                                                              |

**Shape 5: `type` is `solid`.**

| Field                                      | Type    | Required | Description                                                    |
| ------------------------------------------ | ------- | -------- | -------------------------------------------------------------- |
| `items.{key}.type`                         | string  | Yes      | Always `solid`.                                                |
| `items.{key}.color`                        | string  | Yes      | CSS color of the rectangle. At least 1 character.              |
| `items.{key}.fade_in_duration_in_seconds`  | number  | No       | Visual fade-in length in seconds. Default: `0`. At least 0.    |
| `items.{key}.fade_out_duration_in_seconds` | number  | No       | Visual fade-out length in seconds. Default: `0`. At least 0.   |
| `items.{key}.border_radius`                | number  | No       | Corner radius in composition pixels. Default: `0`. At least 0. |
| `items.{key}.rotation`                     | number  | No       | Rotation in degrees. Default: `0`.                             |
| `items.{key}.keep_aspect_ratio`            | boolean | No       | Default: `false`.                                              |

**Shape 6: `type` is `text`.**

| Field                                       | Type           | Required | Description                                                                                                              |
| ------------------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `items.{key}.type`                          | string         | Yes      | Always `text`.                                                                                                           |
| `items.{key}.text`                          | string         | Yes      | At least 1 character.                                                                                                    |
| `items.{key}.color`                         | string         | No       | CSS color. Default: `#ffffff`. At least 1 character.                                                                     |
| `items.{key}.align`                         | string         | No       | One of: `left`, `center`, `right`. Default: `center`.                                                                    |
| `items.{key}.font_family`                   | string         | No       | Google Fonts family name. Default: `Roboto`. At least 1 character.                                                       |
| `items.{key}.font_style`                    | object         | No       | Font variant ("normal" or "italic") and CSS weight ("400", "700", …). Default: `{"variant": "normal", "weight": "400"}`. |
| `items.{key}.font_style.variant`            | string         | Yes      | At least 1 character.                                                                                                    |
| `items.{key}.font_style.weight`             | string         | Yes      | At least 1 character.                                                                                                    |
| `items.{key}.font_size`                     | number         | No       | Font size in composition pixels. Default: `80`. At least 0.                                                              |
| `items.{key}.line_height`                   | number         | No       | Line height as a multiplier. Default: `1.2`. At least 0.                                                                 |
| `items.{key}.letter_spacing`                | number         | No       | Letter spacing in composition pixels. Default: `0`.                                                                      |
| `items.{key}.direction`                     | string         | No       | One of: `ltr`, `rtl`. Default: `ltr`.                                                                                    |
| `items.{key}.stroke_width`                  | number         | No       | Text outline width in composition pixels. Default: `0`. At least 0.                                                      |
| `items.{key}.stroke_color`                  | string         | No       | CSS color. Default: `#000000`. At least 1 character.                                                                     |
| `items.{key}.background`                    | object or null | No       | Rounded box painted behind the text, or null for none                                                                    |
| `items.{key}.background.color`              | string         | Yes      | At least 1 character.                                                                                                    |
| `items.{key}.background.horizontal_padding` | number         | Yes      | At least 0.                                                                                                              |
| `items.{key}.background.border_radius`      | number         | Yes      | At least 0.                                                                                                              |
| `items.{key}.resize_on_edit`                | boolean        | No       | Editor behavior: true re-measures the box when the text changes. Default: `false`.                                       |
| `items.{key}.rotation`                      | number         | No       | Rotation in degrees. Default: `0`.                                                                                       |
| `items.{key}.fade_in_duration_in_seconds`   | number         | No       | Visual fade-in length in seconds. Default: `0`. At least 0.                                                              |
| `items.{key}.fade_out_duration_in_seconds`  | number         | No       | Visual fade-out length in seconds. Default: `0`. At least 0.                                                             |

**Shape 7: `type` is `captions`.**

| Field                                       | Type    | Required | Description                                                                                                              |
| ------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `items.{key}.type`                          | string  | Yes      | Always `captions`.                                                                                                       |
| `items.{key}.asset_id`                      | string  | Yes      | Key of a caption asset in `assets`. 1 to 200 characters.                                                                 |
| `items.{key}.color`                         | string  | No       | CSS color. Default: `#ffffff`. At least 1 character.                                                                     |
| `items.{key}.align`                         | string  | No       | One of: `left`, `center`, `right`. Default: `center`.                                                                    |
| `items.{key}.font_family`                   | string  | No       | Google Fonts family name. Default: `Roboto`. At least 1 character.                                                       |
| `items.{key}.font_style`                    | object  | No       | Font variant ("normal" or "italic") and CSS weight ("400", "700", …). Default: `{"variant": "normal", "weight": "400"}`. |
| `items.{key}.font_style.variant`            | string  | Yes      | At least 1 character.                                                                                                    |
| `items.{key}.font_style.weight`             | string  | Yes      | At least 1 character.                                                                                                    |
| `items.{key}.font_size`                     | number  | No       | Font size in composition pixels. Default: `80`. At least 0.                                                              |
| `items.{key}.line_height`                   | number  | No       | Line height as a multiplier. Default: `1.2`. At least 0.                                                                 |
| `items.{key}.letter_spacing`                | number  | No       | Letter spacing in composition pixels. Default: `0`.                                                                      |
| `items.{key}.direction`                     | string  | No       | One of: `ltr`, `rtl`. Default: `ltr`.                                                                                    |
| `items.{key}.stroke_width`                  | number  | No       | Text outline width in composition pixels. Default: `0`. At least 0.                                                      |
| `items.{key}.stroke_color`                  | string  | No       | CSS color. Default: `#000000`. At least 1 character.                                                                     |
| `items.{key}.highlight_color`               | string  | No       | CSS color of the word being spoken. Default: `#39E508`. At least 1 character.                                            |
| `items.{key}.page_duration_in_milliseconds` | number  | No       | Default: `1200`. At least 0.                                                                                             |
| `items.{key}.caption_start_in_seconds`      | number  | No       | Default: `0`. At least 0.                                                                                                |
| `items.{key}.max_lines`                     | integer | No       | Default: `2`. At least 0.                                                                                                |
| `items.{key}.rotation`                      | number  | No       | Default: `0`.                                                                                                            |
| `items.{key}.fade_in_duration_in_seconds`   | number  | No       | Visual fade-in length in seconds. Default: `0`. At least 0.                                                              |
| `items.{key}.fade_out_duration_in_seconds`  | number  | No       | Visual fade-out length in seconds. Default: `0`. At least 0.                                                             |

`add[].document.assets.{key}` takes one of 5 shapes, set by `type`.

Fields every shape has:

| Field                         | Type   | Required | Description                                                                                           |
| ----------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `assets.{key}.id`             | string | Yes      | Caller-chosen identifier; survives verbatim and is how other fields refer to it. 1 to 200 characters. |
| `assets.{key}.filename`       | string | No       | Display name in the editor. Defaults to the last path segment of media\_url. At least 1 character.    |
| `assets.{key}.mime_type`      | string | No       | Defaults from the asset type and the media\_url extension. At least 1 character.                      |
| `assets.{key}.source_node_id` | string | No       | Canvas node whose output seeded this asset, when known. Read-only.                                    |

Fields that depend on the shape:

**Shape 1: `type` is `video`.**

| Field                              | Type         | Required | Description                                                                                                        |
| ---------------------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `assets.{key}.type`                | string       | Yes      | Always `video`.                                                                                                    |
| `assets.{key}.media_url`           | string (uri) | Yes      | Durable https URL of the media the renderer fetches. Flora's own asset URLs and any public https URL are accepted. |
| `assets.{key}.width`               | number       | Yes      | Native media width in pixels. At least 0.                                                                          |
| `assets.{key}.height`              | number       | Yes      | Native media height in pixels. At least 0.                                                                         |
| `assets.{key}.duration_in_seconds` | number       | Yes      | At least 0.                                                                                                        |
| `assets.{key}.has_audio_track`     | boolean      | No       | Default: `false`.                                                                                                  |

**Shape 2: `type` is `image`.**

| Field                    | Type         | Required | Description                                                                                                        |
| ------------------------ | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `assets.{key}.type`      | string       | Yes      | Always `image`.                                                                                                    |
| `assets.{key}.media_url` | string (uri) | Yes      | Durable https URL of the media the renderer fetches. Flora's own asset URLs and any public https URL are accepted. |
| `assets.{key}.width`     | number       | Yes      | Native media width in pixels. At least 0.                                                                          |
| `assets.{key}.height`    | number       | Yes      | Native media height in pixels. At least 0.                                                                         |

**Shape 3: `type` is `gif`.**

| Field                              | Type         | Required | Description                                                                                                        |
| ---------------------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `assets.{key}.type`                | string       | Yes      | Always `gif`.                                                                                                      |
| `assets.{key}.media_url`           | string (uri) | Yes      | Durable https URL of the media the renderer fetches. Flora's own asset URLs and any public https URL are accepted. |
| `assets.{key}.width`               | number       | Yes      | Native media width in pixels. At least 0.                                                                          |
| `assets.{key}.height`              | number       | Yes      | Native media height in pixels. At least 0.                                                                         |
| `assets.{key}.duration_in_seconds` | number       | Yes      | At least 0.                                                                                                        |

**Shape 4: `type` is `audio`.**

| Field                              | Type         | Required | Description                                                                                                        |
| ---------------------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `assets.{key}.type`                | string       | Yes      | Always `audio`.                                                                                                    |
| `assets.{key}.media_url`           | string (uri) | Yes      | Durable https URL of the media the renderer fetches. Flora's own asset URLs and any public https URL are accepted. |
| `assets.{key}.duration_in_seconds` | number       | Yes      | At least 0.                                                                                                        |

**Shape 5: `type` is `caption`.**

| Field                                  | Type             | Required | Description       |
| -------------------------------------- | ---------------- | -------- | ----------------- |
| `assets.{key}.type`                    | string           | Yes      | Always `caption`. |
| `assets.{key}.captions`                | array of objects | Yes      | At least 1 item.  |
| `assets.{key}.captions[].text`         | string           | Yes      |                   |
| `assets.{key}.captions[].start_ms`     | number           | Yes      | At least 0.       |
| `assets.{key}.captions[].end_ms`       | number           | Yes      | At least 0.       |
| `assets.{key}.captions[].timestamp_ms` | number or null   | No       |                   |
| `assets.{key}.captions[].confidence`   | number or null   | No       |                   |

`add[].document.slides[].document.layers.{key}` takes one of 3 shapes, set by `content_type`.

Fields every shape has:

| Field                                                 | Type          | Required | Description                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slides[].document.layers.{key}.id`                   | string        | Yes      | 1 to 128 characters.                                                                                                                                                                                                                                                                                                                                                                        |
| `slides[].document.layers.{key}.name`                 | string        | No       | Default: `""`.                                                                                                                                                                                                                                                                                                                                                                              |
| `slides[].document.layers.{key}.visible`              | boolean       | No       | Default: `true`.                                                                                                                                                                                                                                                                                                                                                                            |
| `slides[].document.layers.{key}.locked`               | boolean       | No       |                                                                                                                                                                                                                                                                                                                                                                                             |
| `slides[].document.layers.{key}.transform`            | object        | Yes      |                                                                                                                                                                                                                                                                                                                                                                                             |
| `slides[].document.layers.{key}.transform.position`   | object        | Yes      |                                                                                                                                                                                                                                                                                                                                                                                             |
| `slides[].document.layers.{key}.transform.position.x` | number        | Yes      |                                                                                                                                                                                                                                                                                                                                                                                             |
| `slides[].document.layers.{key}.transform.position.y` | number        | Yes      |                                                                                                                                                                                                                                                                                                                                                                                             |
| `slides[].document.layers.{key}.transform.scale`      | object        | Yes      | Dimensionless size multipliers. Text uses frame.pixel\_width by round(font\_size \* 7.5) as its reference box (font\_size defaults to 144); shapes use 512 by 512; media uses its resolved source dimensions. Divide the desired pixel width and height by the reference dimensions. For a 1200 by 240 text box at font\_size 96 on a 1920-wide frame, use x: 0.625, y: 0.3333333333333333. |
| `slides[].document.layers.{key}.transform.scale.x`    | number        | Yes      |                                                                                                                                                                                                                                                                                                                                                                                             |
| `slides[].document.layers.{key}.transform.scale.y`    | number        | Yes      |                                                                                                                                                                                                                                                                                                                                                                                             |
| `slides[].document.layers.{key}.transform.rotation`   | number        | No       |                                                                                                                                                                                                                                                                                                                                                                                             |
| `slides[].document.layers.{key}.transform.opacity`    | number        | No       | 0 to 1.                                                                                                                                                                                                                                                                                                                                                                                     |
| `slides[].document.layers.{key}.blend_mode`           | string        | No       | One of: `normal`, `dissolve`, `darken`, `multiply`, `color-burn`, `linear-burn`, `darker-color`, `lighten`, `screen`, `color-dodge`, `linear-dodge`, `lighter-color`, `overlay`, `soft-light`, `hard-light`, `vivid-light`, `linear-light`, `pin-light`, `hard-mix`, `difference`, `exclusion`, `subtract`, `divide`, `hue`, `saturation`, `color`, `luminosity`.                           |
| `slides[].document.layers.{key}.fill`                 | string        | No       |                                                                                                                                                                                                                                                                                                                                                                                             |
| `slides[].document.layers.{key}.adjustments`          | map of number | No       |                                                                                                                                                                                                                                                                                                                                                                                             |

Fields that depend on the shape:

**Shape 1: `content_type` is `text`.**

| Field                                                          | Type           | Required | Description                                                                           |
| -------------------------------------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------- |
| `slides[].document.layers.{key}.content_type`                  | string         | Yes      | Always `text`.                                                                        |
| `slides[].document.layers.{key}.content`                       | object         | Yes      | See the `add[].document.slides[].document.layers.{key}.content` shapes below.         |
| `slides[].document.layers.{key}.text_data`                     | object         | No       | Typography only; the rendered text or live binding belongs in content. Default: `{}`. |
| `slides[].document.layers.{key}.text_data.font_family`         | string         | No       |                                                                                       |
| `slides[].document.layers.{key}.text_data.font_size`           | number         | No       | At least 0.                                                                           |
| `slides[].document.layers.{key}.text_data.text_color`          | string         | No       |                                                                                       |
| `slides[].document.layers.{key}.text_data.font_weight`         | number         | No       | 1 to 1000.                                                                            |
| `slides[].document.layers.{key}.text_data.font_style`          | string         | No       | One of: `normal`, `italic`.                                                           |
| `slides[].document.layers.{key}.text_data.text_align`          | string         | No       | One of: `left`, `center`, `right`.                                                    |
| `slides[].document.layers.{key}.text_data.text_vertical_align` | string         | No       | One of: `top`, `middle`, `bottom`.                                                    |
| `slides[].document.layers.{key}.text_data.line_height`         | number or null | No       | At least 0.                                                                           |
| `slides[].document.layers.{key}.text_data.letter_spacing`      | number         | No       |                                                                                       |
| `slides[].document.layers.{key}.text_data.kerning`             | map of number  | No       |                                                                                       |
| `slides[].document.layers.{key}.text_data.custom_font_id`      | string         | No       |                                                                                       |
| `slides[].document.layers.{key}.text_data.auto_width`          | boolean        | No       |                                                                                       |

**Shape 2: `content_type` is `shape`.**

| Field                                          | Type   | Required | Description                             |
| ---------------------------------------------- | ------ | -------- | --------------------------------------- |
| `slides[].document.layers.{key}.content_type`  | string | Yes      | Always `shape`.                         |
| `slides[].document.layers.{key}.primitive`     | string | Yes      | One of: `square`, `circle`, `triangle`. |
| `slides[].document.layers.{key}.shape_color`   | string | Yes      |                                         |
| `slides[].document.layers.{key}.line`          | object | No       |                                         |
| `slides[].document.layers.{key}.line.cap`      | string | No       | Always `round`.                         |
| `slides[].document.layers.{key}.corner_radius` | number | No       | At least 0.                             |

**Shape 3: `content_type` is `image`.**

| Field                                                     | Type              | Required | Description                                                                  |
| --------------------------------------------------------- | ----------------- | -------- | ---------------------------------------------------------------------------- |
| `slides[].document.layers.{key}.content_type`             | string            | Yes      | Always `image`.                                                              |
| `slides[].document.layers.{key}.source`                   | object            | Yes      | See the `add[].document.slides[].document.layers.{key}.source` shapes below. |
| `slides[].document.layers.{key}.source_dimensions`        | object            | No       |                                                                              |
| `slides[].document.layers.{key}.source_dimensions.width`  | number            | Yes      | At least 0.                                                                  |
| `slides[].document.layers.{key}.source_dimensions.height` | number            | Yes      | At least 0.                                                                  |
| `slides[].document.layers.{key}.fit`                      | string            | No       | One of: `contain`, `cover`, `stretch`.                                       |
| `slides[].document.layers.{key}.video`                    | object            | No       |                                                                              |
| `slides[].document.layers.{key}.video.autoplay`           | boolean           | No       |                                                                              |
| `slides[].document.layers.{key}.model3d`                  | object            | No       |                                                                              |
| `slides[].document.layers.{key}.model3d.view_state`       | map of JSON value | No       |                                                                              |
| `slides[].document.layers.{key}.model3d.auto_rotate`      | boolean           | No       |                                                                              |

`add[].document.slides[].document.layers.{key}.content` takes one of 2 shapes, set by `kind`.

**Shape 1: `kind` is `node_output`.**

| Field                                               | Type   | Required | Description                                                                                                                              |
| --------------------------------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `slides[].document.layers.{key}.content.kind`       | string | Yes      | Always `node_output`.                                                                                                                    |
| `slides[].document.layers.{key}.content.node_id`    | string | Yes      | Source node UUID or short id in this project, or a node ref declared in the same request. Read responses use UUIDs. 1 to 128 characters. |
| `slides[].document.layers.{key}.content.output_key` | string | No       |                                                                                                                                          |

**Shape 2: `kind` is `inline`.**

| Field                                         | Type   | Required | Description      |
| --------------------------------------------- | ------ | -------- | ---------------- |
| `slides[].document.layers.{key}.content.kind` | string | Yes      | Always `inline`. |
| `slides[].document.layers.{key}.content.text` | string | Yes      |                  |

`add[].document.slides[].document.layers.{key}.source` takes one of 2 shapes, set by `kind`.

**Shape 1: `kind` is `node_output`.**

| Field                                              | Type   | Required | Description                                                                                                                              |
| -------------------------------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `slides[].document.layers.{key}.source.kind`       | string | Yes      | Always `node_output`.                                                                                                                    |
| `slides[].document.layers.{key}.source.node_id`    | string | Yes      | Source node UUID or short id in this project, or a node ref declared in the same request. Read responses use UUIDs. 1 to 128 characters. |
| `slides[].document.layers.{key}.source.output_key` | string | No       |                                                                                                                                          |

**Shape 2: `kind` is `asset`.**

| Field                                            | Type   | Required | Description                                     |
| ------------------------------------------------ | ------ | -------- | ----------------------------------------------- |
| `slides[].document.layers.{key}.source.kind`     | string | Yes      | Always `asset`.                                 |
| `slides[].document.layers.{key}.source.asset_id` | string | Yes      | Flora asset id (asset\_…). 1 to 128 characters. |

</details>

<details>

<summary>update[].commands[] shapes</summary>

Field paths in this block are relative to `update[].commands[]`.

`update[].commands[]` takes one of 12 shapes, set by `type`.

**Shape 1: `type` is `add_slide`.**

| Field            | Type   | Required | Description                                                            |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `type`           | string | Yes      | Insert a blank slide. Always `add_slide`.                              |
| `after_slide_id` | string | No       | Slide to insert after; omit to append at the end. 1 to 128 characters. |

**Shape 2: `type` is `duplicate_slide`.**

| Field      | Type   | Required | Description                                                    |
| ---------- | ------ | -------- | -------------------------------------------------------------- |
| `type`     | string | Yes      | Copy a slide, minting new layer ids. Always `duplicate_slide`. |
| `slide_id` | string | Yes      | Slide id. 1 to 128 characters.                                 |

**Shape 3: `type` is `remove_slide`.**

| Field      | Type   | Required | Description                                                      |
| ---------- | ------ | -------- | ---------------------------------------------------------------- |
| `type`     | string | Yes      | Delete a slide; the last one is rejected. Always `remove_slide`. |
| `slide_id` | string | Yes      | Slide id. 1 to 128 characters.                                   |

**Shape 4: `type` is `move_slide`.**

| Field      | Type    | Required | Description                                                    |
| ---------- | ------- | -------- | -------------------------------------------------------------- |
| `type`     | string  | Yes      | Reorder a slide to a zero-based position. Always `move_slide`. |
| `slide_id` | string  | Yes      | Slide id. 1 to 128 characters.                                 |
| `to_index` | integer | Yes      | 0 to 199.                                                      |

**Shape 5: `type` is `set_slide_hidden`.**

| Field      | Type    | Required | Description                                      |
| ---------- | ------- | -------- | ------------------------------------------------ |
| `type`     | string  | Yes      | Hide or show a slide. Always `set_slide_hidden`. |
| `slide_id` | string  | Yes      | Slide id. 1 to 128 characters.                   |
| `hidden`   | boolean | Yes      |                                                  |

**Shape 6: `type` is `set_slide_background`.**

| Field      | Type   | Required | Description                                            |
| ---------- | ------ | -------- | ------------------------------------------------------ |
| `type`     | string | Yes      | Set the frame fill. Always `set_slide_background`.     |
| `slide_id` | string | Yes      | Slide id. 1 to 128 characters.                         |
| `fill`     | string | Yes      | Hex color, e.g. #112233. Pattern: `^#[0-9a-fA-F]{6}$`. |

**Shape 7: `type` is `set_guides`.**

| Field       | Type            | Required | Description                                                                                                                           |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `type`      | string          | Yes      | Replace one axis' guide positions. Always `set_guides`.                                                                               |
| `slide_id`  | string          | Yes      | Slide id. 1 to 128 characters.                                                                                                        |
| `axis`      | string          | Yes      | One of: `vertical`, `horizontal`.                                                                                                     |
| `positions` | array of number | Yes      | Guide offsets in pixels; vertical guides are bounded by the 1920 slide width, horizontal by the 1080 slide height. At most 100 items. |

**Shape 8: `type` is `add_layers`.**

| Field      | Type             | Required | Description                                                                    |
| ---------- | ---------------- | -------- | ------------------------------------------------------------------------------ |
| `type`     | string           | Yes      | Insert layers into a slide's z-order. Always `add_layers`.                     |
| `slide_id` | string           | Yes      | Slide id. 1 to 128 characters.                                                 |
| `layers`   | array of objects | Yes      | 1 to 100 items. Same shape as `add[].document.slides[].document.layers.{key}`. |
| `at_index` | integer          | No       | Z-order position to insert at; omit to place on top. 0 to 256.                 |

**Shape 9: `type` is `update_layers`.**

| Field      | Type             | Required | Description                                                                        |
| ---------- | ---------------- | -------- | ---------------------------------------------------------------------------------- |
| `type`     | string           | Yes      | Replace whole layers by id, geometry and content included. Always `update_layers`. |
| `slide_id` | string           | Yes      | Slide id. 1 to 128 characters.                                                     |
| `layers`   | array of objects | Yes      | 1 to 100 items. Same shape as `add[].document.slides[].document.layers.{key}`.     |

**Shape 10: `type` is `update_layer_geometry`.**

| Field                  | Type             | Required | Description                                                                                 |
| ---------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------- |
| `type`                 | string           | Yes      | Move, scale and rotate existing layers in place. Always `update_layer_geometry`.            |
| `slide_id`             | string           | Yes      | Slide id. 1 to 128 characters.                                                              |
| `updates`              | array of objects | Yes      | 1 to 100 items.                                                                             |
| `updates[].layer_id`   | string           | Yes      | Layer id. 1 to 128 characters.                                                              |
| `updates[].position`   | object           | Yes      |                                                                                             |
| `updates[].position.x` | number           | Yes      |                                                                                             |
| `updates[].position.y` | number           | Yes      |                                                                                             |
| `updates[].scale`      | object           | Yes      | Dimensionless multipliers on the layer's reference box, same convention as layer transforms |
| `updates[].scale.x`    | number           | Yes      |                                                                                             |
| `updates[].scale.y`    | number           | Yes      |                                                                                             |
| `updates[].rotation`   | number           | Yes      |                                                                                             |

**Shape 11: `type` is `remove_layers`.**

| Field       | Type            | Required | Description                                         |
| ----------- | --------------- | -------- | --------------------------------------------------- |
| `type`      | string          | Yes      | Delete layers from a slide. Always `remove_layers`. |
| `slide_id`  | string          | Yes      | Slide id. 1 to 128 characters.                      |
| `layer_ids` | array of string | Yes      | 1 to 100 items.                                     |

**Shape 12: `type` is `reorder_layers`.**

| Field       | Type            | Required | Description                                                               |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------- |
| `type`      | string          | Yes      | Set a slide's layer z-order to the ids supplied. Always `reorder_layers`. |
| `slide_id`  | string          | Yes      | Slide id. 1 to 128 characters.                                            |
| `layer_ids` | array of string | Yes      | At most 256 items.                                                        |

</details>

## Responses

### 200: Changeset applied.

| Field                   | Type            | Required | Description                                                                                                                                                               |
| ----------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`            | string          | Yes      | Project identifier. Pattern: `^prj_\S+$`. Example: `prj_abc123`.                                                                                                          |
| `canvas_url`            | string (uri)    | Yes      | Project canvas URL                                                                                                                                                        |
| `created`               | map of object   | Yes      | Each add operation's ref mapped to the ids of the node it created                                                                                                         |
| `created.{key}.id`      | string          | Yes      | Short id the created node answers to from now on. At least 1 character. Example: `n9`.                                                                                    |
| `created.{key}.node_id` | string          | Yes      | Created node UUID. At least 1 character. Example: `7f6ae6da-4a0e-4a2f-9c6a-2c1c6b8d1f21`.                                                                                 |
| `applied`               | object          | Yes      | What the transaction actually did                                                                                                                                         |
| `applied.added`         | integer         | Yes      | Nodes created. At least 0.                                                                                                                                                |
| `applied.updated`       | integer         | Yes      | Update operations that changed at least one field. At least 0.                                                                                                            |
| `applied.connected`     | integer         | Yes      | Edges created. At least 0.                                                                                                                                                |
| `applied.disconnected`  | integer         | Yes      | Edges removed. At least 0.                                                                                                                                                |
| `applied.removed`       | integer         | Yes      | Nodes deleted, including group members deleted with their frame. At least 0.                                                                                              |
| `revision`              | string          | Yes      | Change-detection marker of the canvas after this changeset, identical to the value the project graph endpoint reports. At least 1 character. Example: `4f2c8ab19e3d7c05`. |
| `warnings`              | array of string | Yes      | Operations that resolved but did not change what the caller may have expected, such as an update matching current state or a duplicate connect                            |

## Errors

Every error has the same body: `error.code`, `error.message`, and `error.fields` on validation errors. See [Errors](https://docs.flora.ai/api/platform/errors.md) for how to recover from each code.

| Status | Code                                         | Meaning                                                                             |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------- |
| 400    | `invalid_json`, `input_validation_error`     | The body isn't valid JSON, or an input failed validation (`fields` lists each one). |
| 401    | `unauthorized`, `invalid_api_key`            | The API key is missing, invalid or revoked.                                         |
| 402    | `insufficient_credits`                       | The workspace balance is too low for this request.                                  |
| 403    | `forbidden`, `paid_plan_required`            | The key can't do this, or the workspace plan doesn't include it.                    |
| 404    | `not_found`                                  | The resource doesn't exist or isn't visible to this key.                            |
| 409    | `idempotency_duplicate`, `revision_conflict` | Duplicate `Idempotency-Key` or a stale `base_revision`.                             |
| 429    | `rate_limited`                               | Too many requests. Back off and retry.                                              |
| 500    | `unknown_error`, `internal_error`            | Something failed on FLORA's side. Retry with backoff.                               |
| 503    | `temporarily_unavailable`                    | Authorization is temporarily unavailable. Retry later.                              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/api/reference/canvas/applycanvaschangeset.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
