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

# Arrange canvas nodes

Arrange canvas nodes with the FLORA API: POST /workspaces/{workspaceId}/projects/{projectId}/canvas/arrange.

Lays out nodes with the canvas's own layout engine — the same Tidy the editor offers — so a caller never has to compute positions by hand. The layout follows edges (sources left of the nodes they feed), stacks unconnected nodes below the flow, and keeps group members inside their frame; a frame's own size is left as it is. Pass node\_ids for the nodes to arrange, or all:true to reorganize the entire canvas, which moves work the user positioned by hand and so should only follow an explicit request; a request with neither is rejected. For an explicit row, column or grid layout without an origin, the block is translated clear of relevant untouched nodes: top-level work for a top-level set, or sibling members for a set inside a field. An explicit origin is authoritative and may collide with untouched work. Tidy retains its flow-layout behavior. Inspect the returned overlaps and choose a clear origin or arrange the relevant work when needed. Unknown ids reject the whole request with a machine-readable ref\_not\_found per id and nothing moves. Positions are written as one atomic transaction. The revision returned is the same change-detection marker the project graph endpoint reports. 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/arrange
```

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

## Example

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

```bash
curl -X POST 'https://app.flora.ai/api/v1/workspaces/ws_abc123/projects/prj_abc123/canvas/arrange' \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "node_ids": [
    "n7"
  ]
}'
```

{% 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.arrangeNodes({
  workspaceId: 'ws_abc123',
  projectId: 'prj_abc123',
  body: {
    node_ids: [
      'n7',
    ],
  },
});
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.

The body takes one of 2 shapes, set by `all`.

**Shape 1: `all` is `false`.**

| Field             | Type            | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `node_ids`        | array of string | Yes      | Nodes to lay out, addressed by the short id or node UUID the project graph endpoint reports. Up to 500 per request. With layout, this is also the placement order. 1 to 500 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `all`             | boolean         | No       | Always `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `layout`          | object          | No       | Place the nodes in a row, a column, or a grid instead of the edge-following Tidy layout. Each cell is as wide as the widest node in its column and as tall as the tallest node in its row, so mixed sizes stay aligned and never overlap each other. The nodes must all sit at the top level of the canvas or all be direct members of the same group; a mixed set is rejected, and so is a label pinned to a node, which follows its host. Members are laid out from their frame's padded corner and the frame is refit around all of its members in the same write (an explicit origin inside the frame only grows it; the exact frame anchor aliases its padded content corner; any other origin above or left of the padded corner is rejected). Nodes outside the set are not moved and are not obstacles, so the response's overlaps still names anything the block landed on. |
| `layout.mode`     | string          | Yes      | How to place the nodes: row lays them left to right, column top to bottom, grid row-major with columns per row. Every mode keeps the order of node\_ids, so the first id is the leading node. One of: `row`, `column`, `grid`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `layout.columns`  | integer         | No       | Nodes per row for mode grid; defaults to the square root of the count, rounded up. Ignored on row and column, which determine it from the mode. 1 to 500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `layout.gap`      | number          | No       | Space between neighbouring nodes in canvas units, between columns and between rows alike. Defaults to 64, the canvas's own Autoformat grid gap. 0 to 4096.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `layout.origin`   | object          | No       | Absolute canvas position of the block's visual top-left corner — where the first node's box starts painting, not its anchor. Omit to keep the block where the nodes already are (the top-left corner of their current bounding box) or, for group members, to start at the frame's padded corner. For members of one frame, the exact frame anchor (both coordinates equal its graph position) is an alias for that padded corner; every other explicit origin stays literal.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `layout.origin.x` | number          | Yes      | Absolute horizontal canvas coordinate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `layout.origin.y` | number          | Yes      | Absolute vertical canvas coordinate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

**Shape 2: `all` is `true`.**

| Field | Type    | Required | Description                                                                                                                                                          |
| ----- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `all` | boolean | Yes      | Lay out every node on the canvas. Moves work the user positioned by hand, so pass it only when the user asked for the whole canvas to be reorganized. Always `true`. |

## Responses

### 200: Nodes arranged.

| Field                      | Type             | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`               | string           | Yes      | Project identifier. Pattern: `^prj_\S+$`. Example: `prj_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `canvas_url`               | string (uri)     | Yes      | Project canvas URL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `arranged`                 | integer          | Yes      | Nodes the layout considered. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `moved`                    | integer          | Yes      | Nodes whose position changed. Zero means the set was already laid out. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `overlaps`                 | array of objects | Yes      | Pairs left too close together: an arranged node and something that cannot move out of its way — a node outside the set, or another created node pinned to a caller-chosen position. WHAT COUNTS AS TOO CLOSE DEPENDS ON THE PASS. A layout reports true geometric intersection — it plans in isolation, so nodes outside it are not obstacles. The collision rescue instead reports anything inside the canvas’s node spacing (320px horizontal, 40px vertical), the same clearance the placer keeps, so a pair it names may still have visible air between them. Either way an empty array is the only clean result, and it is always empty for all:true, which leaves nothing outside the layout. |
| `overlaps[].node_id`       | string           | Yes      | Arranged node's short id. At least 1 character. Example: `n3`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `overlaps[].overlaps_with` | string           | Yes      | Short id of the node it conflicts with, which cannot move out of the way: one outside the arranged set, or another created node pinned to a caller-chosen position. At least 1 character. Example: `n7`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `hint`                     | string           | No       | How to resolve the collisions. Present only when overlaps is non-empty.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `bounds`                   | object           | No       | Absolute visual bounding box of the arranged nodes after the layout — painted edges, not anchors — so a follow-up batch can be placed beside or below it (for example at origin y = bounds.y + bounds.height + gap). Reported by the arrange endpoint; absent from the collision rescue a canvas write runs on what it created.                                                                                                                                                                                                                                                                                                                                                                     |
| `bounds.x`                 | number           | Yes      | Absolute left edge of the arranged block                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `bounds.y`                 | number           | Yes      | Absolute top edge of the arranged block                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `bounds.width`             | number           | Yes      | Width of the arranged block. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `bounds.height`            | number           | Yes      | Height of the arranged block. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `revision`                 | string           | Yes      | Change-detection marker of the canvas after the layout, identical to the value the project graph endpoint reports. At least 1 character. Example: `4f2c8ab19e3d7c05`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

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