Skip to main content

​
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:
RoleValueDescription
Guest5Limited access, can view and comment
Member15Standard access, can create and edit items
Admin20Full 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.
​
workspace_slug
string
required
Workspace identifier
Response
​
id
uuid
Workspace member ID
​
member
object
User information
​
role
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.
​
workspace_slug
string
required
Workspace identifier
​
project_id
uuid
required
Project UUID
Response
​
id
uuid
Project member ID
​
member
uuid
User ID (reference to User)
​
role
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.
​
member
uuid
required
User ID to add to the project
​
role
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.
​
member_id
uuid
required
Project member UUID
​
role
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:
ErrorCauseSolution
Member not found in workspaceUser not in workspaceAdd to workspace first
Invalid roleRole value not 5, 15, or 20Use valid role value
Member is requiredMissing member fieldInclude member UUID
Slug is requiredMissing workspace slugInclude workspace slug in context

​
Next steps

Work Items API

Assign members to work items

Projects API

Manage project settings

Build docs developers (and LLMs) love

Get started for freeTalk to us