> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Labels

> Create workspace-level labels and attach them to issues for categorisation

> [!NOTE]
>
> Platform is now a separate repository - install with `pip install praisonai-platform` as before, and see the [PraisonAI-Platform repo](https://github.com/MervinPraison/PraisonAI-Platform) for source and issues. Details: [Where Platform Lives](https://praison.ai/docs/features/platform/where-platform-lives.md).

Colour-coded labels organise platform issues by type, priority, or team — attach them from an agent or the SDK.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import os
from praisonaiagents import Agent
from praisonai_platform.client import PlatformClient

agent = Agent(
    name="label-manager",
    instructions="Categorise issues with workspace labels (bug, feature, urgent).",
)

async with PlatformClient(
    os.getenv("PLATFORM_URL", "http://localhost:8000"),
    token=os.getenv("PLATFORM_TOKEN"),
) as client:
    label = await client.create_label("ws-123", name="bug", color="#dc2626")
    await client.add_label_to_issue("ws-123", "issue-456", label["id"])
```

The user asks to triage issues; the agent creates labels and attaches them on the platform.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Agent[🤖 Agent] --> SDK[📦 PlatformClient]
    SDK --> Create[🏷️ Create Label]
    Create --> Attach[🔗 Attach to Issue]
    Attach --> Organise[📊 Organised Issues]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef sdk fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Agent agent
    class SDK,Create,Attach sdk
    class Organise result
```

## Quick Start

**1. Simple Usage**

Create a label and attach it to an issue:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import os
import asyncio
from praisonai_platform.client import PlatformClient

async def tag_issue():
    async with PlatformClient(
        os.getenv("PLATFORM_URL", "http://localhost:8000"),
        token=os.getenv("PLATFORM_TOKEN"),
    ) as client:
        label = await client.create_label(
            "ws-123",
            name="bug",
            color="#dc2626",
        )
        await client.add_label_to_issue("ws-123", "issue-456", label["id"])

asyncio.run(tag_issue())
```

**2. With Configuration**

List labels, update colours, and remove labels from issues:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import os
import asyncio
from praisonai_platform.client import PlatformClient

async def manage_labels():
    async with PlatformClient(
        os.getenv("PLATFORM_URL", "http://localhost:8000"),
        token=os.getenv("PLATFORM_TOKEN"),
    ) as client:
        labels = await client.list_labels("ws-123")
        await client.update_label("ws-123", labels[0]["id"], color="#991b1b")
        await client.remove_label_from_issue("ws-123", "issue-456", labels[0]["id"])

asyncio.run(manage_labels())
```

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Agent
    participant SDK as PlatformClient
    participant API
    participant DB

    Agent->>SDK: create_label()
    SDK->>API: POST /workspaces/{id}/labels
    API->>DB: store label
    Agent->>SDK: add_label_to_issue()
    SDK->>API: POST /issues/{id}/labels/{label_id}
    API-->>Agent: success
```

| Component | Purpose |
| - | - |
| **Labels** | Reusable, workspace-scoped tags with hex colours |
| **Issue links** | Many-to-many — one issue can carry several labels |
| **PlatformClient** | Async CRUD for labels and issue attachments |

***

## Configuration Options

| Field | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | Label name (unique per workspace) |
| `color` | `str` | `#6B7280` | Hex colour for UI display |
| `description` | `str` | `None` | Optional label description |

***

## Best Practices

> [accordion] Use semantic colours
>
> Keep colours consistent — red for bugs, green for features, orange for urgent items.

> [accordion] Limit label sprawl
>
> Aim for 10–20 labels per workspace; use prefixes like `type:` or `priority:` when needed.

> [accordion] Read tokens from the environment
>
> Use `os.getenv("PLATFORM_TOKEN")` — never hardcode JWT values in source.

> [accordion] Batch with a context manager
>
> Reuse one `PlatformClient` session when tagging many issues in a loop.

***

## Related

> [card] [Platform Issues](https://praison.ai/docs/features/platform/issues.md)
>
> Create and manage issues that labels attach to

> [card] [Platform SDK Client](https://praison.ai/docs/features/platform-sdk.md)
>
> Full PlatformClient API reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.