---
id: display-names
title: 'System Names and Display Names'
description: 'Mapping between what the UI shows and what the API calls things, using meta.v1 and the localization API'
sidebar_label: 'Display Names'
sidebar_position: 8
tags: ['guides', 'localization', 'terminology']
---

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 name  | Displayed as                                    |
| ------------ | ----------------------------------------------- |
| `Scope`      | Project — or Planning Level in current versions |
| `ScopeLabel` | Program                                         |
| `Epic`       | Portfolio Item                                  |
| `Theme`      | Backlog Group                                   |
| `Timebox`    | Iteration (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](/apis/loc-2-v1) resolves an asset type's display
name from the tag `AssetType'<Token>`:

```text
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](/apis/loc-2-v1/tag-resolution), 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](/reference/asset-type-display-names)
— 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.

## Related Topics

- Product feature: [Configuring terminology and localization
  options](https://docs.digital.ai/agility/docs/agility/configuring-terminology-and-localization-options) — where the
  instance overrides this guide resolves are configured; for `Custom_*`
  fields, [Customizing display names for custom fields and
  columns](https://docs.digital.ai/agility/docs/agility/customizing-display-names-for-custom-fields-and-columns).

- [Localization API](/apis/loc-2-v1)
- [Asset type display names](/reference/asset-type-display-names) — the
  full table
- [Glossary](/reference/glossary) — the common mappings, inline
- [Attributes](/concepts/attributes) — `Token` as the unambiguous name