Skip to content
Token Controller Docs
Docs / API / Tags, attributes and rules

Tags, attributes and rules

Tags say what work was for; attributes say who the person is. Both are records with defaults: a feature brings its project, a project its client, a team its department. Rules turn signals into tags, including the contract, when a message arrives.

Endpoint What it does Who
GET /tags Tag names with the values you may view. Anyone
POST /tags Add a tag name, such as purpose. Org manager, in the web app
DELETE /tags/{name} Remove a tag name you added. Built-in names stay; values on record stay in the log. Org manager, in the web app
POST /tags/{name}/values Add a tag value, or change one: the same key again supersedes the earlier record. Assign on the value's tags with their defaults, in the web app
GET /attributes Attribute names with their values. Anyone
POST /attributes Add an attribute name, such as guild. Org manager, in the web app
POST /attributes/{name}/values Add an attribute value, or change one. Assign on the value with its defaults, in the web app
POST /people/{id}/attributes Put an attribute on a person from a date. Assign on the value with its defaults, in the web app
GET /rules The organization's rules and your own, in the order they run. Anyone
POST /rules Add an organization rule. Assign on the tag it sets, in the web app
GET /me/rules, PUT /me/rules Your own rules; replace them. Anyone, for themselves
GET /me/context What a local tool needs to split sessions like the service does. Anyone, for themselves
/tag-sources Connect Jira as a tag source, set the sync map, sync now. Org manager, in the web app

Tag names and values

GET /api/v1/tags?as_of=2026-03-31
[
{
"name": "client",
"built_in": true,
"values": [
{ "id": "tag_77d1…", "name": "client", "key": "acme", "title": "Acme", "description": null, "source_id": null, "source_status": null, "defaults": {}, "contract": null, "recorded_at": "2026-02-01T09:00:00Z" }
]
},
{
"name": "feature",
"built_in": true,
"values": [
{
"id": "tag_5e0c…",
"name": "feature",
"key": "KD-1",
"title": "Checkout redesign",
"description": "A new checkout flow with saved addresses and one-page payment.",
"source_id": "10412",
"source_status": "in progress",
"defaults": { "project": "shop" },
"contract": null,
"recorded_at": "2026-02-01T09:00:00Z"
}
]
},
{
"name": "project",
"built_in": true,
"values": [
{ "id": "tag_1a9b…", "name": "project", "key": "shop", "title": "Shop", "description": "Acme's web shop.", "source_id": null, "source_status": null, "defaults": { "client": "acme" }, "contract": null, "recorded_at": "2026-02-01T09:00:00Z" }
]
},
{ "name": "purpose", "built_in": false, "values": [] }
]

Built-in names come first, then the names you added, each in alphabetical order. project, feature and client are built in. contract is built in too, for money; its values are listed with their terms by GET /contracts. source_id and source_status are set by a tag source's sync, such as the Jira issue id and its status. contract holds the terms on a value of contract, and is null on every other value. A value's id is its event id; reversing it retires the value.

Add a tag name with POST /tags and {"name": "purpose"}: lower-case letters, digits, - and _, up to 40 characters, and never person. 201 when added, 200 when it is already on the list. Then add values:

POST /api/v1/tags/project/values
{ "key": "shop", "title": "Shop", "description": "Acme's web shop.", "defaults": { "client": "acme" } }

201 with the value as above. Each default must be a value on record. A record with the same name and key supersedes the earlier one, so this is also how a project changes its client; the change applies to figures as of a later date, never to figures as of the cutoff. dated dates the record; before the cutoff that needs adjust. contract takes a contract's terms on a value of contract only; see Contracts. 404 for a tag name that does not exist. See Tags.

Attributes

GET /attributes has the same shape as GET /tags, for team, department and location, which are built in, and the names you add:

[
{ "name": "department", "built_in": true, "values": [ { "id": "att_90ef…", "name": "department", "key": "engineering", "title": "Engineering", "defaults": {}, "recorded_at": "2026-02-01T09:00:00Z" } ] },
{ "name": "location", "built_in": true, "values": [] },
{ "name": "team", "built_in": true, "values": [ { "id": "att_3c4d…", "name": "team", "key": "web", "title": "Web", "defaults": { "department": "engineering" }, "recorded_at": "2026-02-01T09:00:00Z" } ] }
]

POST /attributes/{name}/values takes key, title and defaults, like a tag value. A person gets an attribute from a date:

POST /api/v1/people/7f1c4e2a-…/attributes
{ "name": "team", "key": "web", "from": "2026-03-01" }

201 with id (pat_…), person, name, key and from. The person keeps the earlier value for earlier days, so a team change on 1 April moves April's cost and leaves March's where it was. Left out, from means every day. The {id} is the member's id from GET /members. See Attributes.

Rules

A rule is a pattern over one signal that gives a tag value. It runs when a message arrives and back over messages since the cutoff that nobody assigned by hand. Rules resolve per tag name: the first matching rule for feature and the first for contract both apply. A rule on contract may run back before the cutoff, since figures as of the cutoff stay as they were.

POST /api/v1/rules
{
"name": "feature key in branch",
"signal": "branch",
"pattern": "(?<key>KD-\\d+)",
"tag_name": "feature"
}
Field Meaning
name The name people see, 1 to 100 characters.
signal branch, working_directory, repository, pull_request_title, subagent_type, prompt_keys, agent_name, config:<name>, resource:<name> or any other signal by its name, such as organization.id.
pattern A regular expression. A group named key picks the tag value's key; without one, the whole match is the key.
tag_name The tag name the rule sets, such as feature, project or contract.
key A fixed key, such as shop for "repository kestrel/shop is project Shop". It must be a value on record, or for contract a contract the organization has. Left out, the rule sets the key the pattern finds.
order Lower runs first. Default: 10 more than the highest order there is, so the first rule is 10.

201:

{
"id": "rul_6a1f…",
"name": "feature key in branch",
"scope": "organization",
"order": 20,
"signal": "branch",
"pattern": "(?<key>KD-\\d+)",
"tag_name": "feature",
"key": null,
"recorded_at": "2026-02-01T09:10:00Z"
}

The worked month has two rules on contract at order 10: organization.id matching ^kestrel-team$ gives claude-team, and agent_name matching ^review bot$ gives anthropic-api. Beside the organization's rules, Token Controller ships a sign-in rule that is not in this list: a message whose agent reports the Anthropic organization it was signed in to, as organization.id, gets a metered contract named after it, such as anthropic-6f1e2a3b, created the first time it matches. The organization's own rules on contract run before it.

GET /rules lists the organization's rules and your own in the order they run; scope is organization or your email. A rule is removed by reversing its id. PUT /me/rules takes a list of rules in the same shape and replaces your own; they run after the organization's, on your messages only. See Rules.

The CLI's context

GET /me/context is what tc reads once to split sessions on the machine the way the service does:

{
"organization": { "id": "…", "name": "Kestrel Digital", "slug": "kestrel" },
"person": "mara@kestrel.example",
"reporting_currency": "USD",
"cutoff": "2026-02-28",
"rules": [ … ],
"names": [ { "name": "client", "kind": "tag", "built_in": true }, { "name": "team", "kind": "attribute", "built_in": true } ],
"tag_values": [ … ],
"attribute_values": [ … ],
"attributes": { "team": "web" },
"price_table": [ … ],
"as_of": "2026-03-10T07:00:00Z"
}

rules are the organization's and your own in order, names every tag and attribute name, tag_values the values you may view, attributes yours today, price_table the rows in force.

Jira

An org manager connects Jira Cloud in the web app as a tag source; its issues become features with their project as default, synced every 15 minutes. The token is never sent back.

Endpoint What it does
GET /tag-sources The connections, each with id, kind, site, key_hint, mappings, last_sync_at, status (ok or failing) and message.
POST /tag-sources {"kind": "jira", "site": "https://acme.atlassian.net", "email": "…", "token": "…"}. The first sync starts right away. 400 when the address or the token is not usable.
GET /tag-sources/{id}/projects The Jira projects the token can see, as key and name, to map.
PUT /tag-sources/{id}/mappings The sync map, replacing the earlier one: a list of {"external": "KD", "project": "shop", "fields": ["title", "description", "type", "status", "parent", "assignee"]}. fields left out copies all of them. 400 for an unknown project or one mapped twice.
POST /tag-sources/{id}/sync Sync now. 202: it starts within a minute.
DELETE /tag-sources/{id} Disconnect. Its features stay and stop syncing. 204.

See Jira.

Last updated 16 November 2026 · Edit this page© 2026 Jan Beck · Privacy · Imprint