Skip to main content

System Names and Display Names

The UI and the API speak different languages on purpose: the API uses stable system names, while the UI shows localized, instance-configurable display names. The gap trips up every integrator eventually:

System nameDisplayed as
ScopeProject — or Planning Level in current versions
ScopeLabelProgram
EpicPortfolio Item
ThemeBacklog Group
TimeboxIteration (or Sprint, by terminology)

Two audiences hit it from opposite sides. Developers outside the product team see a word in the UI — or hear one from a user — and have to work out which system name it belongs to before they can write a query. Administrators customizing terminology have the opposite problem: the Terminology page (Admin → Configuration → Terminology) overrides display names keyed by localization tag, so they need the tag for the thing they want to rename.

Both answers come from the same two endpoints. Code should always use system names and OIDs; the mapping is for the humans on either end.

System Name → Display Name​

The localization API resolves an asset type's display name from the tag AssetType'<Token>:

GET ~/loc-2.v1?[AssetType'ScopeLabel,AssetType'Epic,AssetType'Scope]

{"AssetType'ScopeLabel": "Program", "AssetType'Epic": "Portfolio Item", "AssetType'Scope": "Project"}

No authentication needed, and the answer arrives in the caller's language. Unmatched tags echo back, so over-asking is harmless.

Attribute display names work the same way — meta.v1 hands you the tag: every attribute definition's DisplayName field is a localization tag (AttributeDefinition'Owners'Story), ready to feed through loc-2.v1. For asset types, the tag is simply the system name — which is also the key the Terminology page customizes.

Display Name → System Name: Build the Table​

There is no reverse-lookup endpoint. If you have admin access, the Terminology page shows each display name beside its System Name — but most outside developers don't. The API recipe is to enumerate and localize once, then look up client-side:

  1. GET ~/meta.v1 — the schema lists every asset type token.
  2. loc-2.v1 requests with the AssetType'<Token> tags — batched into groups, since a query string carrying every tag at once is longer than servers accept.
  3. Invert the result into a display-name → system-name map.

The instance driver ships this as a runnable script — tools/instance-driver/examples/list-display-names.js in the documentation repository — which prints the full table for any instance. The result of running it against a default-terminology instance is published as the asset type display names reference — exhaustive by design, and aimed as much at AI agents reading this site as at people.

Cache the table like any localization data: it changes on configuration, not in daily use — and remember two display names can collide (nothing stops an administrator naming two things alike), which is one more reason the system-name side of the map is the one to store.