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

uuid

Unique workspace identifier

string

Human-readable workspace name

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.

Search

GET

Searches only within the specified workspace.

Multi-Workspace Access

API keys are scoped to a specific workspace. To access multiple workspaces, you need:

Separate API keys for each workspace, or
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

​Workspaces API

​Overview

​Workspace Identifier

​Workspace in API Responses

​Workspace Fields

​Using Workspace Slug

​List Projects in Workspace

​Search Work Items in Workspace

​Create Project in Workspace

​Finding Your Workspace Slug

​From the Plane URL

​From API Responses

​From Search Results

​Workspace Members

​Member Roles

​Member Validation

​Workspace Context in APIs

​Projects

​Work Items

​Search

​Multi-Workspace Access

​Example: Multi-Step Workflow

​Workspace Validation

​Invalid Workspace Slug

​Insufficient Permissions

​Best Practices

​Use Workspace Slug Consistently

​Validate Workspace Access

​Handle Multiple Workspaces

​Related Endpoints

Projects

Work Items

Users

Authentication

Workspaces API

Overview

Workspace Identifier

Workspace in API Responses

Workspace Fields

Using Workspace Slug

List Projects in Workspace

Search Work Items in Workspace

Create Project in Workspace

Finding Your Workspace Slug

From the Plane URL

From API Responses

From Search Results

Workspace Members

Member Roles

Member Validation

Workspace Context in APIs

Projects

Work Items

Search

Multi-Workspace Access

Example: Multi-Step Workflow

Workspace Validation

Invalid Workspace Slug

Insufficient Permissions

Best Practices

Use Workspace Slug Consistently

Validate Workspace Access

Handle Multiple Workspaces

Related Endpoints