Praison AI

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.

python
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.

Diagram

Project Management Flow

📋 Create Project

🧠 Manage Issues

📊 Track Stats

✅ Complete Project

Quick Start

  1. Create Project
    python
    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
    python
    # 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

Diagram
IssuesProjectPlatformUserIssuesProjectPlatformUserCreate ProjectStore project dataReturn project IDAdd IssuesLink to projectUpdate countsGet statsCount by statusStatistics
FeatureDescription
TitleProject display name
LeadUser or agent responsible for project
StatusProject lifecycle stage
StatisticsIssue 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

Project Operations

MethodEndpointDescription
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}/statsGet issue statistics

Configuration Options

Create Project Schema

json
{
  "title": "Backend API",
  "description": "All backend development work",
  "icon": "🔧",
  "lead_type": "user",
  "lead_id": "user-abc123"
}
OptionTypeRequiredDescription
titlestringYesProject display name
descriptionstringNoProject description
iconstringNoProject icon/emoji
lead_typestringNoLead type: “user” or “agent”
lead_idstringNoID of lead user or agent

Response Schema

json
{
  "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

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

Common Patterns

Full CRUD Operations

bash
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

bash
# 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

python
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:

bash
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