# Flowg8 · 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.

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.

## POST /v1/designer-flows

Authentication: restricted integration key (scope: flows:write) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 120
- accessScope (string, optional): min length 1 · max length 60
- definition (object, required): 
- presentation (object, required): 

## Request example (replace example IDs)

```sh
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": {}
  }
}'
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000002",
  "draft": {
    "revision": 1,
    "publishedVersionId": null
  }
}
```

Source: /docs/create-flow
Full schemas: /docs/openapi.json