Tags

Organize and categorize resources with key-value tags.

What Are Tags?

Tags are key-value pairs that help you organize, filter, and manage resources:

Tag Structure

Component	Description	Example
Key	Category or attribute name	environment, team, region
Value	Specific value for the key	production, platform, us-east-1

Taggable Resources

Resource	Common Tag Use Cases
Targets	Environment, region, team, application
Tenants	Tier, industry, support level

Managing Tags

Tag List View

┌─────────────────────────────────────────────────────────────┐
│  Tags                                                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Search: [____________________________] [+ New Tag]         │
│                                                             │
│  ┌───────────────┬──────────────────┬───────┬───────────┐  │
│  │ Key           │ Value            │ Used  │ Actions   │  │
│  ├───────────────┼──────────────────┼───────┼───────────┤  │
│  │ environment   │ production       │ 24    │ [···]     │  │
│  │ environment   │ staging          │ 8     │ [···]     │  │
│  │ environment   │ development      │ 4     │ [···]     │  │
│  │ team          │ platform         │ 12    │ [···]     │  │
│  │ team          │ frontend         │ 8     │ [···]     │  │
│  │ region        │ us-east-1        │ 16    │ [···]     │  │
│  │ region        │ eu-west-1        │ 8     │ [···]     │  │
│  └───────────────┴──────────────────┴───────┴───────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Creating Tags

Via Lens UI

┌─────────────────────────────────────────────────────────────┐
│  Create Tag                                                 │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Key *                                                      │
│  [environment                          ]                    │
│                                                             │
│  Value *                                                    │
│  [production                           ]                    │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ Tags with the same key and value are shared across    │  │
│  │ resources.                                            │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│                                     [Cancel]  [Create]      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Via REST API

Tags are managed through the REST API. There is no mantisctl subcommand for tag management. Create a tag with a POST to /api/v1/tags:

# Create a tag
curl -X POST https://mantis.example.com/api/v1/tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "environment", "value": "production"}'

# Create additional tags with separate requests
curl -X POST https://mantis.example.com/api/v1/tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "team", "value": "platform"}'

The tags:create permission is required.

Applying Tags

To Targets

┌─────────────────────────────────────────────────────────────┐
│  Target: web-prod-01                                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Tags:                                                      │
│  ┌──────────────────────────────────────┐                  │
│  │ environment: production    [×]       │                  │
│  │ team: platform             [×]       │                  │
│  │ region: us-east-1          [×]       │                  │
│  └──────────────────────────────────────┘                  │
│                                                             │
│  [+ Add Tag]                                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Via REST API

Targets are tagged by attaching existing tag IDs. Tag and target management is done in Lens or via the REST API (there is no mantisctl tag subcommand).

# Attach tags to a target (tags are referenced by ID)
curl -X POST "$MANTIS_URL/api/v1/targets/<target-id>/tags" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag_ids": ["<tag-id-1>", "<tag-id-2>"]}'

# Detach tags from a target
curl -X DELETE "$MANTIS_URL/api/v1/targets/<target-id>/tags" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag_ids": ["<tag-id-1>"]}'

# List a target's tags
curl "$MANTIS_URL/api/v1/targets/<target-id>/tags" \
  -H "Authorization: Bearer $TOKEN"

To Tenants

Tenant tags are managed in Lens (via the tenant detail view) or through the REST API, using the same AttachTagsRequest shape as target tags:

# Attach tags to a tenant
curl -X POST "$MANTIS_URL/api/v1/tenants/<tenant-id>/tags" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag_ids": ["<tag-id-1>", "<tag-id-2>"]}'

# Detach tags from a tenant
curl -X DELETE "$MANTIS_URL/api/v1/tenants/<tenant-id>/tags" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag_ids": ["<tag-id-1>"]}'

# List a tenant's tags
curl "$MANTIS_URL/api/v1/tenants/<tenant-id>/tags" \
  -H "Authorization: Bearer $TOKEN"

The tenants:manage_tags permission is required to attach or detach tenant tags.

Filtering by Tags

Target Filtering

Filter targets by tags in Lens:

┌─────────────────────────────────────────────────────────────┐
│  Targets                                                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Filters:                                                   │
│  [environment: production ▼] [team: platform ▼] [+ Filter]  │
│                                                             │
│  Showing 8 of 36 targets matching filters                   │
│                                                             │
│  ┌────────────────┬──────────┬────────────────────────────┐│
│  │ Name           │ Status   │ Tags                       ││
│  ├────────────────┼──────────┼────────────────────────────┤│
│  │ web-prod-01    │ ● Online │ environment:production,... ││
│  │ web-prod-02    │ ● Online │ environment:production,... ││
│  │ api-prod-01    │ ● Online │ environment:production,... ││
│  │ api-prod-02    │ ● Online │ environment:production,... ││
│  └────────────────┴──────────┴────────────────────────────┘│
│                                                             │
└─────────────────────────────────────────────────────────────┘

Via REST API

GET /api/v1/targets returns each target with its associated tags, so you can list targets and filter by tag client-side (the list endpoint itself does not take a tag query parameter):

# List targets and filter to those tagged environment=production
curl "$MANTIS_URL/api/v1/targets" \
  -H "Authorization: Bearer $TOKEN" | \
  jq '.data[] | select(.tags[] | .key == "environment" and .value == "production")'

The Lens Targets view does not currently support tag-based filtering; the search bar filters only by name or hostname, and the status filter narrows by Online/Stale/Offline. Tag-based target selection is available during deployment creation (the By Tags tab in the new-deployment flow). Client-side filtering via the REST API (as shown above) is the alternative for ad-hoc tag queries.

Deployment Target Selection

Select targets by tag during deployment:

┌─────────────────────────────────────────────────────────────┐
│  Select Deployment Targets                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Selection Mode:                                            │
│  ○ All targets in environment                               │
│  ● Select by tags                                           │
│  ○ Manual selection                                         │
│                                                             │
│  Tag Filters:                                               │
│  [environment: production ▼] [team: platform ▼]             │
│                                                             │
│  Matching targets (4):                                      │
│  ✓ web-prod-01                                              │
│  ✓ web-prod-02                                              │
│  ✓ api-prod-01                                              │
│  ✓ api-prod-02                                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Tag Naming Conventions

Recommended Key Names

Category	Keys	Example Values
Infrastructure	environment, region, zone	production, us-east-1, az-a
Organization	team, department, owner	platform, engineering, alice
Cost	cost-center, project, budget	ops-2024, project-x, q1
Technical	os, runtime, version	linux, nodejs-18, v1.2
Compliance	compliance, data-classification	pci, confidential

Best Practices

Practice	Good Example	Avoid
Lowercase keys	environment	Environment, ENVIRONMENT
Hyphen separators	cost-center	cost_center, costCenter
Short values	prod, stg, dev	production-environment
Consistent prefixes	app-web, app-api	web-app, api-application

Tag Grouping Conventions

The tag system is flat key-value pairs — there are no built-in tag groups or categories. Grouping is a human convention enforced through your chosen key names. For example, using a consistent set of keys (such as those in the naming conventions table above) makes it easy to treat all tags sharing a key like environment as a logical group when browsing or filtering.

Searching and Reports

Finding Tagged Resources

Resources tagged with a given key/value are discovered through the Lens UI or the REST list endpoints. There is no dedicated cross-resource search command.

Via Lens UI: Use the tag filter on a resource list (for example, the Targets view) to narrow results to a specific key:value pair.

Via REST API: Each resource list endpoint returns the tags associated with every item, so you can filter client-side. For example, list targets and inspect their tags arrays:

curl https://mantis.example.com/api/v1/targets \
  -H "Authorization: Bearer $TOKEN"

To enumerate every defined tag, list the tag catalog:

curl https://mantis.example.com/api/v1/tags \
  -H "Authorization: Bearer $TOKEN"

Tag Usage Report

┌─────────────────────────────────────────────────────────────┐
│  Tag Usage Report                                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Total tags: 24                                             │
│  Unique keys: 6                                             │
│                                                             │
│  Usage by Key:                                              │
│  ┌───────────────┬────────┬────────────────────────────┐   │
│  │ Key           │ Values │ Resource Count             │   │
│  ├───────────────┼────────┼────────────────────────────┤   │
│  │ environment   │ 3      │ 36 targets                 │   │
│  │ team          │ 5      │ 28 targets                 │   │
│  │ region        │ 4      │ 36 targets                 │   │
│  │ compliance    │ 3      │ 12 targets                 │   │
│  └───────────────┴────────┴────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Best Practices

1. Define Tag Standards

Document and enforce tag standards:

## Tag Standards

Required tags for all targets:
- environment: production | staging | development
- team: <team-name>
- region: <aws-region>

Optional tags:
- cost-center: <cost-code>
- compliance: pci | hipaa | soc2

2. Use Consistent Tagging

Apply tags consistently across resources:

Resource	Required Tags
All targets	environment, region
Production targets	+ team, compliance
Tenant targets	+ tenant (automatic)

3. Review and Clean Up

Periodically audit tags:

• Remove unused tags
• Fix inconsistent naming
• Update outdated values

4. Avoid Over-Tagging

Keep tags meaningful:

Good	Avoid
3-6 tags per resource	15+ tags per resource
Standard key names	Unique keys per resource
Meaningful values	Random or encoded values

Troubleshooting

Tags Not Filtering Correctly

Cause: Typo in tag key or value

Solution:

1. Check exact spelling (case-sensitive values)
2. Verify tag exists on resources
3. Use dropdown selectors instead of typing

Cannot Remove Tag

Cause: Missing permission or tag already detached

Solution:

1. Check that you have the right permission: tags:delete (detach from the shared vocabulary), targets:update (remove a tag from a target), or tenants:manage_tags (detach from a tenant)
2. Verify the tag is still attached to the resource
3. Contact your administrator if the permission is not granted

Tag Not Appearing

Cause: Tag not yet saved or sync delay

Solution:

1. Refresh the page
2. Verify tag was created successfully
3. Wait for sync if using distributed setup

Next Steps

• Deployment Freezes - Block deployments during time windows
• Audit Logs - Track system changes