Platform Workspace Management

Create, manage, and organize projects in multi-tenant workspace containers

Workspaces are the top-level organizational containers in PraisonAI Platform that hold projects, issues, agents, and team members.

Workspaces are the top-level organizational containers in PraisonAI Platform that hold projects, issues, agents, and team members.

import os
from praisonaiagents import Agent
from praisonai_platform import PlatformClient

agent = Agent(name="platform-assistant", instructions="Organise team workspaces.")
agent.start("Create a workspace for the Q3 product launch.")

The user asks the agent to organise work; PlatformClient creates workspaces that hold projects, issues, and members.

Quick Start

1. Create Workspace

   TOKEN="your-jwt-token"
   
   curl -s -X POST http://localhost:8000/api/v1/workspaces/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"My Team","slug":"my-team","description":"Dev workspace"}' \
     --max-time 10
   
2. List Workspaces

   curl -s "http://localhost:8000/api/v1/workspaces/?limit=10&offset=0" \
     -H "Authorization: Bearer $TOKEN" \
     --max-time 10
   

---

How It Works

Operation	Endpoint	Description
Create	POST /api/v1/workspaces/	Create new workspace
List	GET /api/v1/workspaces/	List user workspaces
Get	GET /api/v1/workspaces/{id}	Get specific workspace
Update	PATCH /api/v1/workspaces/{id}	Update workspace
Delete	DELETE /api/v1/workspaces/{id}	Delete workspace

---

API Reference

Create Workspace

Creates a new workspace with the specified configuration.

POST /api/v1/workspaces/

Request:

{
  "name": "My Team",
  "slug": "my-team",
  "description": "Our development workspace"
}

Response:

{
  "id": "ws-abc123",
  "name": "My Team",
  "slug": "my-team",
  "description": "Our development workspace",
  "settings": {},
  "created_at": "2025-01-01T00:00:00"
}

List Workspaces

Retrieves paginated list of user’s workspaces.

GET /api/v1/workspaces/?limit=10&offset=0

Query Parameters:

• limit (int): Results per page (default: 10, max: 100)
• offset (int): Pagination offset (default: 0)

Update Workspace

Updates workspace properties using partial data.

PATCH /api/v1/workspaces/{workspace_id}

Request:

{
  "name": "Updated Name",
  "description": "New description",
  "settings": {"theme": "dark"}
}

---

Python SDK Examples

Basic Operations

import asyncio
from praisonai_platform.client import PlatformClient

async def main():
    client = PlatformClient("http://localhost:8000", token="your-jwt-token")

    # Create workspace
    workspace = await client.create_workspace("My Team", slug="my-team")
    print(f"Created: {workspace['id']}")

    # List all workspaces
    workspaces = await client.list_workspaces()
    for ws in workspaces:
        print(f"Workspace: {ws['name']} ({ws['slug']})")

    # Get specific workspace
    details = await client.get_workspace(workspace["id"])
    print(f"Description: {details['description']}")

asyncio.run(main())

Advanced Management

async def workspace_management():
    client = PlatformClient("http://localhost:8000", token="your-jwt-token")
    
    # Create with custom settings
    workspace = await client.create_workspace(
        name="Production Team",
        slug="prod-team", 
        description="Production workspace",
        settings={"theme": "dark", "notifications": True}
    )
    
    # Update workspace
    updated = await client.update_workspace(
        workspace["id"],
        description="Updated production workspace"
    )
    
    # Clean up - this removes all data including members
    await client.delete_workspace(workspace["id"])

Workspace Deletion: Deleting a workspace now also removes all Member rows associated with it in the same transaction. Previously, memberships could be orphaned and surface in subsequent member lookups.

---

Key Concepts

Workspace Slug

URL-friendly identifier that’s auto-generated from name if not provided. Must be unique across the platform. Used for friendly URLs like /workspace/my-team.

Multi-tenancy

Users can own or belong to multiple workspaces. Access control ensures users only see workspaces they have permissions for.

Settings Object

Flexible JSON dictionary for workspace-level configuration like themes, notification preferences, or feature toggles.

Organizational Hierarchy

Workspaces → Projects → Issues/Agents/Tasks. Workspaces provide the top-level boundary for organizing work and team access.

---

Best Practices

Naming Convention

Use descriptive names that reflect the team or purpose. Avoid generic names like “Workspace 1”. Good examples: “Marketing Team”, “Backend Services”, “Client Projects”.

Slug Management

Choose memorable slugs for URLs. Use hyphens, not underscores. Keep them short but descriptive: marketing-team not marketing_team_workspace_2024.

Settings Strategy

Use settings for workspace-wide preferences. Store user preferences separately. Common settings: theme, defaultProject, notifications.

Access Control

Plan member permissions before inviting users. Consider using role-based access with workspace-level roles like owner, admin, member.

---

Testing

Test workspace operations to ensure proper functionality:

# Test workspace service
pytest tests/test_services.py::TestWorkspaceService -v

# Test API integration  
pytest tests/test_api_integration.py -v

# Test with real database
pytest tests/integration/test_workspace_crud.py -v

---

Related

Projects

Organize work within workspaces using projects

Members

Manage team access and permissions