Tag and label your fleet

Once you run more than a few machines, “which one was db1 again” becomes a question you actually ask. Two small pieces of metadata answer it, and you can script both. A label is one friendly name for a machine. Tags are a set of short words you attach for grouping and filtering. Neither changes anything the machine does. They're there so the fleet makes sense to you, and to your tooling.

Label: one name per machine

A label is a single human-readable name shown next to the hostname in your lists. You set it with PUT /v1/servers/{id}/label and a servers.write key:

curl -s -X PUT https://api.amoni.app/v1/servers/955/label \
  -H "Authorization: Bearer nr_live_..." -H "Content-Type: application/json" \
  -d '{"label": "web-prod-1"}'
# { "success": true, "data": { "label": "web-prod-1", "message": "Label updated." } }

Labels max out at 60 characters, and an empty string removes one. Each server has exactly one label, so setting a new one replaces the old.

Tags: a set you filter on

Tags are how you organize across the whole fleet: prod, web, a datacenter code, a customer's name. You read them with GET /v1/servers/{id}/tags and write them with PUT /v1/servers/{id}/tags. The write replaces the whole set, which means you send every tag the server should end up with, not only the new one:

curl -s -X PUT https://api.amoni.app/v1/servers/955/tags \
  -H "Authorization: Bearer nr_live_..." -H "Content-Type: application/json" \
  -d '{"tags": ["prod", "web", "fra"]}'
# { "success": true, "data": { "tags": ["prod", "web", "fra"], "message": "Tags updated." } }

Adding a tag means reading the current set, appending, and writing it back. An empty array clears them all. Reads come back sorted:

curl -s https://api.amoni.app/v1/servers/955/tags \
  -H "Authorization: Bearer nr_live_..."
# { "success": true, "data": { "tags": ["fra", "prod", "web"] } }

A few rules keep tags tidy and easy for scripts to handle. A server can hold up to ten tags. Each one is lower-cased and cut down to letters, digits and hyphens, so Prod Web is stored as prod-web, and none may run past 30 characters. Tags that begin with int-netr- are reserved for our own use; the API refuses them with code reserved_tag.

Filter the fleet on them

Tags pay off when you ask the fleet a question. GET /v1/servers returns each server with its label and tags, so you filter in your own code, without any special query:

# every production web server, by tag
curl -s https://api.amoni.app/v1/servers \
  -H "Authorization: Bearer nr_live_..." \
  | jq -r '.data[] | select(.tags | index("prod") and index("web"))
           | "\(.id)\t\(.label // .hostname)"'

The ids then go into whatever comes next: a reinstall, a reverse-DNS pass, a power action. A script that acts on a tag stays correct as the fleet changes. One that carries a hardcoded list of ids doesn't.

Cloud instances too

Cloud instances have the same two fields, on their own routes: PUT /v1/vms/{account}/{id}/label and PUT /v1/vms/{account}/{id}/tags, using a vms.write key. The rules don't change, so a single tagging convention can span bare metal and cloud.

The same names show in the portal

The labels and tags you set over the API are the ones the portal shows. There's no separate API-only metadata. A label written by a script appears next to the hostname in your lists. Tags and projects complement each other: tags are lightweight and a machine can carry many, while a project is a single grouping with running totals attached.

Questions we get

• Does the tag write merge or replace? Replace. Send the complete set every time; to add or remove one, read, change and write it back.
• Why did my tag come back changed? Tags are normalized to lower-case letters, digits and hyphens, so DB-01 becomes db-01. That's expected; filter on the normalized form.
• What is the difference between a label and a tag? A label names the machine. Tags are a set you group and filter on. Use both.
• Can I search the whole account for a tag? Yes, in your own code: list the servers and filter on tags. Each server comes with its tags in the list response.

Still stuck?

Open a support ticket if a tag write gets refused and the code isn't reserved_tag. We can check what that server will accept.