> For the complete documentation index, see [llms.txt](https://flowmate.gitbook.io/flowmate-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flowmate.gitbook.io/flowmate-documentation/api-reference/flows.md).

# Flows

## Retrieve all flows

> This will only return Flows that are either directly associated with the user, or that are associated with a tenant that the user is also a member of. Requires the 'flows.read' permissions.

```json
{"openapi":"3.0.1","info":{"title":"Default module","version":"1.0.0"},"tags":[{"name":"flows"}],"security":[],"paths":{"/flows":{"get":{"summary":"Retrieve all flows","deprecated":false,"description":"This will only return Flows that are either directly associated with the user, or that are associated with a tenant that the user is also a member of. Requires the 'flows.read' permissions.","operationId":"getFlows","tags":["flows"],"parameters":[{"name":"page[size]","in":"query","description":"Amount of flows per page returned. Default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page[number]","in":"query","description":"Number of the page to be returned. Default is 1.","required":false,"schema":{"type":"integer"}},{"name":"filter[status]","in":"query","description":"Filter results by flow status. Accepts either string ('active' and 'inactive') or integer (1 or 0)","required":false,"schema":{"type":"string"}},{"name":"filter[type]","in":"query","description":"Filter results by flow type (ordinary, long_running)","required":false,"schema":{"type":"string"}},{"name":"filter[user]","in":"query","description":"Filter by user. Works for admin or users with same tenant.","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort the result by one property. Supported: createdAt, updatedAt and name. Prefix field name with - for reversed sort order (DESC) i.e. sort=-updatedAt. Default sorting is by id ASC","required":false,"schema":{"type":"string"}},{"name":"search","in":"query","description":"Search flows by a word or a phrase contained in the flow description OR in the flow name (case-insensitive). Behavior is similar to operator LIKE in SQL but case insensitive.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A list of flows.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Flow"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"headers":{}}}}}},"components":{"schemas":{"Flow":{"allOf":[{"$ref":"#/components/schemas/MutableFlow"},{"type":"object","required":["id","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"status":{"type":"string","description":"Flow status, set automatically in response to start/stop commands","enum":["active","inactive","starting","stopping"]},"createdAt":{"type":"string","description":"Timestamp of flow creation","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp of most recent flow update","format":"date-time"}}}]},"MutableFlow":{"type":"object","required":["name","graph","type"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"tenant":{"type":"string"},"graph":{"$ref":"#/components/schemas/FlowGraph"},"type":{"type":"string","description":"Flow type","enum":["ordinary","realtime"]},"cron":{"type":"string","description":"A cron string describing the interval at which this flow is run. If unset, the flow uses webhooks instead"},"owners":{"type":"array","items":{"$ref":"#/components/schemas/Owner"}}}},"FlowGraph":{"type":"object","properties":{"nodes":{"type":"array","description":"An array of all components involved in this flow","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"ID of this node, which will be referenced by edges"},"componentId":{"type":"string","description":"The component repository id of the component (e.g. adapter/transformer) to be used in this step."},"credentials_id":{"type":"string","description":"A secret service id of a secret containing credentials for this node."},"function":{"type":"string","description":"The function that the component will be executing."},"name":{"type":"string","description":"Descriptive name of this node"},"description":{"type":"string"},"fields":{"type":"object","description":"Optional arguments passed on to the component","properties":{}}}}},"edges":{"type":"array","description":"An array of edges linking nodes together, determining the order in which nodes are activated","items":{"type":"object","required":["source","target"],"properties":{"id":{"type":"string"},"config":{"type":"object","properties":{"condition":{"type":"string"},"mapper":{"type":"object","properties":{}}}},"source":{"type":"string","description":"The source node of this edge, referring to the id field of a node"},"target":{"type":"string","description":"The target node of this edge, referring to the id field of a node"}}}}}},"Owner":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"External id of the owner"},"type":{"type":"string","description":"Type to discriminate between user or tenant"}}},"Meta":{"type":"object","properties":{"page":{"type":"integer","description":"Current page (1-based numbering)"},"perPage":{"type":"integer","description":"Number of objects per page"},"total":{"type":"integer","description":"Total number of objects"},"totalPages":{"type":"integer","description":"Total number of pages"}}}}}}
```

## Find Flow by ID

> Returns a single Flow by its ID, if the user is authorized to see it. This requires the 'flows.read' permission

```json
{"openapi":"3.0.1","info":{"title":"Default module","version":"1.0.0"},"tags":[{"name":"flows"}],"security":[],"paths":{"/flows/{id}":{"get":{"summary":"Find Flow by ID","deprecated":false,"description":"Returns a single Flow by its ID, if the user is authorized to see it. This requires the 'flows.read' permission","operationId":"getFlowById","tags":["flows"],"parameters":[{"name":"id","in":"path","description":"ID of flow to return","required":true,"schema":{"type":"string","format":"string"}}],"responses":{"200":{"description":"Returns the flow","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Flow"},"meta":{"type":"object","properties":{}}}}}},"headers":{}},"404":{"description":"No Flow with this id was found.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}}}}}},"components":{"schemas":{"Flow":{"allOf":[{"$ref":"#/components/schemas/MutableFlow"},{"type":"object","required":["id","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"status":{"type":"string","description":"Flow status, set automatically in response to start/stop commands","enum":["active","inactive","starting","stopping"]},"createdAt":{"type":"string","description":"Timestamp of flow creation","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp of most recent flow update","format":"date-time"}}}]},"MutableFlow":{"type":"object","required":["name","graph","type"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"tenant":{"type":"string"},"graph":{"$ref":"#/components/schemas/FlowGraph"},"type":{"type":"string","description":"Flow type","enum":["ordinary","realtime"]},"cron":{"type":"string","description":"A cron string describing the interval at which this flow is run. If unset, the flow uses webhooks instead"},"owners":{"type":"array","items":{"$ref":"#/components/schemas/Owner"}}}},"FlowGraph":{"type":"object","properties":{"nodes":{"type":"array","description":"An array of all components involved in this flow","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"ID of this node, which will be referenced by edges"},"componentId":{"type":"string","description":"The component repository id of the component (e.g. adapter/transformer) to be used in this step."},"credentials_id":{"type":"string","description":"A secret service id of a secret containing credentials for this node."},"function":{"type":"string","description":"The function that the component will be executing."},"name":{"type":"string","description":"Descriptive name of this node"},"description":{"type":"string"},"fields":{"type":"object","description":"Optional arguments passed on to the component","properties":{}}}}},"edges":{"type":"array","description":"An array of edges linking nodes together, determining the order in which nodes are activated","items":{"type":"object","required":["source","target"],"properties":{"id":{"type":"string"},"config":{"type":"object","properties":{"condition":{"type":"string"},"mapper":{"type":"object","properties":{}}}},"source":{"type":"string","description":"The source node of this edge, referring to the id field of a node"},"target":{"type":"string","description":"The target node of this edge, referring to the id field of a node"}}}}}},"Owner":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"External id of the owner"},"type":{"type":"string","description":"Type to discriminate between user or tenant"}}}}}}
```

## Deletes a flow

> Entirely deletes a Flow from the repository. This cannot be reverted. Requires the 'flows.write' permission.

```json
{"openapi":"3.0.1","info":{"title":"Default module","version":"1.0.0"},"tags":[{"name":"flows"}],"security":[],"paths":{"/flows/{id}":{"delete":{"summary":"Deletes a flow","deprecated":false,"description":"Entirely deletes a Flow from the repository. This cannot be reverted. Requires the 'flows.write' permission.","operationId":"deleteFlow","tags":["flows"],"parameters":[{"name":"id","in":"path","description":"Flow id to delete","required":true,"schema":{"type":"string","format":"string"}}],"responses":{"200":{"description":"Flow was successfully deleted","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}},"400":{"description":"Invalid ID supplied","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}},"404":{"description":"No Flow with this id was found.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}},"409":{"description":"Flow is currently not inactive. Only stopped, inactive flows may be deleted.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}}}}}}}
```

## Update an existing flow

> The id is used to match the existing Flow that will be updated. Requires the 'flows.write' permission.

```json
{"openapi":"3.0.1","info":{"title":"Default module","version":"1.0.0"},"tags":[{"name":"flows"}],"security":[],"paths":{"/flows/{id}":{"patch":{"summary":"Update an existing flow","deprecated":false,"description":"The id is used to match the existing Flow that will be updated. Requires the 'flows.write' permission.","operationId":"updateFlow","tags":["flows"],"parameters":[{"name":"id","in":"path","description":"ID of flow to update","required":true,"schema":{"type":"string","format":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MutableFlow"}}}},"responses":{"200":{"description":"The updated Flow.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Flow"},"meta":{"type":"object","properties":{}}}}}},"headers":{}},"404":{"description":"Flow not found","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}},"409":{"description":"Flow is currently not inactive. Only stopped, inactive flows may be updated.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}}}}}},"components":{"schemas":{"MutableFlow":{"type":"object","required":["name","graph","type"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"tenant":{"type":"string"},"graph":{"$ref":"#/components/schemas/FlowGraph"},"type":{"type":"string","description":"Flow type","enum":["ordinary","realtime"]},"cron":{"type":"string","description":"A cron string describing the interval at which this flow is run. If unset, the flow uses webhooks instead"},"owners":{"type":"array","items":{"$ref":"#/components/schemas/Owner"}}}},"FlowGraph":{"type":"object","properties":{"nodes":{"type":"array","description":"An array of all components involved in this flow","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"ID of this node, which will be referenced by edges"},"componentId":{"type":"string","description":"The component repository id of the component (e.g. adapter/transformer) to be used in this step."},"credentials_id":{"type":"string","description":"A secret service id of a secret containing credentials for this node."},"function":{"type":"string","description":"The function that the component will be executing."},"name":{"type":"string","description":"Descriptive name of this node"},"description":{"type":"string"},"fields":{"type":"object","description":"Optional arguments passed on to the component","properties":{}}}}},"edges":{"type":"array","description":"An array of edges linking nodes together, determining the order in which nodes are activated","items":{"type":"object","required":["source","target"],"properties":{"id":{"type":"string"},"config":{"type":"object","properties":{"condition":{"type":"string"},"mapper":{"type":"object","properties":{}}}},"source":{"type":"string","description":"The source node of this edge, referring to the id field of a node"},"target":{"type":"string","description":"The target node of this edge, referring to the id field of a node"}}}}}},"Owner":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"External id of the owner"},"type":{"type":"string","description":"Type to discriminate between user or tenant"}}},"Flow":{"allOf":[{"$ref":"#/components/schemas/MutableFlow"},{"type":"object","required":["id","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"status":{"type":"string","description":"Flow status, set automatically in response to start/stop commands","enum":["active","inactive","starting","stopping"]},"createdAt":{"type":"string","description":"Timestamp of flow creation","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp of most recent flow update","format":"date-time"}}}]}}}}
```

## Start a flow

> Initiates the flow's integration process by publishing an appropriate event to the event bus. Requires the 'flows.control' permission.

```json
{"openapi":"3.0.1","info":{"title":"Default module","version":"1.0.0"},"tags":[{"name":"flows"}],"security":[],"paths":{"/flows/{id}/start":{"post":{"summary":"Start a flow","deprecated":false,"description":"Initiates the flow's integration process by publishing an appropriate event to the event bus. Requires the 'flows.control' permission.","operationId":"startFlow","tags":["flows"],"parameters":[{"name":"id","in":"path","description":"ID of flow to start, must be a valid MongoDB ID.","required":true,"schema":{"type":"string","format":"string"}}],"responses":{"200":{"description":"Returns the id and new status of the flow","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}},"meta":{"type":"object","properties":{}}}}}},"headers":{}},"400":{"description":"Invalid ID format.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}},"403":{"description":"User is not authorised to start flows.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}},"404":{"description":"No Flow with this id was found.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}},"409":{"description":"Flow is currently not inactive. Only inactive flows can be started.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}}}}}}}
```

## Stop a flow

> Stops the flow's integration process by publishing an appropriate event to the event bus. Requires the 'flows.control' permission.

```json
{"openapi":"3.0.1","info":{"title":"Default module","version":"1.0.0"},"tags":[{"name":"flows"}],"security":[],"paths":{"/flows/{id}/stop":{"post":{"summary":"Stop a flow","deprecated":false,"description":"Stops the flow's integration process by publishing an appropriate event to the event bus. Requires the 'flows.control' permission.","operationId":"stopFlow","tags":["flows"],"parameters":[{"name":"id","in":"path","description":"ID of flow to stop, must be a valid MongoDB ID.","required":true,"schema":{"type":"string","format":"string"}}],"responses":{"200":{"description":"Returns id and new status of the stopped flow","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}},"meta":{"type":"object","properties":{}}}}}},"headers":{}},"400":{"description":"Invalid ID format.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}},"403":{"description":"User is not authorised to stop flows.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}},"404":{"description":"No Flow with this id was found.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}},"409":{"description":"Flow is currently not active. Only active flows can be stopped.","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}}}}}}}
```