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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://flowmate.gitbook.io/flowmate-documentation/api-reference/flows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.