> 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/replaceprojectcanvasdefinition.md).

# Replace a canvas definition

Replace a canvas definition with the FLORA API: PUT /workspaces/{workspaceId}/projects/{projectId}/canvas/definition.

Validates and atomically replaces the complete project canvas definition. Supplied positions are preserved and omitted positions receive deterministic automatic layout. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency\_duplicate.

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

* **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.replaceDefinition()`.
* **Idempotency:** optional `Idempotency-Key` header. See [Idempotency](https://docs.flora.ai/api/platform/idempotency.md).
* **Operation ID:** `replaceProjectCanvasDefinition`.

## Example

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

```bash
curl -X PUT 'https://app.flora.ai/api/v1/workspaces/ws_abc123/projects/prj_abc123/canvas/definition' \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "definition": {
    "nodes": [
      {
        "id": "node_abc123",
        "type": "videoBlock",
        "data": {}
      }
    ],
    "edges": [
      {
        "id": "edge_abc123",
        "source": "<source>",
        "target": "<target>",
        "source_handle": "<source_handle>",
        "target_handle": "<target_handle>"
      }
    ],
    "node_inputs": {},
    "node_outputs": {}
  }
}'
```

{% 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.replaceDefinition({
  workspaceId: 'ws_abc123',
  projectId: 'prj_abc123',
  definition: {
    nodes: [
      {
        id: 'node_abc123',
        type: 'videoBlock',
        data: {},
      },
    ],
    edges: [
      {
        id: 'edge_abc123',
        source: '<source>',
        target: '<target>',
        source_handle: '<source_handle>',
        target_handle: '<target_handle>',
      },
    ],
    node_inputs: {},
    node_outputs: {},
  },
});
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

Required.

| Field                               | Type                                     | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------- | ---------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `definition`                        | object                                   | Yes      | Complete canvas definition to replace                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `definition.nodes`                  | array of objects                         | Yes      | Complete replacement canvas node list. At most 2000 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `definition.nodes[].id`             | string                                   | Yes      | Stable canvas node identifier. 1 to 200 characters. Example: `node_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `definition.nodes[].type`           | string                                   | Yes      | Flora canvas node type. One of: `videoBlock`, `textBlock`, `comment`, `group`, `ghost`, `virtualSourceNode`, `emptyImageBlock`, `outpaintImageBlock`, `inpaintImageBlock`, `staticImageBlock`, `staticVideoBlock`, `resultImageBlock`, `resultVideoBlock`, `resultTextBlock`, `audioBlock`, `resultAudioBlock`, `staticAudioBlock`, `techniqueBlock`, `layerEditorNode`, `videoEditorNode`, `collectionNode`, `routerNode`, `switchNode`, `elementNode`, `textLabel`, `notes`, `codeBlock`, `documentNode`, `deckNode`, `exportNode`, `webcamNode`, `claudeNode`, `model3dNode`. |
| `definition.nodes[].data`           | object                                   | Yes      | Durable public node configuration; transient collaboration state is omitted                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `definition.nodes[].parent_id`      | string                                   | No       | Parent group node identifier. 1 to 200 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `definition.nodes[].extent`         | string or array of 2 array of 2 numberss | No       | Optional React Flow movement extent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `definition.nodes[].expand_parent`  | boolean                                  | No       | Whether moving the node may expand its parent group                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `definition.nodes[].width`          | number                                   | No       | Authored node width. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `definition.nodes[].height`         | number                                   | No       | Authored node height. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `definition.nodes[].style`          | object                                   | No       | Durable node style properties                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `definition.nodes[].origin`         | array of 2 numbers                       | No       | React Flow node origin                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `definition.nodes[].z_index`        | number                                   | No       | Canvas stacking order                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `definition.nodes[].hidden`         | boolean                                  | No       | Whether the node is hidden                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `definition.nodes[].position`       | object                                   | No       | Node position; omitted positions receive deterministic automatic layout                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `definition.nodes[].position.x`     | number                                   | Yes      | Horizontal canvas coordinate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `definition.nodes[].position.y`     | number                                   | Yes      | Vertical canvas coordinate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `definition.edges`                  | array of objects                         | Yes      | Complete canvas edge list. At most 10000 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `definition.edges[].id`             | string                                   | Yes      | Stable canvas edge identifier. 1 to 200 characters. Example: `edge_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `definition.edges[].source`         | string                                   | Yes      | Source node identifier. 1 to 200 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `definition.edges[].target`         | string                                   | Yes      | Target node identifier. 1 to 200 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `definition.edges[].source_handle`  | string or null                           | Yes      | Source handle identifier                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `definition.edges[].target_handle`  | string or null                           | Yes      | Target handle identifier                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `definition.edges[].type`           | string                                   | No       | Canvas edge renderer type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `definition.edges[].data`           | object                                   | No       | Durable edge configuration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `definition.node_inputs`            | map of object                            | Yes      | Complete per-node generation and action input configuration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `definition.node_outputs`           | map of object                            | Yes      | Complete current durable output attached to each node                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `definition.layer_editor_documents` | map of object                            | No       | Portable Layer Editor documents keyed by Layer Editor node identifier; omitted when no Layer Editor nodes exist                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## Responses

### 200: Canvas definition replaced.

| Field                               | Type                                     | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------- | ---------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`                        | string                                   | Yes      | Project identifier. Pattern: `^prj_\S+$`. Example: `prj_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `canvas_url`                        | string (uri)                             | Yes      | Project canvas URL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `definition`                        | object                                   | Yes      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `definition.nodes`                  | array of objects                         | Yes      | Complete ordered canvas node list                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `definition.nodes[].id`             | string                                   | Yes      | Stable canvas node identifier. 1 to 200 characters. Example: `node_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `definition.nodes[].type`           | string                                   | Yes      | Flora canvas node type. One of: `videoBlock`, `textBlock`, `comment`, `group`, `ghost`, `virtualSourceNode`, `emptyImageBlock`, `outpaintImageBlock`, `inpaintImageBlock`, `staticImageBlock`, `staticVideoBlock`, `resultImageBlock`, `resultVideoBlock`, `resultTextBlock`, `audioBlock`, `resultAudioBlock`, `staticAudioBlock`, `techniqueBlock`, `layerEditorNode`, `videoEditorNode`, `collectionNode`, `routerNode`, `switchNode`, `elementNode`, `textLabel`, `notes`, `codeBlock`, `documentNode`, `deckNode`, `exportNode`, `webcamNode`, `claudeNode`, `model3dNode`. |
| `definition.nodes[].data`           | object                                   | Yes      | Durable public node configuration; transient collaboration state is omitted                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `definition.nodes[].parent_id`      | string                                   | No       | Parent group node identifier. 1 to 200 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `definition.nodes[].extent`         | string or array of 2 array of 2 numberss | No       | Optional React Flow movement extent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `definition.nodes[].expand_parent`  | boolean                                  | No       | Whether moving the node may expand its parent group                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `definition.nodes[].width`          | number                                   | No       | Authored node width. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `definition.nodes[].height`         | number                                   | No       | Authored node height. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `definition.nodes[].style`          | object                                   | No       | Durable node style properties                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `definition.nodes[].origin`         | array of 2 numbers                       | No       | React Flow node origin                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `definition.nodes[].z_index`        | number                                   | No       | Canvas stacking order                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `definition.nodes[].hidden`         | boolean                                  | No       | Whether the node is hidden                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `definition.nodes[].position`       | object                                   | Yes      | Persisted node position                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `definition.nodes[].position.x`     | number                                   | Yes      | Horizontal canvas coordinate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `definition.nodes[].position.y`     | number                                   | Yes      | Vertical canvas coordinate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `definition.edges`                  | array of objects                         | Yes      | Complete canvas edge list                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `definition.edges[].id`             | string                                   | Yes      | Stable canvas edge identifier. 1 to 200 characters. Example: `edge_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `definition.edges[].source`         | string                                   | Yes      | Source node identifier. 1 to 200 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `definition.edges[].target`         | string                                   | Yes      | Target node identifier. 1 to 200 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `definition.edges[].source_handle`  | string or null                           | Yes      | Source handle identifier                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `definition.edges[].target_handle`  | string or null                           | Yes      | Target handle identifier                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `definition.edges[].type`           | string                                   | No       | Canvas edge renderer type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `definition.edges[].data`           | object                                   | No       | Durable edge configuration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `definition.node_inputs`            | map of object                            | Yes      | Complete per-node generation and action input configuration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `definition.node_outputs`           | map of object                            | Yes      | Complete current durable output attached to each node                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `definition.layer_editor_documents` | map of object                            | No       | Portable Layer Editor documents keyed by Layer Editor node identifier; omitted when no Layer Editor nodes exist                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `summary`                           | object                                   | Yes      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `summary.node_count`                | integer                                  | Yes      | At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `summary.edge_count`                | integer                                  | Yes      | At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `summary.workflow_count`            | integer                                  | Yes      | At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `summary.isolated_node_count`       | integer                                  | Yes      | At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `summary.group_count`               | integer                                  | Yes      | At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

## 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/replaceprojectcanvasdefinition.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.
