Process Flows

Cross-functional process diagrams — start/end terminators, manual steps, decision diamonds, SOP references, and department swimlanes wired up with edges.

GET/api/v1/process-flows

List process flows in the workspace, paginated.

Query parameters

Name	Type	Required	Description
limit	integer	optional	Default 100, max 500.
cursor	ISO 8601	optional	Pagination cursor.

Example response

Json

{
  "data": [
    {
      "id": "...",
      "title": "Customer feature request — sample",
      "status": "active",
      "createdAt": "...",
      "updatedAt": "..."
    }
  ],
  "nextCursor": null
}

GET/api/v1/process-flows/:id

Returns a single flow with its nodes and edges inlined.

Example response

Json

{
  "data": {
    "id": "10a7fb55-aac3-4a17-8beb-8074c1d31697",
    "title": "Customer feature request — sample",
    "description": "Cross-functional sample flow.",
    "status": "active",
    "createdAt": "2026-05-03T04:30:00.000Z",
    "updatedAt": "2026-05-03T04:30:00.000Z",
    "nodes": [
      {
        "id": "...",
        "nodeType": "start",
        "label": "Request filed",
        "positionX": 60,
        "positionY": 200
      },
      {
        "id": "...",
        "nodeType": "decision",
        "label": "In scope?",
        "positionX": 420,
        "positionY": 340
      }
    ],
    "edges": [
      {
        "id": "...",
        "sourceNodeId": "...",
        "targetNodeId": "...",
        "edgeType": "conditional",
        "label": "Yes"
      }
    ]
  }
}

Flow object

Fields

Name	Type	Required	Description
id	uuid	optional	—
title	string	optional	—
description	string \| null	optional	—
status	string	optional	draft \| active \| archived
createdAt	ISO 8601	optional	—
updatedAt	ISO 8601	optional	—
nodes	FlowNode[]	optional	Inline only on the detail endpoint.
edges	FlowEdge[]	optional	Inline only on the detail endpoint.

FlowNode

Fields

Name	Type	Required	Description
id	uuid	optional	—
nodeType	string	optional	start \| end \| manual_step \| decision \| sop_reference \| department_lane
label	string \| null	optional	—
sopId	uuid \| null	optional	Set on sop_reference nodes.
orgNodeId	uuid \| null	optional	Set on department_lane nodes.
positionX	number	optional	—
positionY	number	optional	—
metadata	object	optional	Free-form (color, hints, etc.).

FlowEdge

Fields

Name	Type	Required	Description
id	uuid	optional	—
sourceNodeId	uuid	optional	—
targetNodeId	uuid	optional	—
edgeType	string	optional	default \| conditional \| error
label	string \| null	optional	Often "Yes" / "No" on conditional edges.
sourceHandle	string	optional	Default "out". Decision nodes use "yes" / "no".
targetHandle	string	optional	Default "in".

Code sample — build a flow

# List flows
curl https://sopflow.io/api/v1/process-flows \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# Create a new flow
curl -X POST https://sopflow.io/api/v1/process-flows \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Onboarding","status":"draft"}'

# Add a start node
curl -X POST https://sopflow.io/api/v1/process-flows/FLOW_ID/nodes \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nodeType":"start","label":"Begin","positionX":0,"positionY":0}'

Mutating flows

All mutations require write scope. Building a flow is three resources: the flow itself, its nodes, and its edges. Pass an Idempotency-Key on POSTs to make retries safe.

POST/api/v1/process-flows

Create an empty flow.

Body fields

Name	Type	Required	Description
title	string	required	—
description	string \| null	optional	—
status	string	optional	draft (default) \| active \| archived

Example response

Json

{ "data": { "id": "...", "title": "Onboarding", "status": "draft" } }

PATCH/api/v1/process-flows/:id

Update flow metadata. Nodes/edges are managed via their own endpoints.

Example response

Json

{ "data": { "id": "...", "title": "Renamed", "status": "active" } }

DELETE/api/v1/process-flows/:id

Delete a flow. Cascades to nodes and edges.

Example response

Json

HTTP/1.1 204 No Content

Nodes

POST/api/v1/process-flows/:id/nodes

Add a node to a flow.

Body fields

Name	Type	Required	Description
nodeType	string	required	start \| end \| manual_step \| decision \| sop_reference \| department_lane
label	string \| null	optional	—
positionX	number	optional	Defaults to 0.
positionY	number	optional	Defaults to 0.
sopId	uuid \| null	optional	Required when nodeType=sop_reference.
orgNodeId	uuid \| null	optional	Optional anchor (used by department_lane).
metadata	object	optional	—

Example response

Json

{ "data": { "id": "...", "nodeType": "start", "label": "Begin" } }

PATCH/api/v1/process-flow-nodes/:id

Update a node's label, position, or metadata.

Example response

Json

{ "data": { "id": "...", "label": "New label" } }

DELETE/api/v1/process-flow-nodes/:id

Delete a node. Edges touching it cascade.

Example response

Json

HTTP/1.1 204 No Content

Edges

POST/api/v1/process-flows/:id/edges

Connect two nodes.

Body fields

Name	Type	Required	Description
sourceNodeId	uuid	required	—
targetNodeId	uuid	required	—
edgeType	string	optional	default \| conditional \| error
label	string \| null	optional	—
sourceHandle	string	optional	Defaults to "out". Use "yes" / "no" off decision nodes.
targetHandle	string	optional	Defaults to "in".

Example response

Json

{ "data": { "id": "...", "edgeType": "conditional", "label": "Yes" } }

PATCH/api/v1/process-flow-edges/:id

Update an edge's label or type.

Example response

Json

{ "data": { "id": "...", "edgeType": "error" } }

DELETE/api/v1/process-flow-edges/:id

Delete an edge.

Example response

Json

HTTP/1.1 204 No Content

Process Flows

Flow object

FlowNode

FlowEdge

Code sample — build a flow

Mutating flows

Nodes

Edges

Keep flow design separate from execution