Skip to main content
Labels provide a flexible tagging system for organizing issues by categories, priorities, teams, or any custom classification system. Labels provide a flexible tagging system for organizing issues by categories, priorities, teams, or any custom classification system. 
from praisonaiagents import Agent

agent = Agent(name="triage-bot", instructions="Label and categorise issues.")
agent.start("Tag urgent customer bugs with label customer-escalation.")
The user applies colour-coded labels so boards and filters stay organised across many issues.

​
Quick Start

1

Create Labels

import asyncio
from praisonai_platform.client import PlatformClient

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

    # Create category labels
    bug_label = await client.create_label(
        ws_id,
        name="bug",
        color="#dc2626",  # red
        description="Something isn't working"
    )
    
    feature_label = await client.create_label(
        ws_id,
        name="enhancement", 
        color="#059669",  # green
        description="New feature or request"
    )
    
    print(f"Created labels: {bug_label['name']}, {feature_label['name']}")

asyncio.run(create_labels())
2

Apply Labels to Issues

async def apply_labels():
    client = PlatformClient("http://localhost:8000", token="your-jwt-token")
    ws_id = "your-workspace-id"
    
    # Add multiple labels to an issue
    await client.add_issue_labels(
        ws_id,
        issue_id="issue-123",
        labels=["bug", "priority-high", "backend"]
    )
    
    # Remove labels from issue
    await client.remove_issue_labels(
        ws_id,
        issue_id="issue-123", 
        labels=["priority-high"]
    )
    
    print("Labels updated successfully")

asyncio.run(apply_labels())

​
How It Works

ComponentPurposeFeatures
LabelCategorization tagName, color, description
AssociationIssue-label relationshipMany-to-many mapping
Color CodingVisual organizationHex color values
FilteringIssue discoveryQuery by label combinations

​
API Reference

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

​
Label Management Endpoints

MethodEndpointPurposeAuthentication
POST/api/v1/workspaces/{ws_id}/labelsCreate labelBearer Token
GET/api/v1/workspaces/{ws_id}/labelsList labelsBearer Token
PUT/api/v1/workspaces/{ws_id}/labels/{label_id}Update labelBearer Token
DELETE/api/v1/workspaces/{ws_id}/labels/{label_id}Delete labelBearer Token

​
Issue Label Operations

MethodEndpointPurposeAuthentication
POST/api/v1/workspaces/{ws_id}/issues/{issue_id}/labelsAdd labels to issueBearer Token
DELETE/api/v1/workspaces/{ws_id}/issues/{issue_id}/labels/{label_name}Remove label from issueBearer Token
GET/api/v1/workspaces/{ws_id}/issues?labels=tag1,tag2Filter issues by labelsBearer Token

​
Common Patterns

Create hierarchical labels using naming conventions:
async def create_label_hierarchy():
    client = PlatformClient("http://localhost:8000", token="your-jwt-token")
    ws_id = "your-workspace-id"
    
    # Priority hierarchy
    await client.create_label(ws_id, "priority:critical", "#dc2626", "Critical priority")
    await client.create_label(ws_id, "priority:high", "#f97316", "High priority")
    await client.create_label(ws_id, "priority:medium", "#eab308", "Medium priority")
    await client.create_label(ws_id, "priority:low", "#22c55e", "Low priority")
    
    # Team hierarchy
    await client.create_label(ws_id, "team:backend", "#3b82f6", "Backend team")
    await client.create_label(ws_id, "team:frontend", "#8b5cf6", "Frontend team")
    await client.create_label(ws_id, "team:devops", "#06b6d4", "DevOps team")
    
    # Status hierarchy
    await client.create_label(ws_id, "status:blocked", "#ef4444", "Blocked issue")
    await client.create_label(ws_id, "status:ready", "#10b981", "Ready for work")
Efficiently manage labels in bulk operations:
async def bulk_label_operations():
    client = PlatformClient("http://localhost:8000", token="your-jwt-token")
    ws_id = "your-workspace-id"
    
    # Bulk create labels
    label_definitions = [
        {"name": "documentation", "color": "#6366f1", "description": "Documentation updates"},
        {"name": "testing", "color": "#8b5cf6", "description": "Testing related work"},
        {"name": "performance", "color": "#f59e0b", "description": "Performance improvements"},
        {"name": "security", "color": "#ef4444", "description": "Security issues"}
    ]
    
    created_labels = []
    for label_def in label_definitions:
        label = await client.create_label(ws_id, **label_def)
        created_labels.append(label)
    
    print(f"Created {len(created_labels)} labels")
    
    # Bulk apply labels to multiple issues
    issue_ids = ["issue-1", "issue-2", "issue-3"]
    common_labels = ["documentation", "testing"]
    
    for issue_id in issue_ids:
        await client.add_issue_labels(ws_id, issue_id, common_labels)
Build dynamic filtering interfaces using labels:
async def dynamic_label_filtering():
    client = PlatformClient("http://localhost:8000", token="your-jwt-token")
    ws_id = "your-workspace-id"
    
    # Get all available labels
    all_labels = await client.list_labels(ws_id)
    
    # Filter by multiple labels (AND operation)
    backend_bugs = await client.list_issues(
        ws_id,
        labels=["team:backend", "bug"]
    )
    
    # Filter by label groups (OR within group, AND between groups)
    critical_or_high = await client.list_issues(
        ws_id,
        labels=["priority:critical,priority:high", "team:backend"]
    )
    
    # Exclude certain labels (NOT operation)
    non_blocked_issues = await client.list_issues(
        ws_id,
        exclude_labels=["status:blocked"]
    )
    
    print(f"Backend bugs: {len(backend_bugs)}")
    print(f"High priority backend: {len(critical_or_high)}")
    print(f"Non-blocked issues: {len(non_blocked_issues)}")

​
Best Practices

  • Consistent naming: Use lowercase, hyphen-separated names (e.g., “priority-high”, “team-backend”)
  • Descriptive names: Choose clear, searchable names that indicate purpose
  • Namespace prefixes: Use prefixes for categories (e.g., “type:”, “team:”, “priority:”)
  • Avoid redundancy: Don’t create similar labels with different names
  • Semantic colors: Use colors that match label meaning (red for critical, green for good)
  • Accessibility: Ensure sufficient contrast for all users
  • Consistency: Use the same color for related labels across projects
  • Limited palette: Stick to 8-12 core colors to avoid visual confusion
  • Regular cleanup: Remove unused labels to keep the system organized
  • Deprecation process: Mark old labels as deprecated before removing
  • Migration strategy: Plan label renames and merges carefully
  • Documentation: Maintain guidelines for label usage in your team
  • Index frequently used labels: Ensure database indexes on common label queries
  • Limit labels per issue: Keep to 3-5 labels per issue for usability
  • Batch operations: Use bulk API calls when modifying multiple labels
  • Cache label lists: Cache workspace labels to reduce API calls

Issue Tracking

Comprehensive issue management system

Project Management

Organize work with projects and workflows