Ctrlk
ForumChangelog
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Projects

Operations about projects

Retrieve projects

get
/projects

Retrieve projects from your instance.

Authorizations
X-N8N-API-KEYstringRequired
Query parameters
limitnumber · max: 250Optional

The maximum number of items to return.

Default: 100Example: 100
cursorstringOptional

Paginate by setting the cursor parameter to the nextCursor attribute returned by the previous request's response. Default value fetches the first "page" of the collection. See pagination for more detail.

Responses
200

Operation successful.

application/json
nextCursorstring · nullableRequired

Paginate through projects by setting the cursor parameter to a nextCursor attribute returned by a previous request. Default value fetches the first "page" of the collection.

Example: eyJvZmZzZXQiOjEwMCwibGltaXQiOjEwMH0=
get/projects
GET /api/v1/projects HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "VmwOO9HeTEj20kxM",
      "name": "Marketing",
      "type": "team",
      "icon": {
        "type": "emoji",
        "value": "text",
        "color": "text"
      },
      "description": "Workflows the marketing team owns.",
      "customTelemetryTags": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "creatorId": "f9a2cbb8-0b1e-4b64-9c1c-0d5f5f1f2a3b",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjEwMCwibGltaXQiOjEwMH0="
}

Create a project

post
/projects

Create a team project on your instance.

Authorizations
X-N8N-API-KEYstringRequired
Body
namestring · min: 1 · max: 255RequiredExample: Marketing
idstring · min: 1 · max: 36Optional

Project ID. The server generates an ID when omitted. An ID that is in use returns HTTP 409.

Example: VmwOO9HeTEj20kxM
descriptionstring · max: 512 · nullableOptionalExample: Workflows the marketing team owns.
typestringRead-onlyOptional
Responses
201

Operation successful.

application/json
idstringRead-onlyRequiredExample: VmwOO9HeTEj20kxM
namestringRequiredExample: Marketing
typestring · enumRead-onlyRequiredExample: teamPossible values:
descriptionstring · nullableRequiredExample: Workflows the marketing team owns.
creatorIdstring · nullableRequiredExample: f9a2cbb8-0b1e-4b64-9c1c-0d5f5f1f2a3b
createdAtstring · date-timeRead-onlyRequired
updatedAtstring · date-timeRead-onlyRequired
rolestringRequired

The caller's role in the new project.

Example: project:admin
scopesstring[]Required

Scopes the caller holds in the new project.

post/projects
POST /api/v1/projects HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 203

{
  "name": "Marketing",
  "id": "VmwOO9HeTEj20kxM",
  "icon": {
    "type": "emoji",
    "value": "text",
    "color": "text"
  },
  "description": "Workflows the marketing team owns.",
  "customTelemetryTags": [
    {
      "key": "text",
      "value": "text"
    }
  ]
}
{
  "id": "VmwOO9HeTEj20kxM",
  "name": "Marketing",
  "type": "team",
  "icon": {
    "type": "emoji",
    "value": "text",
    "color": "text"
  },
  "description": "Workflows the marketing team owns.",
  "customTelemetryTags": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "creatorId": "f9a2cbb8-0b1e-4b64-9c1c-0d5f5f1f2a3b",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "role": "project:admin",
  "scopes": [
    "text"
  ]
}

Update a project

put
/projects/{projectId}

Update a project on your instance.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
projectIdstringRequired

The ID of the project.

Body
namestring · min: 1 · max: 255RequiredExample: Marketing
idstringRead-onlyOptional
typestringRead-onlyOptional
Responses
204

Operation successful.

No content
put/projects/{projectId}
PUT /api/v1/projects/{projectId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "name": "Marketing"
}
No content

Delete a project

delete
/projects/{projectId}

Delete a project from your instance.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
projectIdstringRequired

The ID of the project.

Responses
204

Operation successful.

No content
delete/projects/{projectId}
DELETE /api/v1/projects/{projectId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

No content

List project members

get
/projects/{projectId}/users

Returns a list of all members of a project including their role. Requires user:list scope.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
projectIdstringRequired

The ID of the project.

Query parameters
limitnumber · max: 250Optional

The maximum number of items to return.

Default: 100Example: 100
cursorstringOptional

Paginate by setting the cursor parameter to the nextCursor attribute returned by the previous request's response. Default value fetches the first "page" of the collection. See pagination for more detail.

Responses
200

Operation successful.

application/json
nextCursorstring · nullableRequired

Paginate through project members by setting the cursor parameter to the nextCursor attribute returned by a previous request. Default value fetches the first page of the collection.

Example: eyJvZmZzZXQiOjEwMCwibGltaXQiOjEwMH0=
get/projects/{projectId}/users
GET /api/v1/projects/{projectId}/users HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "john.doe@company.com",
      "firstName": "john",
      "lastName": "Doe",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "role": "project:viewer"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjEwMCwibGltaXQiOjEwMH0="
}

Add one or more users to a project

post
/projects/{projectId}/users

Add one or more users to a project on your instance.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
projectIdstringRequired

The ID of the project.

Body
Responses
201

Operation successful.

No content
post/projects/{projectId}/users
POST /api/v1/projects/{projectId}/users HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "relations": [
    {
      "userId": "91765f0d-3b29-45df-adb9-35b23937eb92",
      "role": "project:viewer"
    }
  ]
}
No content

Delete a user from a project

delete
/projects/{projectId}/users/{userId}

Delete a user from a project on your instance.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
projectIdstringRequired

The ID of the project.

userIdstringRequired

The ID of the user.

Responses
204

Operation successful.

No content
delete/projects/{projectId}/users/{userId}
DELETE /api/v1/projects/{projectId}/users/{userId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

No content

Change a user's role in a project

patch
/projects/{projectId}/users/{userId}

Change a user's role in a project.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
projectIdstringRequired

The ID of the project.

userIdstringRequired

The ID of the user.

Body
rolestring · min: 1Required

The role assigned to the user in the project.

Example: project:viewer
Responses
204

Operation successful.

No content
patch/projects/{projectId}/users/{userId}
PATCH /api/v1/projects/{projectId}/users/{userId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "role": "project:viewer"
}
No content
PreviousNode Type Policy
NextPromotions

Last updated

Was this helpful?