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

# Organize with Labels & Dependencies

> Learn how to categorize and prioritize work with labels and dependencies

As your workspace grows, labels and dependencies help you categorize and prioritize work.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Organization Flow"
        Issues[📝 Issues] --> Labels[🏷️ Labels]
        Issues --> Dependencies[🔗 Dependencies]
        Labels --> Organized[📊 Organized Work]
        Dependencies --> Organized
    end
    
    classDef issues fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef tools fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    
    class Issues issues
    class Labels,Dependencies tools
    class Organized result
```

## Quick Start

<Steps>
  <Step title="Create Labels">
    Create color-coded tags to categorize issues across your workspace.

    <Tabs>
      <Tab title="curl">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        # Create "bug" label (red)
        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

        # Create "feature" label (blue)
        curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/labels \
          -H "Authorization: Bearer $TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"name":"feature","color":"#0066FF"}' \
          --max-time 10
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        import asyncio, httpx

        async def create_labels():
            base = "http://localhost:8000/api/v1"
            headers = {"Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json"}
            ws_id = "your-ws-id"

            async with httpx.AsyncClient() as client:
                # Create bug label
                bug_label = await client.post(f"{base}/workspaces/{ws_id}/labels",
                    json={"name": "bug", "color": "#FF0000"}, headers=headers)
                
                # Create feature label
                feature_label = await client.post(f"{base}/workspaces/{ws_id}/labels",
                    json={"name": "feature", "color": "#0066FF"}, headers=headers)

        asyncio.run(create_labels())
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Link Dependencies">
    Connect related issues to show workflow relationships.

    <Tabs>
      <Tab title="curl">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        # Issue A blocks Issue B
        curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_A/dependencies/ \
          -H "Authorization: Bearer $TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"depends_on_issue_id":"ISSUE_B_ID","type":"blocks"}' \
          --max-time 10
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        async def create_dependency():
            base = "http://localhost:8000/api/v1"
            headers = {"Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json"}
            ws_id = "your-ws-id"

            async with httpx.AsyncClient() as client:
                await client.post(f"{base}/workspaces/{ws_id}/issues/{issue_a_id}/dependencies/",
                    json={"depends_on_issue_id": issue_b_id, "type": "blocks"}, headers=headers)
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

***

## How Labels Work

Labels are color-coded tags you attach to issues for easy categorization and filtering.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Label System"
        Workspace[🏢 Workspace] --> Labels[🏷️ Labels]
        Labels --> Issues[📝 Issues]
        Issues --> Filter[🔍 Filter by Label]
        Filter --> Results[📊 Filtered Results]
    end
    
    classDef workspace fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    
    class Workspace workspace
    class Labels,Issues,Filter process
    class Results result
```

### Label Management

| Action     | Description                              |
| ---------- | ---------------------------------------- |
| **Create** | Define workspace-wide labels with colors |
| **Tag**    | Attach labels to issues                  |
| **Filter** | Find issues by label                     |
| **Remove** | Untag labels from issues                 |

### Tag an Issue

<Tabs>
  <Tab title="curl">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID/labels/$LABEL_ID \
      -H "Authorization: Bearer $TOKEN" \
      --max-time 10
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    async def tag_issue():
        await client.post(f"{base}/workspaces/{ws_id}/issues/{issue_id}/labels/{label_id}", 
            headers=headers)
    ```
  </Tab>
</Tabs>

### List Issue Labels

<Tabs>
  <Tab title="curl">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    curl -s http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID/labels \
      -H "Authorization: Bearer $TOKEN" \
      --max-time 10
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    async def get_issue_labels():
        response = await client.get(f"{base}/workspaces/{ws_id}/issues/{issue_id}/labels", 
            headers=headers)
        return response.json()
    ```
  </Tab>
</Tabs>

***

## How Dependencies Work

Dependencies link issues to show relationships and execution order.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Dependency Types"
        A[📝 Issue A] --|blocks|--> B[📝 Issue B]
        C[📝 Issue C] --|related|--> D[📝 Issue D]
        E[📝 Issue E] --|duplicates|--> F[📝 Issue F]
    end
    
    classDef issue fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef blocks fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef related fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef duplicate fill:#6366F1,stroke:#7C90A0,color:#fff
    
    class A,B,C,D,E,F issue
```

### Dependency Types

| Type         | Description                            | Use Case        |
| ------------ | -------------------------------------- | --------------- |
| `blocks`     | Must finish before dependent can start | Sequential work |
| `related`    | Connected but not blocking             | Context sharing |
| `duplicates` | Same work, different issues            | Issue cleanup   |

### View Dependencies

<Tabs>
  <Tab title="curl">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    curl -s http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_A/dependencies/ \
      -H "Authorization: Bearer $TOKEN" \
      --max-time 10
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    async def get_dependencies():
        response = await client.get(f"{base}/workspaces/{ws_id}/issues/{issue_id}/dependencies/", 
            headers=headers)
        return response.json()
    ```
  </Tab>
</Tabs>

***

## Putting It Together

Organize a complete workflow using labels and dependencies.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Workflow Organization"
        DB[🗄️ Setup Database] --> API[🔧 Build API] 
        API --> Tests[🧪 Write Tests]
        
        DB -.-> Backend[backend]
        API -.-> Backend
        Tests -.-> Backend
    end
    
    classDef task fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef label fill:#189AB4,stroke:#7C90A0,color:#fff
    
    class DB,API,Tests task
    class Backend label
```

### Example: Backend Feature Pipeline

<Tabs>
  <Tab title="curl">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Create backend label
    curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/labels \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"name":"backend","color":"#6366F1"}' \
      --max-time 10

    # Create three issues
    curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/ \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"title":"Setup Database"}' \
      --max-time 10

    curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/ \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"title":"Build API"}' \
      --max-time 10

    curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/ \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"title":"Write Tests"}' \
      --max-time 10

    # Tag all with backend label
    curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$DB_ISSUE_ID/labels/$BACKEND_LABEL_ID \
      -H "Authorization: Bearer $TOKEN" \
      --max-time 10

    # Create dependency chain: DB blocks API blocks Tests
    curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$DB_ISSUE_ID/dependencies/ \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"depends_on_issue_id":"API_ISSUE_ID","type":"blocks"}' \
      --max-time 10

    curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$API_ISSUE_ID/dependencies/ \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"depends_on_issue_id":"TESTS_ISSUE_ID","type":"blocks"}' \
      --max-time 10
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import asyncio, httpx

    async def organize_workflow():
        base = "http://localhost:8000/api/v1"
        headers = {"Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json"}
        ws_id = "your-ws-id"

        async with httpx.AsyncClient() as client:
            # Create backend label
            label_response = await client.post(f"{base}/workspaces/{ws_id}/labels",
                json={"name": "backend", "color": "#6366F1"}, headers=headers)
            label = label_response.json()

            # Create three issues
            db_response = await client.post(f"{base}/workspaces/{ws_id}/issues/",
                json={"title": "Setup Database"}, headers=headers)
            db_issue = db_response.json()

            api_response = await client.post(f"{base}/workspaces/{ws_id}/issues/",
                json={"title": "Build API"}, headers=headers)
            api_issue = api_response.json()

            tests_response = await client.post(f"{base}/workspaces/{ws_id}/issues/",
                json={"title": "Write Tests"}, headers=headers)
            tests_issue = tests_response.json()

            # Tag all with backend label
            for issue in [db_issue, api_issue, tests_issue]:
                await client.post(f"{base}/workspaces/{ws_id}/issues/{issue['id']}/labels/{label['id']}", 
                    headers=headers)

            # Create dependency chain
            await client.post(f"{base}/workspaces/{ws_id}/issues/{db_issue['id']}/dependencies/",
                json={"depends_on_issue_id": api_issue["id"], "type": "blocks"}, headers=headers)

            await client.post(f"{base}/workspaces/{ws_id}/issues/{api_issue['id']}/dependencies/",
                json={"depends_on_issue_id": tests_issue["id"], "type": "blocks"}, headers=headers)

    asyncio.run(organize_workflow())
    ```
  </Tab>
</Tabs>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use Consistent Label Names">
    Create standard labels like "bug", "feature", "urgent" that team members recognize. Avoid duplicate labels with similar meanings.
  </Accordion>

  <Accordion title="Color Code by Priority">
    Use red for urgent issues, blue for features, green for improvements. Consistent colors help visual scanning.
  </Accordion>

  <Accordion title="Plan Dependencies Early">
    Map blocking relationships before starting work. This prevents bottlenecks and clarifies execution order.
  </Accordion>

  <Accordion title="Review Dependencies Regularly">
    Check if blocking issues are resolved and update dependency status. Remove outdated links to keep the graph clean.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Platform Issues" icon="list" href="/docs/features/platform/issues">
    Create and manage issues in your workspace
  </Card>

  <Card title="Issue IDs" icon="hashtag" href="/docs/features/platform/issue-ids">
    Understanding issue identification and references
  </Card>
</CardGroup>