---
id: glossary
title: 'API Glossary'
description: 'The vocabulary of the Agility API - asset model terms, query terms, and the UI names that differ from them'
sidebar_label: 'Glossary'
sidebar_position: 2
tags: ['reference', 'glossary']
---

API names first, UI display names in parentheses — instances can customize
labels, so code should always use the API name and OIDs.

## The Asset Model

- **Asset** — any entity in the system: work items, projects, members, even
  the schema itself. Identified by an [OID](#identifiers).
- **AssetType** — an asset's type (`Story`, `Scope`, `Member`), arranged in
  an [inheritance hierarchy](/concepts/assets#the-asset-type-hierarchy).
  Abstract types (`Workitem`, `PrimaryWorkitem`) can be queried but not
  created.
- **Attribute** — a named property of an asset;
  [defined in meta](/concepts/attributes) with a type, requiredness,
  writability.
- **AttributeDefinition** — the meta description of an attribute — itself a
  queryable asset.
- **Relation** — an attribute whose value is another asset (single) or
  several (multi). Every relation has a **reciprocal** on the other side.
- **Custom attribute** — admin-defined attribute; token usually starts
  `Custom_`, flagged `IsCustom` in meta.
- **Scope** (*Project*) — the container and permission boundary for work;
  forms a tree rooted at `Scope:0`.
- **Scheme** (*Project Workspace*) — controls which list values and roles a
  project offers; carries [Important Fields](#lifecycle-and-status).
- **Timebox** (*Iteration/Sprint*) — a planning period, provided to scopes
  through a shared **Schedule**.
- **Epic** (*Portfolio Item*) — portfolio-level work; nests via
  `Super`/`Subs`.
- **Theme** (*Backlog Group*) — classification hierarchy; primary workitems
  point at one via `Parent`.
- **PrimaryWorkitem** — abstract parent of `Story`, `Defect` and `TestSet`;
  the "backlog item" level.
- **Team Process** — a team's own set of `StoryStatus` values, enforced on
  status change; its Active-rollup subset is the team's **WIP cycle**
  (advisory, with the **WIP limit**).

## Identifiers

- **OID** — `AssetType:id` (`Story:1207`); the permanent identifier used in
  API calls. A third part (`Story:1207:5837`) names a **moment**.
- **Moment** — a point-in-time version of an asset; see
  [moments and history](/concepts/moments-and-history).
- **Number** — the human-readable display number (`S-01001`, `D-01004`);
  use with people, not in code.
- **Moniker** — an asset reference by name in place of an OID token, accepted
  by Bulk API relation values; a backslash path through the type's naming
  context (`Offerings\Agility\Optimize`) narrows it, and it must resolve to
  exactly one asset. See
  [creating assets](/apis/asset-bulk/creating-assets#qualifying-a-name-with-a-path).

## Lifecycle and Status

- **AssetState** — the system lifecycle: Future (0), Active (64),
  Closed/**Inactive** (128 — two names, one value), dead states from 192,
  Deleted (255 — still stored and recoverable). *Not* the same thing as
  Status.
- **List** — the abstract base asset type of every dropdown-value type
  (`StoryStatus`, `Priority`, …). The name means *list entry*, not the
  list: each value is-a `List`; the list as a whole is just every asset
  of the concrete type.
- **Status** — the workflow position: a relation to a list value
  (`StoryStatus`, shared by all primary workitems). Instance data — match
  on OID.
- **RollupState** — a status value's lifecycle category (Future/Active/
  Closed) on `StoryStatus` and `EpicStatus`;
  [what reports actually read](/concepts/workflows#rollupstate).
- **EffectiveAssetState** — the reporting state: an Active asset reports
  its status's RollupState. Drives **DoneDate/DoneDateUTC** (stamped at
  effective closure).
- **IsDeleted** — soft-delete flag; deleted assets need both `?deleted=1`
  and an `IsDeleted` filter to query.
- **Operation** — a named lifecycle action (`Inactivate`, `Delete`,
  `Copy`…) invoked with `?op=` or a Bulk API execute command — distinct
  from attribute updates.
- **Important Fields** — scheme-flagged attributes the UI calls out; can be
  made mandatory at close (`IsRequiredAtClose`).

## Querying

- **where** — exact-match filtering in a query document.
- **filter** — the full [comparison grammar](/reference/query-grammar);
  values quoted.
- **find / findin** — text search (substring semantics — unlike `~=`,
  which is [full-text](/reference/query-grammar)).
- **asof** — point-in-time querying, available on `query.v1` and the Bulk
  API's query command.
- **page** — `{size, start}` in query documents; positional size-first
  (`page=50,0`) on rest-1. **There is no default page size.**
- **needTotal** — opt-in result count; without it a paged response omits
  `total` (rest-1) or reports it as `null` (Bulk API). Prefer
  [stopping on a short page](/guides/query-size-and-performance#paging-correctly).
- **Downcast** — narrowing a relation to a subtype in a path
  (`Children:Task`).
- **Rank** — the opaque ordering type behind `Order` attributes: sort by
  it, never read or compare it.

## Surfaces

- **Bulk API** — `api/asset`: queries, creates, updates and operations in
  one request; the [one-stop shop](/getting-started/choosing-an-api).
  Responds with `assetsCreated` / `assetsModified` / `assetsOperatedOn` /
  `commandFailures` / `queryResult`.
- **Alias** — `@name` labels that let later Bulk commands reference earlier
  ones, [with limitations](/apis/asset-bulk/aliases-and-projection).
- **rest-1.v1** — per-asset REST: `Data` (current), `Hist` (change
  history), `New` (defaulted templates).
- **meta.v1** — the schema, anonymous by design.
- **loc-2.v1** — localization: resolves terminology and
  [some error tags](/apis/conventions/errors#violation-tags-are-localizable);
  unmatched tags echo back.
- **Base URL** — `https://host/instance/` (e.g.
  `https://www7.v1host.com/MyInstance/`); see
  [base URL conventions](/apis/conventions/base-url), including the
  `rest-1.v1/query.v1` URL that works only by accident.

## Related Topics

- [Concepts](/concepts/assets) — the model in prose
- [Query grammar](/reference/query-grammar) — the syntax in full
- [Attribute types](/reference/attribute-types)