Skip to main content
Platform Labels provide color-coded tags scoped to a workspace for categorizing issues with labels like “bug”, “feature”, or “urgent”.

​
Quick Start

1

Create Agent with Platform Client

from praisonaiagents import Agent
import httpx

agent = Agent(
    name="Label Manager",
    instructions="Create and manage workspace labels",
    platform_url="http://localhost:8000/api/v1"
)

# Platform client setup
base_url = "http://localhost:8000/api/v1"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
2

Create and Use Labels

import asyncio

async def manage_labels():
    async with httpx.AsyncClient() as client:
        # Create a label
        response = await client.post(
            f"{base_url}/workspaces/ws-123/labels",
            json={"name": "bug", "color": "#FF0000"},
            headers=headers
        )
        label = response.json()
        
        # Attach to issue
        await client.post(
            f"{base_url}/workspaces/ws-123/issues/issue-456/labels/{label['id']}",
            headers=headers
        )

asyncio.run(manage_labels())

​
How It Works

ComponentPurposeScope
LabelsColor-coded categorization tagsWorkspace-scoped, reusable
Issue LinksMany-to-many relationshipsOne issue can have multiple labels
Color CodingVisual organizationHex color codes (default #6B7280)

​
API Endpoints

MethodEndpointDescription
POST/workspaces/{ws_id}/labelsCreate workspace label
GET/workspaces/{ws_id}/labelsList workspace labels
PATCH/workspaces/{ws_id}/labels/{label_id}Update label
DELETE/workspaces/{ws_id}/labels/{label_id}Delete label
POST/workspaces/{ws_id}/issues/{issue_id}/labels/{label_id}Add label to issue
DELETE/workspaces/{ws_id}/issues/{issue_id}/labels/{label_id}Remove label from issue
GET/workspaces/{ws_id}/issues/{issue_id}/labelsList labels on issue

​
Request/Response Schemas

​
Create Label

{
  "name": "bug",
  "color": "#FF0000"
}

​
Update Label

{
  "name": "critical-bug", 
  "color": "#CC0000"
}

​
Label Response

{
  "id": "label-abc123",
  "workspace_id": "ws-abc123", 
  "name": "bug",
  "color": "#FF0000"
}

​
Code Examples

​
curl Examples

TOKEN="your-jwt-token"
WS_ID="workspace-id"

curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/labels \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"bug","color":"#FF0000"}' \
  --max-time 10

​
Python SDK Examples

import asyncio
import httpx

async def label_management():
    base = "http://localhost:8000/api/v1"
    headers = {"Authorization": "Bearer YOUR_TOKEN"}
    ws_id = "your-workspace-id"

    async with httpx.AsyncClient() as client:
        # Create multiple labels
        labels = [
            {"name": "bug", "color": "#FF0000"},
            {"name": "feature", "color": "#00FF00"},
            {"name": "urgent", "color": "#FFA500"}
        ]
        
        created_labels = []
        for label_data in labels:
            resp = await client.post(
                f"{base}/workspaces/{ws_id}/labels",
                json=label_data, 
                headers=headers
            )
            created_labels.append(resp.json())
            
        return created_labels

asyncio.run(label_management())

​
Agent Integration

​
Agent-Powered Label Management

from praisonaiagents import Agent

def create_label_manager_agent():
    return Agent(
        name="Label Manager",
        instructions="""
        You manage workspace labels and categorize issues automatically.
        
        When given an issue:
        1. Analyze the content and determine appropriate labels
        2. Check if required labels exist in the workspace
        3. Create missing labels with appropriate colors
        4. Attach relevant labels to the issue
        
        Use these color conventions:
        - Bug: #FF0000 (red)
        - Feature: #00FF00 (green) 
        - Enhancement: #0000FF (blue)
        - Urgent: #FFA500 (orange)
        - Documentation: #800080 (purple)
        """,
        tools=["web_search", "api_request"]
    )

# Usage
agent = create_label_manager_agent()
result = agent.start("Categorize this bug report and apply appropriate labels")

​
Best Practices

Establish consistent color schemes across your workspace for better visual organization. Use semantic colors that teams can easily recognize.
{
  "bug": "#FF0000",      // Red for bugs
  "feature": "#00FF00",   // Green for features  
  "urgent": "#FFA500",    // Orange for urgency
  "blocked": "#800080"    // Purple for blocked items
}
Use clear, consistent naming conventions. Keep label names short but descriptive. Consider using prefixes for categories like “priority:”, “type:”, “status:”.
# Good label names
labels = ["bug", "feature-request", "urgent", "needs-review"]

# Avoid unclear names
avoid = ["thing", "fix-this", "important", "asap"]
Limit the number of labels per workspace to avoid clutter. Group related labels and consider using a hierarchical naming system for complex projects.
Remember that issues can have multiple labels and labels can be attached to multiple issues. Design your labeling strategy with this flexibility in mind.
# An issue can have multiple labels
issue_labels = ["bug", "urgent", "backend", "needs-review"]

# A label can be on multiple issues  
bug_issues = ["issue-1", "issue-2", "issue-3"]

​
Testing

Run these tests to verify label functionality: 
# Test label service
pytest tests/test_new_gaps.py::TestLabelService -v

# Test label API routes  
pytest tests/test_new_api_integration.py::TestLabelRoutes -v

Platform Issues

Manage issues that labels can be attached to

Platform Workspaces

Workspace-scoped label management