> 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/projects.md).

# Projects

Operations about projects

## Retrieve projects

> Retrieve projects from your instance.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Projects","description":"Operations about projects"}],"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":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"limit":{"name":"limit","in":"query","description":"The maximum number of items to return.","required":false,"schema":{"type":"number","default":100,"maximum":250}},"cursor":{"name":"cursor","in":"query","description":"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.","required":false,"style":"form","schema":{"type":"string"}}},"schemas":{"projectList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/project"}},"nextCursor":{"type":"string","description":"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.","nullable":true}}},"project":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"type":{"type":"string","readOnly":true}}}},"responses":{"unauthorized":{"description":"Unauthorized"}}},"paths":{"/projects":{"get":{"tags":["Projects"],"summary":"Retrieve projects","description":"Retrieve projects from your instance.","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/projectList"}}}},"401":{"$ref":"#/components/responses/unauthorized"}}}}}}
```

## Create a project

> Create a project on your instance.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Projects","description":"Operations about projects"}],"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":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"project":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"type":{"type":"string","readOnly":true}}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"}}},"paths":{"/projects":{"post":{"tags":["Projects"],"summary":"Create a project","description":"Create a project on your instance.","requestBody":{"description":"Payload for project to create.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/project"}}},"required":true},"responses":{"201":{"description":"Operation successful."},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"}}}}}}
```

## Update a project

> Update a project on your instance.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Projects","description":"Operations about projects"}],"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":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"project":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"type":{"type":"string","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}":{"put":{"tags":["Projects"],"summary":"Update a project","description":"Update a project on your instance.","parameters":[{"in":"path","name":"projectId","description":"The ID of the project.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Updated project object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/project"}}},"required":true},"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"}}}}}}
```

## Delete a project

> Delete a project from your instance.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Projects","description":"Operations about projects"}],"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":[]}],"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}":{"delete":{"tags":["Projects"],"summary":"Delete a project","description":"Delete a project from your instance.","parameters":[{"in":"path","name":"projectId","description":"The ID of the project.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Operation successful."},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## List project members

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Projects","description":"Operations about projects"}],"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":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"limit":{"name":"limit","in":"query","description":"The maximum number of items to return.","required":false,"schema":{"type":"number","default":100,"maximum":250}},"cursor":{"name":"cursor","in":"query","description":"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.","required":false,"style":"form","schema":{"type":"string"}}},"schemas":{"projectMemberList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/projectMember"}},"nextCursor":{"type":"string","description":"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.","nullable":true}}},"projectMember":{"type":"object","description":"A project member (user with their role in the project).","properties":{"id":{"type":"string","description":"The user's unique identifier.","readOnly":true},"email":{"type":"string","format":"email","description":"The user's email address.","readOnly":true},"firstName":{"type":"string","maxLength":32,"description":"The user's first name.","readOnly":true},"lastName":{"type":"string","maxLength":32,"description":"The user's last name.","readOnly":true},"createdAt":{"type":"string","format":"date-time","description":"When the user was created.","readOnly":true},"updatedAt":{"type":"string","format":"date-time","description":"When the user was last updated.","readOnly":true},"role":{"type":"string","description":"The user's role in the project (e.g. project:admin, project:viewer).","readOnly":true}}}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/projects/{projectId}/users":{"get":{"tags":["Projects"],"summary":"List project members","description":"Returns a list of all members of a project including their role. Requires user:list scope.","parameters":[{"name":"projectId","in":"path","description":"The ID of the project.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/projectMemberList"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Add one or more users to a project

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Projects","description":"Operations about projects"}],"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":[]}],"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}/users":{"post":{"tags":["Projects"],"summary":"Add one or more users to a project","description":"Add one or more users to a project on your instance.","parameters":[{"name":"projectId","in":"path","description":"The ID of the project.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Payload containing an array of one or more users to add to the project.","content":{"application/json":{"schema":{"type":"object","properties":{"relations":{"type":"array","description":"A list of userIds and roles to add to the project.","items":{"type":"object","properties":{"userId":{"type":"string","description":"The unique identifier of the user."},"role":{"type":"string","description":"The role assigned to the user in the project."}},"required":["userId","role"]}}},"required":["relations"]}}}},"responses":{"201":{"description":"Operation successful."},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Delete a user from a project

> Delete a user from a project on your instance.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Projects","description":"Operations about projects"}],"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":[]}],"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}/users/{userId}":{"delete":{"tags":["Projects"],"summary":"Delete a user from a project","description":"Delete a user from a project on your instance.","parameters":[{"name":"projectId","in":"path","description":"The ID of the project.","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","description":"The ID of the user.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Operation successful."},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Change a user's role in a project

> Change a user's role in a project.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Projects","description":"Operations about projects"}],"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":[]}],"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}/users/{userId}":{"patch":{"tags":["Projects"],"summary":"Change a user's role in a project","description":"Change a user's role in a project.","parameters":[{"name":"projectId","in":"path","description":"The ID of the project.","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","description":"The ID of the user.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Payload containing the new role to assign to the project user.","content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","description":"The role assigned to the user in the project."}},"required":["role"]}}}},"responses":{"204":{"description":"Operation successful."},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```