Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pixlcore/xyops/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Tags are lightweight, user-defined labels you attach to events, jobs, and tickets in xyOps. They serve three key purposes: visual organization, search filtering, and automation triggers through conditional actions.

Visual Organization

Display tags alongside events and jobs for quick status identification

Search & Filter

Filter jobs and tickets by tags to find related items

Conditional Actions

Trigger actions based on tag presence at job completion

​
Tag Structure

Each tag definition includes:
  • ID - Alphanumeric identifier (auto-generated or provided)
  • Title - Display name shown in the UI
  • Icon - Optional Material Design Icon
  • Notes - Optional description
Example Tag Definition
{
  "id": "tmi9dxf3792",
  "title": "Production",
  "icon": "server",
  "notes": "Production environment jobs",
  "username": "admin",
  "created": 1678901234,
  "modified": 1678901234,
  "revision": 1
}
Tag IDs are the reference key used everywhere. Avoid IDs starting with underscore (_) - these are reserved for system tags.

​
Where Tags Apply

Tags flow through the xyOps system in multiple ways:

​
Events

Define default tags on events that apply to every job launch: 
{
  "id": "backup_db",
  "title": "Database Backup",
  "category": "prod",
  "tags": ["tmi9dxf3792", "tb359d6dde"]
}

​
Jobs

Running jobs accumulate tags from multiple sources:
  1. Event defaults - Inherited from the parent event
  2. Manual overrides - Custom tags when launching manually
  3. Plugin updates - Added dynamically during execution
  4. Workflow nodes - Added by workflow sub-jobs
  5. Resource limits - Added when limits are exceeded

​
Tickets

Tickets support their own tags and can override or extend event tags for attached jobs.

​
Dynamic Tagging from Plugins

Event plugins can add tags to running jobs by sending push updates via STDOUT:
Plugin Tag Update
{
  "xy": 1,
  "push": {
    "tags": ["tmi9dxf3792", "tb359d6dde"]
  }
}
  • Tags are additive only (no remove/replace)
  • Duplicate tags are automatically deduplicated
  • Tag IDs must reference existing tag definitions

​
Tag-Based Conditional Actions

Trigger actions when a job completes with specific tags present:
1

Define the Tag

Create a tag for the condition (e.g., “Production” tag)
2

Configure the Action

Set the action condition to reference the tag ID
{
  "enabled": true,
  "condition": "tag:tmi9dxf3792",
  "type": "email",
  "users": ["oncall"],
  "email": "ops@example.com"
}
3

Job Execution

When the job completes and contains that tag, the action fires

​
Tag Action Behavior

  • Timing - Only fires on job completion
  • Retry - Does not fire if the job is retried
  • Deduplication - Multiple references to the same action run only once
Organize your automation with these common tag patterns:

​
Environments

[
  { "id": "prod", "title": "Production", "icon": "server" },
  { "id": "staging", "title": "Staging", "icon": "test-tube" },
  { "id": "dev", "title": "Development", "icon": "code-braces" },
  { "id": "qa", "title": "QA", "icon": "checkbox-marked-circle" }
]

​
Severity Levels

[
  { "id": "sev1", "title": "Severity 1", "icon": "alert-circle" },
  { "id": "sev2", "title": "Severity 2", "icon": "alert" },
  { "id": "sev3", "title": "Severity 3", "icon": "information" }
]

​
Teams & Ownership

[
  { "id": "team_ops", "title": "Team: Ops", "icon": "account-group" },
  { "id": "team_payments", "title": "Team: Payments", "icon": "cash" },
  { "id": "team_security", "title": "Team: Security", "icon": "shield-lock" }
]

​
Data Sensitivity

[
  { "id": "pii", "title": "PII", "icon": "account-lock" },
  { "id": "finance", "title": "Financial Data", "icon": "currency-usd" }
]

​
Searching and Filtering

Use tags to filter throughout xyOps:
Always use tag IDs in API queries and code. Titles are for display only.

​
API Reference

​
List All Tags

GET /api/app/get_tags/v1
Returns all tag definitions.

​
Get Single Tag

GET /api/app/get_tag/v1?id=tmi9dxf3792

​
Create Tag

POST /api/app/create_tag/v1
Request Body
{
  "title": "Production",
  "icon": "server",
  "notes": "Production environment"
}
ID is auto-generated using pattern t<random>. Optionally provide your own ID.

​
Update Tag

POST /api/app/update_tag/v1
Request Body
{
  "id": "tmi9dxf3792",
  "title": "Production Environment",
  "icon": "shield-check"
}

​
Delete Tag

POST /api/app/delete_tag/v1
Request Body
{
  "id": "tmi9dxf3792"
}

​
Other Tag Sources

Beyond event defaults and plugin pushes, tags can be added by:

​
Resource Limits

Limits can apply tags when exceeded: 
{
  "enabled": true,
  "type": "time",
  "duration": 3600,
  "abort": true,
  "tags": ["timeout"]
}
When a job exceeds 1 hour, the “timeout” tag is added.

​
Workflows

Workflow nodes can define tags for sub-jobs. User-defined tags (non-underscore) bubble up to the parent workflow job for visibility.

​
Tickets

When a ticket is created via a job action, it automatically inherits all tags from the triggering job.

​
Permissions

These privileges control tag management:
  • create_tags - Create new tag definitions
  • edit_tags - Modify existing tags
  • delete_tags - Remove tag definitions

​
Best Practices

Create tag definitions before referencing them in events, actions, or plugins. This prevents runtime errors.
Keep tag titles concise but meaningful. “Prod” is clear, “p” is not.
Choose icons that visually represent the tag’s meaning for quick recognition.
Never create tag IDs starting with underscore (_) to prevent collisions with system tags.
Use naming conventions like “team:ops” or “env:prod” for logical grouping.

Build docs developers (and LLMs) love

Get started for freeTalk to us