Folders

Operations about folders

Retrieve folders

get

/projects/{projectId}/folders

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

Authorizations

X-N8N-API-KEYstringRequired

Path parameters

projectIdstringRequired

The ID of the project.

Query parameters

filterstringOptional

JSON-encoded filter object. Supported fields — parentFolderId, name, tags (array of tag names), excludeFolderIdAndDescendants.

Example: {"parentFolderId":"abc123","name":"My Folder"}

selectstringOptional

JSON-encoded array of fields to include. Valid fields — id, name, createdAt, updatedAt, project, tags, parentFolder, workflowCount, subFolderCount, path.

Example: ["id","name","tags","workflowCount"]

sortBystring · enumOptional

Sort order for results.

Possible values:

skipstringOptional

Number of items to skip for pagination. Defaults to 0.

takestringOptional

Number of items to return. Defaults to 10.

Responses

200

Operation successful.

application/json

countintegerRequired

Total number of folders matching the query.

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

get/projects/{projectId}/folders

GET /api/v1/projects/{projectId}/folders HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "count": 1,
  "data": [
    {
      "id": "zLXWgYyZrZ4Gn1Vk",
      "name": "My Folder",
      "parentFolderId": "kRZ0ewrAEAhCkTBd",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "homeProject": {
        "id": "VmwOO9HeTEj20kxM",
        "name": "Marketing",
        "type": "team",
        "icon": {
          "type": "emoji",
          "value": "text",
          "color": "text"
        }
      },
      "parentFolder": {
        "id": "zLXWgYyZrZ4Gn1Vk",
        "name": "My Folder",
        "parentFolderId": "text"
      },
      "tags": [
        {
          "id": "text",
          "name": "text"
        }
      ],
      "workflowCount": 1,
      "subFolderCount": 1,
      "path": [
        "Marketing",
        "Campaigns"
      ]
    }
  ]
}

Create a folder

post

/projects/{projectId}/folders

Create a folder within a project.

Authorizations

X-N8N-API-KEYstringRequired

Path parameters

projectIdstringRequired

The ID of the project, or personal to create the folder in the calling user's own personal project.

Body

namestring · max: 128RequiredExample: My Folder

parentFolderIdstring · max: 36OptionalExample: kRZ0ewrAEAhCkTBd

Responses

201

Operation successful.

application/json

idstringRead-onlyRequiredExample: zLXWgYyZrZ4Gn1Vk

namestringRequiredExample: My Folder

parentFolderIdstring · nullableRequiredExample: kRZ0ewrAEAhCkTBd

createdAtstring · date-timeRead-onlyRequired

updatedAtstring · date-timeRead-onlyRequired

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

415

Unsupported media type.

post/projects/{projectId}/folders

POST /api/v1/projects/{projectId}/folders HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "name": "My Folder",
  "parentFolderId": "kRZ0ewrAEAhCkTBd"
}

{
  "id": "zLXWgYyZrZ4Gn1Vk",
  "name": "My Folder",
  "parentFolderId": "kRZ0ewrAEAhCkTBd",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Get folder details

get

/projects/{projectId}/folders/{folderId}

Get folder details including sub-folder and workflow counts.

Authorizations

X-N8N-API-KEYstringRequired

Path parameters

projectIdstringRequired

The ID of the project.

folderIdstringRequired

The ID of the folder.

Responses

200

Operation successful.

application/json

idstringRead-onlyRequiredExample: zLXWgYyZrZ4Gn1Vk

namestringRequiredExample: My Folder

parentFolderIdstring · nullableRequiredExample: kRZ0ewrAEAhCkTBd

createdAtstring · date-timeRead-onlyRequired

updatedAtstring · date-timeRead-onlyRequired

totalSubFoldersintegerRequired

Total number of sub-folders (recursive).

totalWorkflowsintegerRequired

Total number of workflows (recursive).

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

get/projects/{projectId}/folders/{folderId}

GET /api/v1/projects/{projectId}/folders/{folderId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "id": "zLXWgYyZrZ4Gn1Vk",
  "name": "My Folder",
  "parentFolderId": "kRZ0ewrAEAhCkTBd",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "totalSubFolders": 1,
  "totalWorkflows": 1
}

Delete a folder

delete

/projects/{projectId}/folders/{folderId}

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.

Authorizations

X-N8N-API-KEYstringRequired

Path parameters

projectIdstringRequired

The ID of the project.

folderIdstringRequired

The ID of the folder.

Query parameters

transferToFolderIdstring · min: 1 · max: 36Optional

Optional target folder ID to move workflows and sub-folders into before deleting.

Responses

204

Operation successful.

No content

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

delete/projects/{projectId}/folders/{folderId}

DELETE /api/v1/projects/{projectId}/folders/{folderId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

No content

Update a folder

patch

/projects/{projectId}/folders/{folderId}

Update folder name or parent folder.

Authorizations

X-N8N-API-KEYstringRequired

Path parameters

projectIdstringRequired

The ID of the project.

folderIdstringRequired

The ID of the folder.

Body

namestring · max: 128OptionalExample: Renamed Folder

parentFolderIdstringOptional

ID of the parent folder to move this folder into. Set to "0" to move the folder to the project root.

Example: abc123

Responses

200

Operation successful.

application/json

idstringRead-onlyRequiredExample: zLXWgYyZrZ4Gn1Vk

namestringRequiredExample: My Folder

parentFolderIdstring · nullableRequiredExample: kRZ0ewrAEAhCkTBd

createdAtstring · date-timeRead-onlyRequired

updatedAtstring · date-timeRead-onlyRequired

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

415

Unsupported media type.

patch/projects/{projectId}/folders/{folderId}

PATCH /api/v1/projects/{projectId}/folders/{folderId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "name": "Renamed Folder",
  "parentFolderId": "abc123"
}

{
  "id": "zLXWgYyZrZ4Gn1Vk",
  "name": "My Folder",
  "parentFolderId": "kRZ0ewrAEAhCkTBd",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}