Skip to content
FLORA FLORA API

Arrange canvas nodes

POST
/workspaces/{workspaceId}/projects/{projectId}/canvas/arrange
 
import { FloraClient } from '@flora-ai/flora';


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


const canva = await client.projects.canvas.arrangeNodes({
  workspaceId: '<workspaceId>',
  projectId: '<projectId>',
  node_ids: [
    'n7',
  ],
});
console.log(canva);

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. A node_ids layout is planned in isolation: nodes outside the set are not obstacles, so on a populated canvas the result can land on top of existing work — the response reports every such collision in overlaps, and all:true is the only layout guaranteed to be clear. 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.

Error responses use the standard error body.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
workspaceId
required

Workspace identifier

string
/^ws_\S+$/

Workspace identifier

projectId
required

Project identifier

string
/^prj_\S+$/

Project identifier

Request Body required

Section titled “Request Body required ”
Media type application/json
Any of:
object
node_ids
required

Nodes to lay out, addressed by the short id or node UUID the project graph endpoint reports. Up to 500 per request.

Array<string>
>= 1 items <= 500 items
all
boolean

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Nodes arranged.

Media type application/json
object
project_id
required

Project identifier

string
/^prj_\S+$/
canvas_url
required

Project canvas URL

string format: uri
arranged
required

Nodes the layout considered

integer
moved
required

Nodes whose position changed. Zero means the set was already laid out.

integer
overlaps
required

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.

Array<object>
object
node_id
required

Arranged node’s short id

string
>= 1 characters
overlaps_with
required

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

string
>= 1 characters
hint

How to resolve the collisions. Present only when overlaps is non-empty.

string
revision
required

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

string
>= 1 characters
Example 
{
  "project_id": "prj_abc123",
  "overlaps": [
    {
      "node_id": "n3",
      "overlaps_with": "n7"
    }
  ],
  "revision": "4f2c8ab19e3d7c05"
}