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

​
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

FeatureDescription
TitleProject display name
LeadUser or agent responsible for project
StatusProject lifecycle stage
StatisticsIssue counts by status

​
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

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

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

Keep projects focused on specific domains or features rather than creating overly broad projects. Use descriptive titles and include project descriptions for team clarity.
Assign project leads to provide clear ownership. Use “user” for human leads and “agent” for AI-managed projects. Update leads as project ownership changes.
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.
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

Issues Management

Create and manage issues within projects

Workspaces

Organize projects within workspaces