Tags & labels

Every mutable resource — Server, Snapshot, Domain, Service, SshKey, Firewall — accepts a labels map: a free-form key/value bag for grouping, billing-tag, and selector-based filtering.

Shape

{
  "labels": {
    "env": "prod",
    "tier": "db",
    "team": "payments",
    "cost-center": "cc-42"
  }
}

• Keys match [a-z][a-z0-9_-]*, 1–63 chars.
• Values are arbitrary text, 0–63 chars (empty string = marker label).
• Max 32 entries per resource.
• Labels are full replacement on PATCH — pass the complete map you want stored, not a diff.

Setting labels

On create:

vpsctl servers create \
  --product-id 24 --billing-cycle monthly \
  --region coc_42 --image coc_99 \
  --label env=prod --label tier=web \
  --payment-method credit

On update:

vpsctl servers update srv_42 \
  --label env=prod --label tier=db --label team=payments

To clear all labels:

vpsctl servers update srv_42 --clear-labels

Filtering list endpoints

Use ?label_selector= with k8s-style equality syntax. Comma separates; every label must match for the resource to be returned.

# Servers tagged env=prod AND tier=db
vpsctl servers list --label-selector env=prod,tier=db

# Match the marker label "deprecated" (any value)
curl 'https://api.vps-server.host/v1/servers?label_selector=deprecated' \
  -H "Authorization: Bearer $VPSH_API_TOKEN"

The same ?label_selector= parameter works on every list endpoint: /servers, /snapshots, /domains, /services, /ssh-keys, /firewalls.

Common patterns

Pattern	Example labels
Environment	env=prod, env=staging, env=dev
Team ownership	team=payments, team=growth
Cost allocation	cost-center=cc-42, project=q3-launch
Deprecation marker	deprecated=, do-not-delete=
Application tier	tier=web, tier=app, tier=db

Don't store secrets in labels — they're not encrypted and they show up in audit logs.

Anti-patterns

• Don't put dynamic state in labels (uptime, traffic). Use metrics endpoints for that. Labels are for human-meaningful grouping.
• Don't use labels for access control. They're descriptive, not authoritative. PAT scopes are how you restrict access.
• Don't go past ~10 labels per resource. You can technically have 32 but past 10 the selector queries get unreadable.

MCP tools

Labels appear as a normal field on every resource's get_* / list_* tool output. Set them via update_server, update_snapshot, etc. Filter by passing label_selector to any list_* tool that supports it.