Nodes

Org chart nodes — the departments, teams, and roles that make up your organization's tree.

GET/api/v1/nodes

Returns a paginated flat list of all org chart nodes in your organization.

Query parameters

Name	Type	Required	Description
limit	integer	optional	Number of results (default 100, max 500).
cursor	ISO 8601	optional	Pagination cursor from the previous page's nextCursor.
parentId	uuid	optional	Filter to direct children of this node.

Example response

Json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "parentId": null,
      "title": "Engineering",
      "description": "All software teams",
      "nodeType": "department",
      "sortOrder": 0,
      "color": "#6366f1",
      "metadata": {},
      "createdAt": "2025-03-01T12:00:00.000Z",
      "updatedAt": "2025-03-15T09:30:00.000Z"
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "parentId": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Platform Team",
      "description": "Infrastructure and DevOps",
      "nodeType": "team",
      "sortOrder": 1,
      "color": null,
      "metadata": {},
      "createdAt": "2025-03-02T08:00:00.000Z",
      "updatedAt": "2025-03-02T08:00:00.000Z"
    }
  ],
  "nextCursor": null
}

GET/api/v1/nodes/:id

Returns a single node by ID. 404 if not found or outside your org.

Path parameters

Name	Type	Required	Description
id	uuid	required	Node ID.

Example response

Json

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "parentId": null,
    "title": "Engineering",
    "description": "All software teams",
    "nodeType": "department",
    "sortOrder": 0,
    "color": "#6366f1",
    "metadata": {},
    "createdAt": "2025-03-01T12:00:00.000Z",
    "updatedAt": "2025-03-15T09:30:00.000Z"
  }
}

Node object

Fields

Name	Type	Required	Description
id	uuid	optional	Unique node ID.
parentId	uuid \| null	optional	Parent node ID. null for root nodes.
title	string	optional	Display name of the node.
description	string \| null	optional	Optional description.
nodeType	string	optional	Type label: department, team, role, or custom.
sortOrder	integer	optional	Order among siblings (ascending).
color	string \| null	optional	Hex color code, e.g. "#6366f1".
metadata	object	optional	Free-form JSON metadata attached to this node.
createdAt	ISO 8601	optional	Creation timestamp.
updatedAt	ISO 8601	optional	Last-modified timestamp.

Building a tree from the flat list

The API returns a flat array. Use parentId to reconstruct the hierarchy:

Javascript

function buildTree(nodes) {
  const map = {};
  for (const n of nodes) map[n.id] = { ...n, children: [] };
  const roots = [];
  for (const n of Object.values(map)) {
    if (n.parentId && map[n.parentId]) {
      map[n.parentId].children.push(n);
    } else {
      roots.push(n);
    }
  }
  return roots;
}

Code samples

# List all nodes
curl "https://sopflow.io/api/v1/nodes?limit=100" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# List children of a specific node
curl "https://sopflow.io/api/v1/nodes?parentId=PARENT_NODE_ID" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Mutating nodes

Mutations require the write scope on the API key. Pass an Idempotency-Key header on POSTs to make the call replay-safe (see Errors & Limits).

POST/api/v1/nodes

Create a node. Set parentId=null for a root node, or another node's id to attach as a child.

Body fields

Name	Type	Required	Description
parentId	uuid \| null	required	Parent node, or null for root.
title	string	required	1–200 chars.
nodeType	string	required	department, team, role, or a custom tag.
description	string \| null	optional	Up to 2000 chars.
color	string \| null	optional	Hex code like #6366f1.
sortOrder	integer	optional	Position among siblings; defaults to last.
metadata	object	optional	Arbitrary JSON.

Example response

Json

{
  "data": {
    "id": "af803555-3a41-4fd2-a8da-79537b8781b0",
    "parentId": null,
    "title": "New Department",
    "nodeType": "department",
    "color": "#6366f1",
    "createdAt": "2026-05-03T04:00:00.000Z"
  }
}

PATCH/api/v1/nodes/:id

Update fields on an existing node. Only the fields you supply are changed.

Body fields (all optional)

Name	Type	Required	Description
title	string	optional	1–200 chars.
description	string \| null	optional	—
nodeType	string	optional	—
color	string \| null	optional	Hex code or null to clear.
metadata	object	optional	—

Example response

Json

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "parentId": null,
    "title": "Engineering",
    "description": "All software teams",
    "nodeType": "department",
    "sortOrder": 0,
    "color": "#6366f1",
    "metadata": {},
    "createdAt": "2025-03-01T12:00:00.000Z",
    "updatedAt": "2025-03-15T09:30:00.000Z"
  }
}

POST/api/v1/nodes/:id/move

Re-parent and/or re-order a node. Children move with it.

Body fields

Name	Type	Required	Description
newParentId	uuid \| null	required	Target parent, or null to make a new root.
newSortOrder	integer	required	Position among new siblings (0-indexed).

Example response

Json

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "parentId": null,
    "title": "Engineering",
    "description": "All software teams",
    "nodeType": "department",
    "sortOrder": 0,
    "color": "#6366f1",
    "metadata": {},
    "createdAt": "2025-03-01T12:00:00.000Z",
    "updatedAt": "2025-03-15T09:30:00.000Z"
  }
}

DELETE/api/v1/nodes/:id

Permanently delete a node and every descendant. Returns 204 on success. SOPs assigned to deleted nodes are unassigned but not removed.

Example response

Json

HTTP/1.1 204 No Content

Nodes

Node object

Building a tree from the flat list

Code samples

Mutating nodes

Build a team ownership lookup