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

# Folders

Operations about folders

## Retrieve folders

> Retrieve folders within a project. Supports filtering, sorting, field selection, and pagination.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Folders","description":"Operations about folders"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/projects/{projectId}/folders":{"get":{"operationId":"listFolders","tags":["Folders"],"summary":"Retrieve folders","description":"Retrieve folders within a project. Supports filtering, sorting, field selection, and pagination.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the project.","name":"projectId","in":"path"},{"schema":{"type":"string","description":"JSON-encoded filter object. Supported fields — parentFolderId, name, tags (array of tag names), excludeFolderIdAndDescendants."},"required":false,"name":"filter","in":"query"},{"schema":{"type":"string","description":"JSON-encoded array of fields to include. Valid fields — id, name, createdAt, updatedAt, project, tags, parentFolder, workflowCount, subFolderCount, path."},"required":false,"name":"select","in":"query"},{"schema":{"type":"string","enum":["name:asc","name:desc","createdAt:asc","createdAt:desc","updatedAt:asc","updatedAt:desc"],"description":"Sort order for results."},"required":false,"name":"sortBy","in":"query"},{"schema":{"type":"string","description":"Number of items to skip for pagination. Defaults to 0."},"required":false,"name":"skip","in":"query"},{"schema":{"type":"string","description":"Number of items to return. Defaults to 10."},"required":false,"name":"take","in":"query"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of folders matching the query."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"parentFolderId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"homeProject":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"type":{"type":"string","readOnly":true,"enum":["personal","team"]},"icon":{"type":"object","description":"Icon of the project, or null when the project has none","properties":{"type":{"type":"string","enum":["emoji","icon"]},"value":{"type":"string"},"color":{"type":"string"}},"required":["type","value"],"nullable":true}},"required":["id","name","type","icon"]},"parentFolder":{"type":"object","nullable":true,"properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"parentFolderId":{"type":"string","nullable":true}},"required":["id","name","parentFolderId"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"workflowCount":{"type":"number","description":"Number of workflows the folder holds.","readOnly":true},"subFolderCount":{"type":"number","description":"Number of folders the folder holds.","readOnly":true},"path":{"type":"array","items":{"type":"string"},"description":"Names of every folder from the project root down to this folder.","readOnly":true}},"required":["id"]}}},"required":["count","data"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Create a folder

> Create a folder within a project.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Folders","description":"Operations about folders"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"unsupportedMediaType":{"description":"Unsupported media type."}}},"paths":{"/projects/{projectId}/folders":{"post":{"operationId":"createFolder","tags":["Folders"],"summary":"Create a folder","description":"Create a folder within a project.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the project, or `personal` to create the folder in the calling user's own personal project.","name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":128},"parentFolderId":{"type":"string","maxLength":36}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"parentFolderId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true}},"required":["id","name","parentFolderId","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"415":{"$ref":"#/components/responses/unsupportedMediaType"}}}}}}
```

## Get folder details

> Get folder details including sub-folder and workflow counts.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Folders","description":"Operations about folders"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/projects/{projectId}/folders/{folderId}":{"get":{"operationId":"getFolder","tags":["Folders"],"summary":"Get folder details","description":"Get folder details including sub-folder and workflow counts.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the project.","name":"projectId","in":"path"},{"schema":{"type":"string"},"required":true,"description":"The ID of the folder.","name":"folderId","in":"path"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"parentFolderId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"totalSubFolders":{"type":"integer","description":"Total number of sub-folders (recursive)."},"totalWorkflows":{"type":"integer","description":"Total number of workflows (recursive)."}},"required":["id","name","parentFolderId","createdAt","updatedAt","totalSubFolders","totalWorkflows"]}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Delete a folder

> Delete a folder within a project. When \`transferToFolderId\` is provided, workflows and sub-folders are moved to the target folder before deletion. When omitted, workflows are moved to the project root and archived, and child folders are deleted.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Folders","description":"Operations about folders"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/projects/{projectId}/folders/{folderId}":{"delete":{"operationId":"deleteFolder","tags":["Folders"],"summary":"Delete a folder","description":"Delete a folder within a project. When `transferToFolderId` is provided, workflows and sub-folders are moved to the target folder before deletion. When omitted, workflows are moved to the project root and archived, and child folders are deleted.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the project.","name":"projectId","in":"path"},{"schema":{"type":"string"},"required":true,"description":"The ID of the folder.","name":"folderId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":36,"description":"Optional target folder ID to move workflows and sub-folders into before deleting."},"required":false,"name":"transferToFolderId","in":"query"}],"responses":{"204":{"description":"Operation successful."},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Update a folder

> Update folder name or parent folder.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Folders","description":"Operations about folders"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"unsupportedMediaType":{"description":"Unsupported media type."}}},"paths":{"/projects/{projectId}/folders/{folderId}":{"patch":{"operationId":"updateFolder","tags":["Folders"],"summary":"Update a folder","description":"Update folder name or parent folder.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the project.","name":"projectId","in":"path"},{"schema":{"type":"string"},"required":true,"description":"The ID of the folder.","name":"folderId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":128},"parentFolderId":{"type":"string","description":"ID of the parent folder to move this folder into. Set to \"0\" to move the folder to the project root."}},"additionalProperties":false,"minProperties":1}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"parentFolderId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true}},"required":["id","name","parentFolderId","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"415":{"$ref":"#/components/responses/unsupportedMediaType"}}}}}}
```