Members API

Overview

The Members API allows you to manage team members at both workspace and project levels. Members can have different roles with varying permissions.

Member roles

Members can have one of three roles:

Role	Value	Description
Guest	5	Limited access, can view and comment
Member	15	Standard access, can create and edit items
Admin	20	Full access, can manage settings and members

Members must first be added to a workspace before they can be added to projects within that workspace.

Workspace members

List workspace members

GET /api/v1/workspaces/{workspace_slug}/members/

Retrieve all members in a workspace.

string

required

Workspace identifier

Response

uuid

Workspace member ID

object

User information

Show properties

uuid

User UUID

string

User email address

string

User display name

string

User avatar URL

number

Member role: 5 (Guest), 15 (Member), 20 (Admin)

Example

curl -X GET \
  "https://api.plane.so/api/v1/workspaces/acme/members/" \
  -H "X-Api-Key: your-api-key"

Project members

List project members

GET /api/v1/workspaces/{workspace_slug}/projects/{project_id}/members/

Retrieve all members in a project.

string

required

Workspace identifier

uuid

required

Project UUID

Response

uuid

Project member ID

uuid

User ID (reference to User)

number

Project role: 5 (Guest), 15 (Member), 20 (Admin)

Example

curl -X GET \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/members/" \
  -H "X-Api-Key: your-api-key"

Add project member

POST /api/v1/workspaces/{workspace_slug}/projects/{project_id}/members/

Add a workspace member to a project.

uuid

required

User ID to add to the project

number

required

Project role: 5 (Guest), 15 (Member), or 20 (Admin)

The user must already be a member of the workspace. Add them to the workspace first if needed.

Example

curl -X POST \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/members/" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "member": "user-uuid",
    "role": 15
  }'

Validation errors

{
  "member": ["Member not found in workspace"]
}

{
  "role": ["Invalid role"]
}

Update project member

PATCH /api/v1/workspaces/{workspace_slug}/projects/{project_id}/members/{member_id}/

Update a project member’s role.

uuid

required

Project member UUID

number

Updated role: 5 (Guest), 15 (Member), or 20 (Admin)

Example

curl -X PATCH \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/members/member-uuid/" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "role": 20
  }'

Remove project member

DELETE /api/v1/workspaces/{workspace_slug}/projects/{project_id}/members/{member_id}/

Remove a member from the project.

This only removes the member from the project, not from the workspace.

Example

curl -X DELETE \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/members/member-uuid/" \
  -H "X-Api-Key: your-api-key"

Member permissions

Guest (role: 5)

View work items and project data
Add comments
Cannot create or edit work items

Member (role: 15)

All Guest permissions
Create and edit work items
Manage cycles and modules
Cannot modify project settings

Admin (role: 20)

All Member permissions
Manage project settings
Add/remove project members
Archive/delete project

Using members with work items

Assign members to work items:

{
  "name": "Fix navigation bug",
  "assignees": ["user-uuid-1", "user-uuid-2"]
}

Best practices

Workspace first - Always add users to the workspace before adding them to projects

Least privilege - Start with Guest or Member roles and promote to Admin only when needed

Validation - Always check workspace membership before adding to projects

Error handling

Common validation errors:

Error	Cause	Solution
Member not found in workspace	User not in workspace	Add to workspace first
Invalid role	Role value not 5, 15, or 20	Use valid role value
Member is required	Missing member field	Include member UUID
Slug is required	Missing workspace slug	Include workspace slug in context

Overview

Endpoints

Overview

Member roles

Workspace members

List workspace members

Project members

List project members

Add project member

Update project member

Remove project member

Member permissions

Guest (role: 5)

Member (role: 15)

Admin (role: 20)

Using members with work items

Best practices

Error handling

Next steps

Work Items API

Projects API

​Overview

​Member roles

​Workspace members

​List workspace members

​Project members

​List project members

​Add project member

​Update project member

​Remove project member

​Member permissions

​Guest (role: 5)

​Member (role: 15)

​Admin (role: 20)

​Using members with work items

​Best practices

​Error handling

​Next steps

Work Items API

Projects API

Overview

Member roles

Workspace members

List workspace members

Project members

List project members

Add project member

Update project member

Remove project member

Member permissions

Guest (role: 5)

Member (role: 15)

Admin (role: 20)

Using members with work items

Best practices

Error handling

Next steps