Experimental. Labels may change shape or be removed in a minor release. They are display and filter only today; the change that makes a route select its targets by label turns a label into configuration the gateway reads, and that is a change in what a label is. Build reporting and filtering on them, not automation you cannot revisit.
A label is a short fact attached to a provider, a provider group, a route or a model. Rolter stores two kinds, and the difference matters when you act on one.
| Custom | Automatic | |
|---|---|---|
| Who sets it | you | Rolter |
| Examples | eu-only, prod, cheap, owner:platform-team | priced |
| Can you edit it | yes | no |
| Carries a timestamp | no | yes |
In the dashboard#
The Providers, Provider Groups, Routing Rules and Model Catalog screens show every label their rows carry, and the tag button on each row (or card) opens a panel that reads, adds, changes and removes them.
Automatic labels are told apart from your own three ways at once — a different tone, a different icon, and the word automatic in what a screen reader says — because the two may carry the same key on the same provider deliberately, and a screen that showed them alike would read as a duplicate. An automatic label is shown with what was observed and when, and offers no edit or delete control: the API refuses both, and the only thing that changes one is the subsystem observing again.
The Filter by label control at the top of each list narrows it to the rows
carrying one key=value, alongside the search box where there is one. A filter
that matches nothing says so and offers to clear itself, rather than reading as
an organization with nothing in it.
Reading labels takes the viewer role and writing them takes admin, so a
caller who may not read them simply sees the screen without them rather than an
error. Labelling a model is a superadmin’s act, the way its price is, so an
admin sees the panel and what it holds with the write controls disabled rather
than a form that would be refused.
Custom labels#
A custom label means whatever you need it to mean. Rolter stores and displays
it and never interprets it — nothing routes differently because a provider is
labelled prod.
A label is a key with an optional value. A key alone reads as a flag
(eu-only); a key with a value reads as a field (owner: platform-team).
Keys are lowercase and may contain letters, digits, and . _ : -, up to
63 characters. Values are up to 128 characters.
Attach one to a provider, provider group or route:
subject_type is provider, provider_group or route. Reading an org’s
labels takes the viewer role; adding, changing or removing one takes admin.
Models are labelled through a separate endpoint, because a model belongs to the deployment-wide pricing catalog rather than to one org — labelling one is a superadmin action:
Re-using a key on the same subject returns 409 Conflict rather than
overwriting what is there. Change the value with PUT, or remove the label
with DELETE, using the label’s id.
Deleting a provider, provider group or route deletes its labels with it.
Automatic labels#
An automatic label is a fact Rolter established itself. It carries when it was established and what established it, and both are shown to you.
An automatic label reflects an observation with a time attached. It is not a
guarantee about the next request. priced means a price existed in the catalog
when Rolter last looked — not that a call you make now will be billed at that
rate.
Today one automatic label ships: priced on a model, whose value is the
currency the price is quoted in, recorded from the pricing catalog. Adding a
price to a model records it; removing the price withdraws it.
You cannot edit or delete an automatic label — those requests answer 404. The
only thing that changes one is Rolter observing again. This is deliberate: a
label you could hand-edit would stop being evidence of anything.
You can set a custom label with the same key. It does not overwrite the automatic one; both are stored and both are shown, marked with their source, so your annotation and Rolter’s observation are never confused for each other.
Filtering#
List endpoints narrow on any combination of subject_type, subject_id,
key, value and source:
What labels do not do yet#
Labels are display and filter only. A route cannot select its targets by label
— you cannot yet write a route that sends traffic to whichever providers are
labelled eu-only. Routing still targets providers explicitly.
That is a deliberate first cut: making labels selectable turns them into configuration the data plane consumes. The storage is shaped so it can be added without a migration rewrite.