Apply a canvas changeset

POST

/workspaces/{workspaceId}/projects/{projectId}/canvas/changeset

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

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

const canva = await client.projects.canvas.applyChangeset({
  workspaceId: '<workspaceId>',
  projectId: '<projectId>',
  add: [
    {
      ref: 'hero',
      type: 'image',
    },
  ],
  update: [
    {
      id: 'n7',
    },
  ],
  connect: [
    {
      from: 'n7',
      to: 'n7',
    },
  ],
  disconnect: [
    {
      from: 'n7',
      to: 'n7',
    },
  ],
  remove: [
    {
      id: 'n7',
    },
  ],
});
console.log(canva);

Edits a project canvas: add, update, connect, disconnect and remove operations validate together and apply as ONE atomic transaction. Nothing applies if any operation is invalid, and every cause is reported with a machine-readable code in the error’s fields array. 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. 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.

Error responses use the standard error body.

Authorizations

• bearerAuth

Parameters

Path Parameters

workspaceId

required

Workspace identifier

string

/^ws_\S+$/

Workspace identifier

projectId

required

Project identifier

string

/^prj_\S+$/

Project identifier

Request Body

Media type application/json

object

add

Nodes to create. Groups are created before their members.

Array<object>

<= 200 items

object

ref

required

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.

string

>= 1 characters <= 64 characters

type

required

Node type to create, in the agent vocabulary the graph read reports

string

Allowed values: image video text audio group static_image layer_editor

label

Display label pinned on the node

string

<= 500 characters

prompt

Generation prompt, stored in the node’s model parameters. Mutually exclusive with content_url.

string

model

Model name or endpoint id, as the graph read reports them. Omit to take the default model for the node’s modality.

string

params

Model parameters, validated against the model’s schema. Invalid values reject the whole changeset rather than being coerced.

object

key

additional properties

any

position

Absolute canvas position. Omit to place the node automatically below the existing canvas content.

object

x

required

Absolute horizontal canvas coordinate

number

y

required

Absolute vertical canvas coordinate

number

group

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.

string

content_url

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.

string format: uri

update

Existing nodes to modify. One operation per node.

Array<object>

<= 200 items

object

id

required

Node to modify: its short id or UUID

string

>= 1 characters <= 200 characters

label

Replacement display label

string

<= 500 characters

prompt

Replacement generation prompt

string

model

Replacement model name or endpoint id

string

params

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.

object

key

additional properties

any

position

New absolute canvas position

object

x

required

Absolute horizontal canvas coordinate

number

y

required

Absolute vertical canvas coordinate

number

connect

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.

Array<object>

<= 500 items

object

from

required

Source node reference

string

>= 1 characters <= 200 characters

to

required

Target node reference

string

>= 1 characters <= 200 characters

in

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.

string

disconnect

Edges to remove, addressed by their endpoints as the graph read reports them

Array<object>

<= 500 items

object

from

required

Source node reference

string

>= 1 characters <= 200 characters

to

required

Target node reference

string

>= 1 characters <= 200 characters

in

Input slot of the edge to remove; omit to remove every edge between the pair

string

remove

Nodes to delete. Their edges and any group members go too. Removal is immediate and cannot be undone through the API.

Array<object>

<= 200 items

object

id

required

Node to delete: its short id or UUID

string

>= 1 characters <= 200 characters

Responses

200

Changeset applied.

Media type application/json

object

project_id

required

Project identifier

string

/^prj_\S+$/

canvas_url

required

Project canvas URL

string format: uri

created

required

Each add operation’s ref mapped to the ids of the node it created

object

key

additional properties

object

id

required

Short id the created node answers to from now on

string

>= 1 characters

node_id

required

Created node UUID

string

>= 1 characters

applied

required

What the transaction actually did

object

added

required

Nodes created

integer

updated

required

Update operations that changed at least one field

integer

connected

required

Edges created

integer

disconnected

required

Edges removed

integer

removed

required

Nodes deleted, including group members deleted with their frame

integer

revision

required

Change-detection marker of the canvas after this changeset, identical to the value the project graph endpoint reports

string

>= 1 characters

warnings

required

Operations that resolved but did not change what the caller may have expected, such as an update matching current state or a duplicate connect

Array<string>

Example

{
  "project_id": "prj_abc123",
  "created": {
    "additionalProperty": {
      "id": "n9",
      "node_id": "7f6ae6da-4a0e-4a2f-9c6a-2c1c6b8d1f21"
    }
  },
  "revision": "4f2c8ab19e3d7c05"
}