# Flow Engineering (/integrations/flow)

[Flow Engineering](https://www.flowengineering.com/) connects requirements, systems, tests, and their relationships. Use the Flow block to search current project data, read values and history, manage discussions, and propose changes on a working branch.

## Connect an account \[#connect-an-account]

In Flow, open **Settings → API & MCP**, generate a personal API key, and copy it. Create a connection from the block's **Flow Account** field with:

- **API key:** The complete key, including its `brd_` prefix.
- **API URL:** The URL from Flow's API settings. The default is `https://backend.branch.flowengineering.com`. The `/customer-api` suffix opens the API documentation and is removed from requests.
- **Workspace identifier:** The final segment of the MCP URL. For `https://backend.branch.flowengineering.com/mcp/your-workspace`, enter `your-workspace`.

The key uses its owner's current Flow permissions. It does not grant additional project access or bypass read-only roles. Revoke or replace it in Flow when needed. This integration uses the current customer API, not the older refresh-token API under `api.flowengineering.com/rest/v1`.

## Work with project data \[#work-with-project-data]

Select a project, then use **Get Data Model** to discover its categories and field keys. Requirements and tests are entities in those categories; names and custom fields can vary by project. Use the returned IDs rather than display names.

**Search Entities** returns up to 100 compact matches by name, field value, or exact Flow/Human ID. Use **Get Entities** to read their full values and relationships. Search reflects the selected branch and may have incomplete text results while Flow's index warms.

**List Entities** reads one page. Pass `nextPageStart` as **Cursor** and continue while `moreAvailable` is true, including after an empty page. **Filter Entities** and **Get Entity History** instead return `nextCursor`; continue until it is null. No operation automatically downloads every page.

## Make changes \[#make-changes]

Omitting **Branch** reads or writes Base (`master`). Use **Create Branch** and select its returned ID to prepare changes separately. Flow's project permissions and branch protections still apply; the integration does not request the admin bypass option.

**Create Entities** and **Set Values** accept up to 100 entries per request. Each batch is atomic, but separate requests are separate transactions. Creates and other mutations are not automatically retried. After a timeout, read back the affected data before repeating a write.

To reply to a discussion, pass the original comment ID as **Entity ID**, even when replying to a later reply. Use the same branch for the original thread and its replies. Resolve a thread by updating the original comment.

See [Flow's API conventions](https://docs.flowengineering.com/api/conventions) for branch and pagination behavior, and [its API reference](https://docs.flowengineering.com/api/reference) for supported field values and filters.

## Use the block \[#usage-instructions]

Read and update Flow Engineering projects, requirements, tests, and other entities through its customer API. Search current project data, inspect categories and relationships, manage comments, and make controlled changes on a working branch using your connected account permissions.

## Actions \[#actions]

### Flow List Projects \[#flow-list-projects]

List projects accessible to the connected Flow user. The API returns up to the requested limit without a continuation cursor.

#### Input \[#input]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `limit` | number | No | Maximum results in this page |

#### Output \[#output]

| Parameter | Type | Description |
| - | - | - |
| `projects` | array | List Projects result |

### Flow Get Project \[#flow-get-project]

Read a Flow project by its UUID.

#### Input \[#input-1]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |

#### Output \[#output-1]

| Parameter | Type | Description |
| - | - | - |
| `project` | json | Get Project result |

### Flow Get Data Model \[#flow-get-data-model]

Read the project categories and field definitions before interpreting values or writing custom fields.

#### Input \[#input-2]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |

#### Output \[#output-2]

| Parameter | Type | Description |
| - | - | - |
| `categories` | array | Get Data Model result |

### Flow List Branches \[#flow-list-branches]

List the Flow project branches and their review and protection state.

#### Input \[#input-3]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |

#### Output \[#output-3]

| Parameter | Type | Description |
| - | - | - |
| `branches` | array | List Branches result |

### Flow Create Branch \[#flow-create-branch]

Create a working branch before modifying requirements, tests, or other project entities.

#### Input \[#input-4]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `branchName` | string | No | Name of the new branch |
| `parentId` | string | No | Parent branch ID; omit for Base |
| `description` | string | No | Description of the new branch |
| `isVariant` | boolean | No | Create a variant branch |

#### Output \[#output-4]

| Parameter | Type | Description |
| - | - | - |
| `id` | string | Created branch ID |
| `number` | number | Assigned branch number |

### Flow Search Entities \[#flow-search-entities]

Search live Flow entities by name, supported field values, or exact Flow/Human ID. Returns at most 100 compact matches; fetch entities for full values. Text results may be unavailable while the provider index warms.

#### Input \[#input-5]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `entityType` | string | No | Restrict to this category ID from Get Data Model |
| `query` | string | Yes | Search names and supported field values, or an exact Flow/Human ID; at most 1024 characters |
| `limit` | number | No | Maximum results in this page |

#### Output \[#output-5]

| Parameter | Type | Description |
| - | - | - |
| `matches` | array | Search Entities result |

### Flow List Entities \[#flow-list-entities]

Read one page of live Flow entities. Continue with nextPageStart while moreAvailable is true, including after an empty page.

#### Input \[#input-6]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `entityType` | string | No | Restrict to this category ID from Get Data Model |
| `cursor` | string | No | Opaque continuation cursor from the previous page |
| `limit` | number | No | Maximum results in this page |

#### Output \[#output-6]

| Parameter | Type | Description |
| - | - | - |
| `entities` | array | Entity states on this page |
| `nextPageStart` | string | Opaque cursor for the next page |
| `moreAvailable` | boolean | Continue even after empty pages while true |

### Flow Get Entities \[#flow-get-entities]

Read the full values, relationships, and timestamps of up to 100 Flow entities in one project and branch.

#### Input \[#input-7]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `entityIds` | string | Yes | Comma-separated entity IDs; up to 100 per read |

#### Output \[#output-7]

| Parameter | Type | Description |
| - | - | - |
| `entities` | array | Get Entities result |

### Flow Create Entity \[#flow-create-entity]

Create an entity in a category on the selected branch. Branch protection and the connected user permissions remain enforced.

#### Input \[#input-8]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `entityType` | string | Yes | Category ID returned by Get Data Model |
| `name` | string | Yes | Entity name |

#### Output \[#output-8]

| Parameter | Type | Description |
| - | - | - |
| `entity` | json | Create Entity result |

### Flow Create Entities \[#flow-create-entities]

Create 1–100 entities atomically on a single branch. A timed-out request may already have committed; inspect the branch before retrying.

#### Input \[#input-9]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `entities` | json | Yes | Array of 1–100 entities: \[{entityType, name, id?}]. IDs may be omitted for server generation |

#### Output \[#output-9]

| Parameter | Type | Description |
| - | - | - |
| `entities` | array | Create Entities result |

### Flow Set Value \[#flow-set-value]

Set one field on a Flow entity using a key from the data model and a JSON value of the documented field type.

#### Input \[#input-10]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `entityId` | string | Yes | Entity ID returned by Search Entities or List Entities |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `fieldKey` | string | Yes | Stored field key returned by Get Data Model |
| `value` | string | Yes | JSON-encoded field value matching the data model. Use "text" for a string, 123 for a number, true or false for a boolean, an array or object, or null to clear the field. Use "" for an empty string. |

#### Output \[#output-10]

| Parameter | Type | Description |
| - | - | - |
| `entity` | json | Set Value result |

### Flow Set Values \[#flow-set-values]

Set 1–100 field values atomically on one branch. Returns each affected entity once in first-touched order.

#### Input \[#input-11]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `updates` | json | Yes | Array of 1–100 field updates: \[{entityId, key, value}] |

#### Output \[#output-11]

| Parameter | Type | Description |
| - | - | - |
| `entities` | array | Set Values result |

### Flow Delete Entity \[#flow-delete-entity]

Delete an entity on the selected branch. Branch protection is enforced.

#### Input \[#input-12]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `entityId` | string | Yes | Entity ID returned by Search Entities or List Entities |
| `branchId` | string | No | Branch ID; omit or use master for Base |

#### Output \[#output-12]

No output fields.

### Flow Restore Entity \[#flow-restore-entity]

Restore a deleted entity with its prior fields and links. Restoring a child does not restore its deleted parent.

#### Input \[#input-13]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `entityId` | string | Yes | Entity ID returned by Search Entities or List Entities |
| `branchId` | string | No | Branch ID; omit or use master for Base |

#### Output \[#output-13]

No output fields.

### Flow Add Link \[#flow-add-link]

Add a downstream relationship between Flow entities on the selected branch.

#### Input \[#input-14]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `entityId` | string | Yes | Entity ID returned by Search Entities or List Entities |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `destinationId` | string | Yes | ID of the downstream entity to link or unlink |

#### Output \[#output-14]

| Parameter | Type | Description |
| - | - | - |
| `entity` | json | Add Link result |

### Flow Remove Link \[#flow-remove-link]

Remove a downstream relationship between Flow entities on the selected branch.

#### Input \[#input-15]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `entityId` | string | Yes | Entity ID returned by Search Entities or List Entities |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `destinationId` | string | Yes | ID of the downstream entity to link or unlink |

#### Output \[#output-15]

| Parameter | Type | Description |
| - | - | - |
| `entity` | json | Remove Link result |

### Flow List Comments \[#flow-list-comments]

Read direct comment threads for an entity or direct replies to the original comment ID. Keep the same branch when following replies.

#### Input \[#input-16]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `entityId` | string | Yes | Entity ID, or the original comment ID when reading or posting thread replies |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `includeResolved` | boolean | No | Include resolved comments |

#### Output \[#output-16]

| Parameter | Type | Description |
| - | - | - |
| `comments` | array | List Comments result |

### Flow Get Comment \[#flow-get-comment]

Read a comment using its ID and its returned entity\_id as the parent path.

#### Input \[#input-17]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `entityId` | string | Yes | Entity ID, or the original comment ID when reading or posting thread replies |
| `commentId` | string | Yes | Comment ID; entityId must be the comment's returned entity\_id |

#### Output \[#output-17]

| Parameter | Type | Description |
| - | - | - |
| `comment` | json | Get Comment result |

### Flow Create Comment \[#flow-create-comment]

Start a thread on an entity or reply using the original comment ID as entityId. Set the branch explicitly; replies do not inherit it.

#### Input \[#input-18]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `entityId` | string | Yes | Entity ID, or the original comment ID when reading or posting thread replies |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `text` | string | Yes | Plain-text comment body |

#### Output \[#output-18]

| Parameter | Type | Description |
| - | - | - |
| `comment` | json | Create Comment result |

### Flow Update Comment \[#flow-update-comment]

Edit comment text or resolve/reopen its thread. Use the original comment to change the thread status.

#### Input \[#input-19]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `entityId` | string | Yes | Entity ID, or the original comment ID when reading or posting thread replies |
| `commentId` | string | Yes | Comment ID; entityId must be the comment's returned entity\_id |
| `text` | string | No | Replacement plain-text comment body |
| `resolved` | boolean | No | Resolve the thread with true or reopen it with false |

#### Output \[#output-19]

| Parameter | Type | Description |
| - | - | - |
| `comment` | json | Update Comment result |

### Flow Delete Comment \[#flow-delete-comment]

Delete a comment authored by the connected user.

#### Input \[#input-20]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `entityId` | string | Yes | Entity ID, or the original comment ID when reading or posting thread replies |
| `commentId` | string | Yes | Comment ID; entityId must be the comment's returned entity\_id |

#### Output \[#output-20]

No output fields.

### Flow Filter Entities \[#flow-filter-entities]

Read one page of IDs matching typed field conditions and AND/OR groups. Continue until nextCursor is null, including after empty pages; results reflect current state.

#### Input \[#input-21]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `filter` | json | Yes | Filter object: {kind:"type",operation:"overlaps",values:\[categoryId]}, {kind:"field",category\_id,field\_key,operation:"contains",value}, or {kind:"group",operator:"and"\|"or",conditions:\[...]}. Use data-model IDs and field-compatible operators; at most 50 nodes and 5 group levels |
| `cursor` | string | No | Opaque continuation cursor from the previous page |
| `limit` | number | No | Maximum results in this page |
| `timezone` | string | No | IANA timezone for date filters; defaults to UTC |

#### Output \[#output-21]

| Parameter | Type | Description |
| - | - | - |
| `entityIds` | array | Matching entity IDs; fetch entities to read values |
| `nextCursor` | string | Continue until null, even after an empty page |

### Flow Get Entity History \[#flow-get-entity-history]

Read a page of change history for up to 500 entities. Keep project, branch, and entity IDs fixed while paging; restart if a rebase expires the cursor.

#### Input \[#input-22]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project UUID returned by List Projects |
| `branchId` | string | No | Branch ID; omit or use master for Base |
| `entityIds` | string | Yes | Comma-separated entity IDs; up to 500 per history page |
| `cursor` | string | No | Opaque continuation cursor from the previous page |
| `limit` | number | No | Maximum results in this page |

#### Output \[#output-22]

| Parameter | Type | Description |
| - | - | - |
| `entries` | array | Entity change history page |
| `nextCursor` | string | Continue until null |