> 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"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"folder":{"type":"object","additionalProperties":false,"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}}}},"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":{"tags":["Folders"],"summary":"Retrieve folders","description":"Retrieve folders within a project. Supports filtering, sorting, field selection, and pagination.","parameters":[{"name":"projectId","in":"path","description":"The ID of the project.","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","required":false,"description":"JSON-encoded filter object. Supported fields — parentFolderId, name, tags (array of tag names), excludeFolderIdAndDescendants.","schema":{"type":"string"}},{"name":"select","in":"query","required":false,"description":"JSON-encoded array of fields to include. Valid fields — id, name, createdAt, updatedAt, project, tags, parentFolder, workflowCount, subFolderCount, path.","schema":{"type":"string"}},{"name":"sortBy","in":"query","required":false,"description":"Sort order for results.","schema":{"type":"string","enum":["name:asc","name:desc","createdAt:asc","createdAt:desc","updatedAt:asc","updatedAt:desc"]}},{"name":"skip","in":"query","required":false,"description":"Number of items to skip for pagination. Defaults to 0.","schema":{"type":"string"}},{"name":"take","in":"query","required":false,"description":"Number of items to return. Defaults to 10.","schema":{"type":"string"}}],"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":{"$ref":"#/components/schemas/folder"}}}}}}},"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"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"folder.create":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string"},"parentFolderId":{"type":"string"}}},"folder":{"type":"object","additionalProperties":false,"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}}}},"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":{"post":{"tags":["Folders"],"summary":"Create a folder","description":"Create a folder within a project.","parameters":[{"name":"projectId","in":"path","description":"The ID of the project.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Payload for folder to create.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/folder.create"}}},"required":true},"responses":{"201":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/folder"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## 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"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/projects/{projectId}/folders/{folderId}":{"get":{"tags":["Folders"],"summary":"Get folder details","description":"Get folder details including sub-folder and workflow counts.","parameters":[{"name":"projectId","in":"path","description":"The ID of the project.","required":true,"schema":{"type":"string"}},{"name":"folderId","in":"path","description":"The ID of the folder.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"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)."}}}}}},"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"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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":{"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":[{"name":"projectId","in":"path","description":"The ID of the project.","required":true,"schema":{"type":"string"}},{"name":"folderId","in":"path","description":"The ID of the folder.","required":true,"schema":{"type":"string"}},{"name":"transferToFolderId","in":"query","description":"Optional target folder ID to move workflows and sub-folders into before deleting.","required":false,"schema":{"type":"string"}}],"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"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"folder.update":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string"},"parentFolderId":{"type":"string"}}},"folder":{"type":"object","additionalProperties":false,"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}}}},"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}":{"patch":{"tags":["Folders"],"summary":"Update a folder","description":"Update folder name or parent folder.","parameters":[{"name":"projectId","in":"path","description":"The ID of the project.","required":true,"schema":{"type":"string"}},{"name":"folderId","in":"path","description":"The ID of the folder.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Payload for folder update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/folder.update"}}},"required":true},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/folder"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.n8n.io/connect/n8n-api/folders.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.