> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/api-reference/flow-actions/flow-folders.md).

# Flow Folders

## List Flow Folders

> Return a flat list of all folders for the tenant, ordered by \`position\` then \`name\`. The frontend assembles the folder tree from \`parent\_id\` references.

```json
{"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Flow Folders"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: `<api-key>`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}}},"paths":{"/api/v1/flow-folders":{"get":{"summary":"List Flow Folders","description":"Return a flat list of all folders for the tenant, ordered by `position` then `name`. The frontend assembles the folder tree from `parent_id` references.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"}},"tags":["Flow Folders"]}}}}
```

## Create Flow Folder

> Create a new flow folder.

```json
{"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Flow Folders"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: `<api-key>`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/v1/flow-folders":{"post":{"summary":"Create Flow Folder","description":"Create a new flow folder.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":255,"description":"The folder name."},"parent_id":{"type":"integer","nullable":true,"description":"The ID of the parent folder. Omit or set to `null` for a root-level folder."},"position":{"type":"integer","nullable":true,"minimum":0,"description":"Display order position within the parent."}}}}}},"responses":{"201":{"description":"Folder created","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Flow Folders"]}}}}
```

## Update Flow Folder

> Update an existing flow folder. All fields are optional — only provided fields are updated.

```json
{"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Flow Folders"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: `<api-key>`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/v1/flow-folders/{flow_folder}":{"put":{"summary":"Update Flow Folder","description":"Update an existing flow folder. All fields are optional — only provided fields are updated.","parameters":[{"name":"flow_folder","in":"path","required":true,"schema":{"type":"integer"},"description":"The unique identifier of the flow folder."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"description":"The folder name."},"parent_id":{"type":"integer","nullable":true,"description":"The ID of the parent folder. Set to `null` to move to the root level."},"position":{"type":"integer","nullable":true,"minimum":0,"description":"Display order position within the parent."}}}}}},"responses":{"200":{"description":"Folder updated","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"},"404":{"description":"Folder not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Flow Folders"]}}}}
```

## Delete Flow Folder

> Delete a flow folder. If \`recursive\` is \`true\`, all descendant folders are also deleted and any flows inside them are detached (their folder assignment is cleared).

```json
{"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Flow Folders"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: `<api-key>`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}}},"paths":{"/api/v1/flow-folders/{flow_folder}":{"delete":{"summary":"Delete Flow Folder","description":"Delete a flow folder. If `recursive` is `true`, all descendant folders are also deleted and any flows inside them are detached (their folder assignment is cleared).","parameters":[{"name":"flow_folder","in":"path","required":true,"schema":{"type":"integer"},"description":"The unique identifier of the flow folder."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"recursive":{"type":"boolean","description":"If `true`, deletes all descendant folders and detaches their flows."}}}}}},"responses":{"200":{"description":"Folder deleted","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"},"404":{"description":"Folder not found"}},"tags":["Flow Folders"]}}}}
```