Platform Project Management

Organize issues within workspaces using projects with leads, status tracking, and statistics

Projects organize issues within a workspace, providing structure for team collaboration and progress tracking.

Projects organize issues within a workspace, providing structure for team collaboration and progress tracking.

from praisonaiagents import Agent

agent = Agent(name="pm-bot", instructions="Manage platform projects inside a workspace.")
agent.start("Open a project for the mobile app release.")

The user groups issues into a project; the platform stores milestones, leads, and linked work items.

Quick Start

1. Create Project

   from praisonai_platform.client import PlatformClient
   
   client = PlatformClient("http://localhost:8000", token="your-jwt-token")
   ws_id = "your-workspace-id"
   
   # Create project
   project = await client.create_project(
       ws_id, 
       "Backend API", 
       description="All backend development work"
   )
   print(project["id"])
   
2. List Projects

   # List all projects in workspace
   projects = await client.list_projects(ws_id)
   for project in projects:
       print(f"{project['title']} - {project['status']}")
   

---

How It Works

Feature	Description
Title	Project display name
Lead	User or agent responsible for project
Status	Project lifecycle stage
Statistics	Issue counts by status

Workspace Scoping

All GET / PATCH / DELETE endpoints for projects are scoped to the workspace in the URL. If a project ID exists but belongs to a different workspace, the API returns 404 Not Found — your auth token never reveals whether the ID exists in another workspace.

---

API Endpoints

All endpoints scope resources to the workspace in the URL path. Requesting a project_id that belongs to a different workspace returns 404 Not Found (never 200 or 403) to avoid leaking the existence of resources across tenants.

Project Operations

Method	Endpoint	Description
POST	/api/v1/workspaces/{ws_id}/projects/	Create new project
GET	/api/v1/workspaces/{ws_id}/projects/	List projects (paginated)
GET	/api/v1/workspaces/{ws_id}/projects/{project_id}	Get specific project
PATCH	/api/v1/workspaces/{ws_id}/projects/{project_id}	Update project
DELETE	/api/v1/workspaces/{ws_id}/projects/{project_id}	Delete project
GET	/api/v1/workspaces/{ws_id}/projects/{project_id}/stats	Get issue statistics

---

Configuration Options

Create Project Schema

{
  "title": "Backend API",
  "description": "All backend development work",
  "icon": "🔧",
  "lead_type": "user",
  "lead_id": "user-abc123"
}

Option	Type	Required	Description
title	string	Yes	Project display name
description	string	No	Project description
icon	string	No	Project icon/emoji
lead_type	string	No	Lead type: “user” or “agent”
lead_id	string	No	ID of lead user or agent

Response Schema

{
  "id": "proj-abc123",
  "workspace_id": "ws-abc123", 
  "title": "Backend API",
  "description": "All backend development work",
  "icon": "🔧",
  "status": "active",
  "lead_type": "user",
  "lead_id": "user-abc123",
  "created_at": "2025-01-01T00:00:00"
}

Statistics Response

{
  "total": 21,
  "by_status": {
    "backlog": 5,
    "todo": 3, 
    "in_progress": 2,
    "done": 10,
    "cancelled": 1
  }
}

---

Common Patterns

Full CRUD Operations

TOKEN="your-jwt-token"
WS_ID="workspace-id"
BASE_URL="http://localhost:8000"

# Create project
curl -s -X POST $BASE_URL/api/v1/workspaces/$WS_ID/projects/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Backend API","description":"All backend work"}' \
  --max-time 10

# List projects with pagination  
curl -s "$BASE_URL/api/v1/workspaces/$WS_ID/projects/?limit=10&offset=0" \
  -H "Authorization: Bearer $TOKEN" \
  --max-time 10

# Update project status
curl -s -X PATCH $BASE_URL/api/v1/workspaces/$WS_ID/projects/PROJECT_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"completed"}' \
  --max-time 10

# Delete project  
curl -s -X DELETE $BASE_URL/api/v1/workspaces/$WS_ID/projects/PROJECT_ID \
  -H "Authorization: Bearer $TOKEN" \
  --max-time 10

Project Statistics

# Get detailed project statistics
curl -s $BASE_URL/api/v1/workspaces/$WS_ID/projects/PROJECT_ID/stats \
  -H "Authorization: Bearer $TOKEN" \
  --max-time 10

Python SDK Usage

import asyncio
from praisonai_platform.client import PlatformClient

async def manage_projects():
    client = PlatformClient("http://localhost:8000", token="your-jwt-token")
    ws_id = "your-workspace-id"

    # Create project with lead
    project = await client.create_project(
        ws_id, 
        "Mobile App",
        description="iOS and Android development"
    )
    
    # List all projects
    projects = await client.list_projects(ws_id)
    for p in projects:
        print(f"Project: {p['title']} (Status: {p['status']})")

asyncio.run(manage_projects())

---

Best Practices

Project Organization

Keep projects focused on specific domains or features rather than creating overly broad projects. Use descriptive titles and include project descriptions for team clarity.

Lead Assignment

Assign project leads to provide clear ownership. Use “user” for human leads and “agent” for AI-managed projects. Update leads as project ownership changes.

Status Management

Regularly update project status to reflect current state. Use consistent status values across your organization. Archive completed projects rather than deleting them for historical tracking.

Statistics Monitoring

Use project statistics to track progress and identify bottlenecks. Monitor issue distribution across statuses to ensure balanced workload and identify stuck issues.

---

Testing

Run the project service tests to verify functionality:

pytest tests/test_services.py::TestProjectService -v

Expected test coverage includes:

• Project creation and validation
• Listing and pagination
• Updates and status changes
• Deletion and cleanup
• Statistics calculation

---

Related

Issues Management

Create and manage issues within projects

Workspaces

Organize projects within workspaces