Skip to main content
The Platform SDK provides a complete async Python client for interacting with the PraisonAI Platform API, featuring connection pooling for optimal performance and comprehensive CRUD operations for all platform resources.

​
Quick Start

1

Install Package

pip install praisonai-platform
2

Basic Usage

from praisonai_platform import PlatformClient

# Context manager (recommended - uses connection pooling)
async with PlatformClient("http://localhost:8000") as client:
    # Register and auto-set token
    await client.register("user@example.com", "password123")
    
    # Create workspace and project
    workspace = await client.create_workspace("My Team")
    project = await client.create_project(workspace["id"], "Sprint 1")
    
    # Create and manage issues
    issue = await client.create_issue(
        workspace["id"], 
        "Fix login bug", 
        project_id=project["id"]
    )
3

Standalone Usage

# Without context manager (creates client per request)
client = PlatformClient("http://localhost:8000", token="your-jwt-token")
workspaces = await client.list_workspaces()

​
Connection Pooling

The client supports two usage patterns with automatic connection pooling optimization:
PatternConnection StrategyPerformanceUse Case
Context ManagerSingle pooled client⚡ HighMultiple API calls
StandaloneClient per request🔄 StandardSingle API calls

​
API Methods

​
Authentication

async with PlatformClient("http://localhost:8000") as client:
    user_data = await client.register(
        email="user@example.com",
        password="secure123",
        name="John Doe"  # optional
    )
    # Token automatically set for future requests

​
Workspaces

# Create workspace
workspace = await client.create_workspace("Development Team", slug="dev-team")

# List all workspaces
workspaces = await client.list_workspaces()

# Get specific workspace
workspace = await client.get_workspace("workspace-id")

​
Members

# Add member to workspace
member = await client.add_member(
    workspace_id="ws-123",
    user_id="user-456", 
    role="admin"  # admin, member, viewer
)

# List workspace members
members = await client.list_members("ws-123")

​
Projects

# Create project
project = await client.create_project(
    workspace_id="ws-123",
    title="Q1 Sprint",
    description="First quarter development sprint"
)

# List projects
projects = await client.list_projects("ws-123")

# Get project details
project = await client.get_project("ws-123", "project-456")

​
Issues

# Create issue
issue = await client.create_issue(
    workspace_id="ws-123",
    title="Fix authentication bug",
    description="Users cannot log in with SSO",
    project_id="project-456",
    priority="high",  # none, low, medium, high, urgent
    assignee_type="user",
    assignee_id="user-789"
)

# List issues with filters
issues = await client.list_issues(
    workspace_id="ws-123",
    status="open",
    project_id="project-456"
)

​
Comments

# Add comment to issue
comment = await client.add_comment(
    workspace_id="ws-123",
    issue_id="issue-789",
    content="I'm investigating this bug now"
)

# List all comments on issue
comments = await client.list_comments("ws-123", "issue-789")

​
Agents

# Create agent
agent = await client.create_agent(
    workspace_id="ws-123",
    name="Code Reviewer",
    runtime_mode="cloud",  # local, cloud
    instructions="Review all code changes for security issues"
)

# List agents
agents = await client.list_agents("ws-123")

# Get agent details
agent = await client.get_agent("ws-123", "agent-456")

​
Labels

# Create label
label = await client.create_label(
    workspace_id="ws-123",
    name="bug",
    color="#ff0000",
    description="Bug reports"
)

# List labels
labels = await client.list_labels("ws-123")

​
Dependencies

# Create dependency between issues
dependency = await client.create_dependency(
    workspace_id="ws-123",
    blocker_id="issue-123",  # Issue that blocks
    blocked_id="issue-456"   # Issue that is blocked
)

# List dependencies for workspace
dependencies = await client.list_dependencies("ws-123")

​
Activity Tracking

# Get workspace activity feed
activities = await client.list_workspace_activity(
    workspace_id="ws-123",
    limit=50,
    offset=0
)

​
Error Handling

The client raises httpx.HTTPStatusError for HTTP errors: 
import httpx

try:
    async with PlatformClient("http://localhost:8000") as client:
        workspace = await client.get_workspace("invalid-id")
except httpx.HTTPStatusError as e:
    if e.response.status_code == 404:
        print("Workspace not found")
    elif e.response.status_code == 401:
        print("Authentication required")
    else:
        print(f"API error: {e.response.status_code}")

​
Best Practices

Always prefer the context manager pattern for multiple API calls to benefit from connection pooling:
# ✅ Good - Connection pooling
async with PlatformClient(base_url) as client:
    for workspace in await client.list_workspaces():
        projects = await client.list_projects(workspace["id"])

# ❌ Avoid - New connection per request  
client = PlatformClient(base_url)
for workspace in await client.list_workspaces():
    projects = await client.list_projects(workspace["id"])
The client automatically manages tokens after register() or login(). For existing tokens:
# Set token explicitly
client = PlatformClient("http://localhost:8000", token="your-jwt-token")

# Or let register/login set it automatically
async with PlatformClient("http://localhost:8000") as client:
    await client.login(email, password)  # Token auto-set
    # All subsequent requests use this token
Use environment variables for configuration in production:
import os

client = PlatformClient(
    base_url=os.getenv("PRAISON_PLATFORM_URL", "http://localhost:8000"),
    token=os.getenv("PRAISON_PLATFORM_TOKEN")
)

Platform API Reference

Complete REST API documentation

Agent Platform Integration

Connect agents to platform resources