Skip to main content

​
Workspaces API

Workspaces are the top-level organizational units in Plane. They contain projects, teams, and members.

​
Overview

Workspaces serve as the primary container for:
  • Projects: Organizational units for work items
  • Members: Users with various roles and permissions
  • Teams: Groups of members working together
  • Settings: Workspace-level configurations

​
Workspace Identifier

Workspaces are identified by a unique slug - a URL-friendly string identifier (e.g., acme, engineering-team). The workspace slug is used in all workspace-scoped API endpoints: 
/workspaces/{slug}/projects/
/workspaces/{slug}/work-items/
/workspaces/{slug}/members/

​
Workspace in API Responses

When workspaces appear in API responses, they typically use the lightweight WorkspaceLiteSerializer format: 
{
  "id": "750e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corporation",
  "slug": "acme"
}

​
Workspace Fields

​
id
uuid
Unique workspace identifier
​
name
string
Human-readable workspace name
​
slug
string
URL-friendly workspace identifier (unique across all workspaces)

​
Using Workspace Slug

The workspace slug is required for most API operations:

​
List Projects in Workspace

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/" \
  -H "X-Api-Key: your_api_key"

​
Search Work Items in Workspace

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/work-items/search/?q=authentication" \
  -H "X-Api-Key: your_api_key"

​
Create Project in Workspace

curl -X POST "https://api.plane.so/api/v1/workspaces/acme/projects/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Project",
    "identifier": "NEWPROJ"
  }'

​
Finding Your Workspace Slug

You can find your workspace slug in several ways:

​
From the Plane URL

When logged into Plane, your workspace slug appears in the URL: 
https://app.plane.so/acme/projects
                     ^^^^^
                workspace slug

​
From API Responses

Workspace information is included in many API responses: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Mobile App",
  "workspace_id": "750e8400-e29b-41d4-a716-446655440000",
  "workspace": {
    "id": "750e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corporation",
    "slug": "acme"
  }
}

​
From Search Results

Workspace information appears in work item search results: 
{
  "id": "650e8400-e29b-41d4-a716-446655440000",
  "name": "Fix authentication bug",
  "workspace__slug": "acme",
  "project__identifier": "MOBILE",
  "sequence_id": "42"
}

​
Workspace Members

Workspace members are users who have access to the workspace with specific roles:

​
Member Roles

​
Member Validation

Many API operations validate that users are workspace members:
  • Project Lead: Must be a workspace member
  • Default Assignee: Must be a workspace member
  • Work Item Assignees: Must be project members (role ≥ 15)

​
Workspace Context in APIs

All workspace-scoped operations automatically filter results to the specified workspace:

​
Projects

GET
Returns only projects in the specified workspace.

​
Work Items

GET
Returns only work items in projects within the specified workspace.
GET
Searches only within the specified workspace.

​
Multi-Workspace Access

API keys are scoped to a specific workspace. To access multiple workspaces, you need:
  1. Separate API keys for each workspace, or
  2. A service token with multi-workspace access

​
Example: Multi-Step Workflow

Here’s a common workflow using workspace context: 
# 1. Verify authentication and get user info
curl -X GET "https://api.plane.so/api/v1/users/me/" \
  -H "X-Api-Key: your_api_key"

# 2. List projects in workspace
curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/" \
  -H "X-Api-Key: your_api_key"

# 3. Get work items in a specific project
curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/work-items/" \
  -H "X-Api-Key: your_api_key"

# 4. Search across workspace
curl -X GET "https://api.plane.so/api/v1/workspaces/acme/work-items/search/?q=bug" \
  -H "X-Api-Key: your_api_key"

​
Workspace Validation

The API automatically validates workspace context:

​
Invalid Workspace Slug

Status: 404 Not Found 
{
  "detail": "Not found."
}

​
Insufficient Permissions

Status: 403 Forbidden 
{
  "detail": "You do not have permission to perform this action."
}

​
Best Practices

​
Use Workspace Slug Consistently

Store the workspace slug in your application configuration: 
WORKSPACE_SLUG = "acme"
BASE_URL = f"https://api.plane.so/api/v1/workspaces/{WORKSPACE_SLUG}"

​
Validate Workspace Access

Verify workspace access before performing operations: 
import requests

headers = {"X-Api-Key": "your_api_key"}

# Test workspace access
response = requests.get(
    f"https://api.plane.so/api/v1/workspaces/acme/projects/",
    headers=headers
)

if response.status_code == 200:
    print("Workspace access confirmed")
else:
    print("Cannot access workspace")

​
Handle Multiple Workspaces

If your integration supports multiple workspaces: 
workspaces = [
    {"slug": "acme", "api_key": "key_1"},
    {"slug": "engineering", "api_key": "key_2"}
]

for workspace in workspaces:
    response = requests.get(
        f"https://api.plane.so/api/v1/workspaces/{workspace['slug']}/projects/",
        headers={"X-Api-Key": workspace['api_key']}
    )
    # Process projects for each workspace

Projects

Manage projects within a workspace

Work Items

Access work items across workspace projects

Users

Retrieve user and member information

Authentication

Learn about workspace-scoped API keys

Build docs developers (and LLMs) love

Get started for freeTalk to us