Flows

Create a flow

Create a named designer document with typed fields and a node graph. This saves a draft and does not start a process.

POST/v1/designer-flows

Administrator or Sandbox developer requiredIntegration key: flows:write; or a user token with the required role.

How it works

Replace the example groupId with an existing workspace approval group. Up to 30 fields (text, number, boolean, ISO date, select) and 40 nodes (start, condition, approval, end).

Conditions reference field keys with all/any and eq, neq, gt, gte, lt, lte or contains. Internal approval nodes reference groupId. External nodes use groupId:null and externalApprover:{source:"email",email:"reviewer@example.com"} or {source:"field",field:"recipientEmail",allowedDomains:["example.com"]}. The referenced field must be required text/email. sharedFields lists the request fields disclosed externally (default []). Connect all outputs before publishing. Loops and unreachable nodes are rejected.

Approval outputs: next selects the approved route; rejectedNext selects the rejected route. Connect both for new flows. Each may lead to a condition, another approval, or an end. Omitting rejectedNext preserves historical immediate rejection; null is an unconnected draft output and blocks publishing. Only gates on the actual decision path become pending.

Definition-only alternative: POST /v1/flows {name, definition}; POST /v1/flows/{flowId}/versions {definition}; POST /v1/flow-versions/{versionId}/publish {}. Both schema versions are supported.

Request body

namestringrequiredmin length 1 · max length 120

accessScopestringoptionalmin length 1 · max length 60

definitionobjectrequired

presentationobjectrequired

Required fields & full validation schema → OpenAPI

Request essentials

Authorization: Bearer $FLOWG8_API_KEY
X-Organization-Id: Your workspace UUID
Idempotency-Key: Stable per operation; 8–128 characters

Have an implementation question?Ask about this endpoint. Answers include source references.

curl -X POST "https://api.flowg8.io/v1/designer-flows" \ -H "authorization: Bearer $FLOWG8_API_KEY" \ -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \ -H "idempotency-key: example-create-flow-001" \ -H "content-type: application/json" \ --data-raw '{ "name": "Deployment approval", "definition": { "schemaVersion": 2, "fields": [ { "key": "environment", "label": "Environment", "type": "select", "required": true, "options": [ "staging", "production" ], "min": null, "max": null } ], "nodes": [ { "id": "start", "type": "start", "label": "Request received", "next": "approval" }, { "id": "approval", "type": "approval", "label": "Operations approval", "groupId": "10000000-0000-4000-8000-000000000009", "next": "end" }, { "id": "end", "type": "end", "label": "Approved", "outcome": "approved" } ] }, "presentation": { "names": { "api": "Request", "amount": "Condition", "end": "Complete" }, "description": "Operations approves a deployment.", "positions": {} } }'

Flows

Create a flow

Create a named designer document with typed fields and a node graph. This saves a draft and does not start a process.

POST/v1/designer-flows

Administrator or Sandbox developer requiredIntegration key: flows:write; or a user token with the required role.

How it works

Replace the example groupId with an existing workspace approval group. Up to 30 fields (text, number, boolean, ISO date, select) and 40 nodes (start, condition, approval, end).

Definition-only alternative: POST /v1/flows {name, definition}; POST /v1/flows/{flowId}/versions {definition}; POST /v1/flow-versions/{versionId}/publish {}. Both schema versions are supported.

Request body

namestringrequiredmin length 1 · max length 120

accessScopestringoptionalmin length 1 · max length 60

definitionobjectrequired

presentationobjectrequired

Required fields & full validation schema → OpenAPI

Request essentials

Authorization: Bearer $FLOWG8_API_KEY
X-Organization-Id: Your workspace UUID
Idempotency-Key: Stable per operation; 8–128 characters

Have an implementation question?Ask about this endpoint. Answers include source references.

Create a flow

How it works

Request body

Request essentials

Ask the docs

Create a flow

How it works

Request body

Request essentials

Ask the docs