> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberdesk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Workflow Tags & Groups
> Organize your workflows with tags and tag groups for better filtering, categorization, and team collaboration
As your workflow library grows, finding and organizing them becomes essential. Workflow tags let you categorize, filter, and manage your workflows efficiently. Tag groups add another layer of organization with mutually exclusive labels.
## What Are Workflow Tags?
Tags are labels you attach to workflows for organization and quick filtering. Each tag can have:
* **Name** - A short, descriptive label (e.g., "Production", "Testing", "High Priority")
* **Color** - Visual differentiation (red, orange, yellow, green, blue, purple, pink, gray)
* **Emoji** - Optional icon for quick recognition
* **Description** - Optional notes about when to use this tag
## Using Tags in the Dashboard
### Viewing Tags
Tags appear prominently above your workflow table. Each tag shows:
* Its emoji (if set)
* Its name
* A count of how many workflows use it
### Filtering by Tags
Click any tag to filter the workflow table to only show workflows with that tag. You can select multiple tags to filter by all of them (AND logic) - only workflows that have **all** selected tags will appear.
Use the clear-filters action to remove all selected tags and return to the full workflow list.
### Adding Tags to Workflows
There are two ways to add tags to workflows:
**Individual workflow:**
1. Open the workflow detail page
2. Use the tags section to add or remove tags
**Bulk tagging:**
1. Select multiple workflows using the checkboxes
2. Click the "Add Tags" button that appears
3. Choose which tags to apply to all selected workflows
## Tag Groups
Tag groups let you organize related tags and enforce mutual exclusivity.
### What Are Tag Groups?
A tag group is a named collection of related tags where **only one tag from the group can be applied to a workflow at a time**. This is perfect for status-type categorizations.
**Example: Status Group**
* 🟢 Production
* 🟡 Staging
* 🔴 Development
When you add "Production" to a workflow, any existing status tag (like "Staging") is automatically removed.
### When to Use Groups
Track workflow lifecycle: Draft → Testing → Production → Deprecated
Mark importance: Low → Medium → High → Critical
Categorize by environment: Dev → Staging → Prod
Assign to teams: Engineering → QA → Operations
### When NOT to Use Groups
Don't use groups for tags that can coexist on the same workflow. For example:
* Feature areas (a workflow might touch "Billing" AND "Notifications")
* Clients (unless a workflow is truly client-specific)
* Capabilities (a workflow might do "OCR" AND "Form Filling")
These should be ungrouped tags so you can apply multiple.
## Creating Tags & Groups
### From the Dashboard
Click **"Tag Actions"** above the workflow table to:
* **New Tag** - Create a new tag (optionally in a group)
* **New Group** - Create a new tag group
* **Manage Tags** - Edit, delete, or reorganize existing tags
### Via the API
```typescript theme={null}
// Create a tag group
const { data: statusGroup } = await client.workflow_tag_groups.create({
name: "Status",
emoji: "🚦"
});
// Create tags in the group
await client.workflow_tags.create({
name: "Production",
color: "green",
emoji: "🟢",
group_id: statusGroup.id
});
await client.workflow_tags.create({
name: "Development",
color: "red",
emoji: "🔴",
group_id: statusGroup.id
});
// Create an ungrouped tag
await client.workflow_tags.create({
name: "Needs Review",
color: "yellow",
emoji: "👀"
});
```
```python theme={null}
# Create a tag group
status_group = client.workflow_tag_groups.create(
name="Status",
emoji="🚦"
)
# Create tags in the group
client.workflow_tags.create(
name="Production",
color="green",
emoji="🟢",
group_id=status_group.id
)
client.workflow_tags.create(
name="Development",
color="red",
emoji="🔴",
group_id=status_group.id
)
# Create an ungrouped tag
client.workflow_tags.create(
name="Needs Review",
color="yellow",
emoji="👀"
)
```
## Filtering Workflows by Tags (API)
When listing workflows, pass `tag_ids` to filter:
```typescript theme={null}
// Filter by single tag
const { data: workflows } = await client.workflows.list({
tag_ids: "tag-uuid-1"
});
// Filter by multiple tags (AND logic - must have ALL tags)
const { data: workflows } = await client.workflows.list({
tag_ids: "tag-uuid-1,tag-uuid-2"
});
// Include tag data in response
const { data: workflows } = await client.workflows.list({
include_tags: true
});
```
```python theme={null}
# Filter by single tag
workflows = client.workflows.list(tag_ids="tag-uuid-1")
# Filter by multiple tags (AND logic - must have ALL tags)
workflows = client.workflows.list(tag_ids="tag-uuid-1,tag-uuid-2")
# Include tag data in response
workflows = client.workflows.list(include_tags=True)
```
## Drag-and-Drop Organization
The tag bar supports drag-and-drop for intuitive organization:
### Reordering Tags
Drag any tag left or right to change its position within its group (or among ungrouped tags). The order is saved automatically.
### Moving Tags Between Groups
Drag a tag onto a different group's label to move it into that group. The tag will now be mutually exclusive with other tags in its new group.
### Ungrouping Tags
Drag a grouped tag to the ungrouped area (outside any group) to remove it from its group. It will become a standalone tag that can coexist with any other tag.
### Reordering Groups
Drag a group label left or right to change the display order of groups in the tag bar.
## Best Practices
Begin with a few essential tags. You can always add more as patterns emerge from your workflow usage.
Adopt a color convention (e.g., green = good/active, red = danger/deprecated) and stick to it across all tags.
Any time a workflow can only be in one state at a time, use a tag group to enforce this.
Emojis make tags instantly recognizable when scanning a long list. Pick distinctive ones.
## Example: Production Workflow Management
Here's a complete tagging setup for managing production workflows:
**Tag Groups:**
* **Status** (🚦): Draft, Testing, Production, Deprecated
* **Priority** (⚡): Low, Medium, High, Critical
**Ungrouped Tags:**
* 📋 Needs Review
* 🔧 Maintenance
* 📊 Generates Reports
* 💳 Handles Payments
* 🔐 Requires Auth
This setup lets you:
1. Filter to "Production + Critical" to see urgent production workflows
2. Ensure a workflow is only ever in one status
3. Tag workflows with multiple capabilities (e.g., both "Generates Reports" and "Handles Payments")
4. Quickly spot workflows needing attention via the "Needs Review" tag
## API Reference
For complete API documentation on tags and tag groups, see:
* [Workflow Tags API](/api-reference/workflow-tags/list-tags)
* [Workflow Tag Groups API](/api-reference/workflow-tag-groups/list-tag-groups)