Skip to main content
Workspaces are the top-level organizational containers in PraisonAI Platform that hold projects, issues, agents, and team 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

OperationEndpointDescription
CreatePOST /api/v1/workspaces/Create new workspace
ListGET /api/v1/workspaces/List user workspaces
GetGET /api/v1/workspaces/{id}Get specific workspace
UpdatePATCH /api/v1/workspaces/{id}Update workspace
DeleteDELETE /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
    await client.delete_workspace(workspace["id"])

​
Key Concepts

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.
Users can own or belong to multiple workspaces. Access control ensures users only see workspaces they have permissions for.
Flexible JSON dictionary for workspace-level configuration like themes, notification preferences, or feature toggles.
Workspaces → Projects → Issues/Agents/Tasks. Workspaces provide the top-level boundary for organizing work and team access.

​
Best Practices

Use descriptive names that reflect the team or purpose. Avoid generic names like “Workspace 1”. Good examples: “Marketing Team”, “Backend Services”, “Client Projects”.
Choose memorable slugs for URLs. Use hyphens, not underscores. Keep them short but descriptive: marketing-team not marketing_team_workspace_2024.
Use settings for workspace-wide preferences. Store user preferences separately. Common settings: theme, defaultProject, notifications.
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

Projects

Organize work within workspaces using projects

Members

Manage team access and permissions