Skip to main content

API 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.
  • AssetType — an asset's type (Story, Scope, Member), arranged in an inheritance hierarchy. Abstract types (Workitem, PrimaryWorkitem) can be queried but not created.
  • Attribute — a named property of an asset; defined in meta 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.
  • 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.
  • 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.

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.
  • 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; values quoted.
  • find / findin — text search (substring semantics — unlike ~=, which is full-text).
  • 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.
  • 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. Responds with assetsCreated / assetsModified / assetsOperatedOn / commandFailures / queryResult.
  • Alias — @name labels that let later Bulk commands reference earlier ones, with limitations.
  • 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; unmatched tags echo back.
  • Base URL — https://host/instance/ (e.g. https://www7.v1host.com/MyInstance/); see base URL conventions, including the rest-1.v1/query.v1 URL that works only by accident.