# Digital.ai Agility API Documentation

> The canonical developer documentation for the Digital.ai Agility API

This index lists every page on https://docs.digital.ai/agility-api/ (131 pages).

- Every page is also served as raw CommonMark: append `.md` to its URL.
- The entire corpus, concatenated in this order, is at https://docs.digital.ai/agility-api/llms-full.txt.
- Auto-generated tag listing pages are omitted; they contain no prose.

## Overview

- [Digital.ai Agility API Documentation](https://docs.digital.ai/agility-api/): Developer reference for the Digital.ai Agility API: endpoints, query syntax, and the behaviour you can rely on.

## Getting started

- [Getting Started with the Agility API](https://docs.digital.ai/agility-api/getting-started/quickstart): Learn how to authenticate and make your first API calls to Digital.ai Agility
- [Authentication Guide](https://docs.digital.ai/agility-api/getting-started/authentication): Access tokens, Basic authentication and the headers every Digital.ai Agility API request needs.
- [Choosing an API](https://docs.digital.ai/agility-api/getting-started/choosing-an-api): Decide between query.v1, rest-1.v1, api/asset and meta.v1 for your Agility integration.

## Concepts

- [Assets in Agility](https://docs.digital.ai/agility-api/concepts/assets): Understanding assets, asset types, OIDs and the core data model in Digital.ai Agility
- [Attributes in Agility](https://docs.digital.ai/agility-api/concepts/attributes): Understanding asset attributes, attribute definitions and data types in Digital.ai Agility
- [Relations in Agility](https://docs.digital.ai/agility-api/concepts/relations): Understanding relation attributes - the links that form the Agility asset graph - and how to traverse, filter and modify them
- [Operations in Agility](https://docs.digital.ai/agility-api/concepts/operations): Understanding operations - the named actions that change asset lifecycle state in Digital.ai Agility
- [Scopes and Projects](https://docs.digital.ai/agility-api/concepts/scope-projects): Understanding Scope - the asset behind Projects - its hierarchy, lifecycle and role in queries and permissions
- [Workflows and Status](https://docs.digital.ai/agility-api/concepts/workflows): How status lists, RollupState and asset lifecycle interact in Digital.ai Agility - and what the API does and does not enforce
- [Moments & History](https://docs.digital.ai/agility-api/concepts/moments-and-history): How Agility journals changes as globally-sequential moments, and how moments drive the Hist namespace, versioned asset addresses and asof queries.

## APIs

- [API Conventions](https://docs.digital.ai/agility-api/apis/conventions): Base URLs, HTTP headers, error shapes and terminology shared by every Agility API.
- [Base URL](https://docs.digital.ai/agility-api/apis/conventions/base-url): How to build the base URL that every Agility API request is relative to, from your instance host and instance name.
- [HTTP Headers](https://docs.digital.ai/agility-api/apis/conventions/http-headers): The Authorization, Content-Type and Accept headers required by every Agility API request, and what each one controls.
- [Errors](https://docs.digital.ai/agility-api/apis/conventions/errors): The HTTP status codes the Agility APIs return, what each one means, and how to read the error payload.
- [Attribute Definition Syntax](https://docs.digital.ai/agility-api/apis/conventions/attribute-definitions): Where to find the normative attribute-path and filter-expression grammar shared by every Agility query surface.
- [Terminology](https://docs.digital.ai/agility-api/apis/conventions/terminology): Asset, asset type, asset state, attribute definition and Oid — the five terms the Agility API vocabulary is built from.
- [Dates and Date Ranges](https://docs.digital.ai/agility-api/apis/conventions/dates): How Agility stores date ranges. EndDate is exclusive — midnight of the day after the range ends — which is the source of most off-by-one errors against the API.
- [Bulk API (api/asset)](https://docs.digital.ai/agility-api/apis/asset-bulk): Create, update, query and invoke operations on many assets in a single request against ~/api/asset.
- [Request and Response Format](https://docs.digital.ai/agility-api/apis/asset-bulk/request-format): Content types, the JSON-array and YAML-multi-document forms, the response envelope, resultMetaData, and config counts-only.
- [Creating Assets](https://docs.digital.ai/agility-api/apis/asset-bulk/creating-assets): Create one asset, many assets, or a whole hierarchy in a single Bulk API request.
- [Updating Assets](https://docs.digital.ai/agility-api/apis/asset-bulk/updating-assets): Update a single asset by OID token, or every asset matching a query, in one Bulk API request.
- [Updating Multi-Value Relations](https://docs.digital.ai/agility-api/apis/asset-bulk/relation-updates): The complete add/remove grammar for multi-value relations on the Bulk API, including object-keys, subquery, and mixed forms.
- [Find and Replace](https://docs.digital.ai/agility-api/apis/asset-bulk/find-and-replace): Conditionally replace substrings in text attributes and swap references in multi-value relations across many assets at once.
- [Invoking Operations](https://docs.digital.ai/agility-api/apis/asset-bulk/operations): Execute Agility operations against one asset or every asset matching a query, with args, list, and subquery parameter forms.
- [Queries](https://docs.digital.ai/agility-api/apis/asset-bulk/queries): Issue one or many independent queries in a Bulk API request and read the multi-result-set response.
- [Projection, Processing and Aliases](https://docs.digital.ai/agility-api/apis/asset-bulk/aliases-and-projection): The two-phase execution model behind the Bulk API, auto-aliasing, user-aliasing, request hierarchy flattening, and deferred commands.
- [Preview Mode](https://docs.digital.ai/agility-api/apis/asset-bulk/preview-mode): Use ?previewOnly=true to stop a Bulk API request after the projection phase and inspect exactly what it would do.
- [Errors and Partial Failures](https://docs.digital.ai/agility-api/apis/asset-bulk/errors): How the Bulk API reports partial failure, how failures cascade through a hierarchy, and how to correct and reissue a failed request safely.
- [Compound Requests](https://docs.digital.ai/agility-api/apis/asset-bulk/compound-requests): A capstone Bulk API example that creates a project hierarchy, invokes an operation on a newly created asset, and queries the result in one request.
- [Meta API (meta.v1)](https://docs.digital.ai/agility-api/apis/meta-v1): Discover the asset types, attribute definitions and operations your Agility instance actually supports, before you address them through rest-1.v1.
- [Query Examples](https://docs.digital.ai/agility-api/apis/meta-v1/query-examples): The four meta.v1 query shapes - all of Meta, one asset type, one attribute definition and one operation - with real responses.
- [Security and Errors](https://docs.digital.ai/agility-api/apis/meta-v1/security-and-errors): meta.v1 requires no authentication. This page covers that, and the error payload and status codes it returns.
- [REST API (rest-1.v1)](https://docs.digital.ai/agility-api/apis/rest-1): Query, create, update and operate on Agility assets over HTTP, including full historical access through the Hist namespace.
- [Information Model](https://docs.digital.ai/agility-api/apis/rest-1/information-model): Asset types, attribute definitions, assets, attributes and moments - the five concepts the whole Agility API is built on.
- [Query Examples](https://docs.digital.ai/agility-api/apis/rest-1/query-examples): Worked rest-1.v1 GET queries with real response payloads, from a single asset through filtering, sorting, paging, text search and history.
- [Update Examples](https://docs.digital.ai/agility-api/apis/rest-1/update-examples): Worked rest-1.v1 POST payloads for scalar attributes, single-value relations, multi-value relations and asset creation.
- [New Asset Templates](https://docs.digital.ai/agility-api/apis/rest-1/new-asset-templates): The rest-1.v1 New endpoint, which returns a pre-populated, context-aware payload you can edit and post back to create an asset.
- [Operations](https://docs.digital.ai/agility-api/apis/rest-1/operations): Executing named operations such as Delete, Inactivate, Reactivate and Activate against a single asset with the op query parameter.
- [XML Response Reference](https://docs.digital.ai/agility-api/apis/rest-1/xml-responses): The shape of every rest-1.v1 response: Data and Hist queries by asset type, asset and attribute, plus update, New and operation responses.
- [Security and Errors](https://docs.digital.ai/agility-api/apis/rest-1/security-and-errors): How rest-1.v1 authenticates requests, and the error payload and status codes it returns when something goes wrong.
- [Query API (query.v1)](https://docs.digital.ai/agility-api/apis/query-v1): Retrieve Agility assets with flexible filtering, sorting, and pagination
- [Webhooks (api/webhook)](https://docs.digital.ai/agility-api/apis/webhooks): Subscribe to asset created and changed events and have Agility push them to your system instead of polling.
- [Event Types](https://docs.digital.ai/agility-api/apis/webhooks/event-types): Describe exactly which asset changes should fire a webhook using type, from, attributes, filter, with, userContext and select.
- [Webhook Payload](https://docs.digital.ai/agility-api/apis/webhooks/payload): The JSON Agility POSTs to your endpoint, the headers it sends, and how to verify the HMAC signature.
- [Create a Subscription](https://docs.digital.ai/agility-api/apis/webhooks/create): Create a webhook subscription with POST ~/api/webhook.
- [Query Subscriptions](https://docs.digital.ai/agility-api/apis/webhooks/query): List webhook subscriptions with paging, or retrieve one by id.
- [Update a Subscription](https://docs.digital.ai/agility-api/apis/webhooks/update): Change a webhook subscription with POST ~/api/webhook/:id.
- [Delete a Subscription](https://docs.digital.ai/agility-api/apis/webhooks/delete): Delete a webhook subscription with POST ~/api/webhook/delete/:id — note the verb and the path shape.
- [Delivery Status](https://docs.digital.ai/agility-api/apis/webhooks/status): Inspect the 20 most recent delivery receipts for a subscription to troubleshoot webhooks that are not arriving.
- [Tags (api/tags)](https://docs.digital.ai/agility-api/apis/tags): Query, search, merge and remove asset tags instance-wide through ~/api/tags.
- [Query a Tag](https://docs.digital.ai/agility-api/apis/tags/query): Retrieve usage counts for a single tag with GET ~/api/tags?tag=<tag>.
- [Query All Tags](https://docs.digital.ai/agility-api/apis/tags/query-all): Retrieve every tag in use across the instance with usage counts, via GET ~/api/tags/all.
- [Search Tags](https://docs.digital.ai/agility-api/apis/tags/search): Substring-match tag names with GET ~/api/tags/command/search?term=<term>.
- [Merge Tags](https://docs.digital.ai/agility-api/apis/tags/merge): Collapse several tags into one across every asset with POST ~/api/tags/command/merge.
- [Remove Tags](https://docs.digital.ai/agility-api/apis/tags/remove): Purge tags from every asset carrying them with POST ~/api/tags/command/remove.
- [Activity Stream (api/ActivityStream)](https://docs.digital.ai/agility-api/apis/activity-stream): Read-only feed of what happened to an asset — who did what, when — with verb filtering and date-anchored paging.
- [Query Activity](https://docs.digital.ai/agility-api/apis/activity-stream/query): Retrieve the activity feed for an asset, with a field-by-field walkthrough of the response.
- [Asset Permalinks (assetdetail.v1)](https://docs.digital.ai/agility-api/apis/asset-permalinks): Turn an OID or an asset Number into a clickable link that opens the asset in the Agility UI.
- [Localization (loc-2.v1)](https://docs.digital.ai/agility-api/apis/loc-2-v1): The localization API and the localizer engine behind it: term stacks, nested substitution, culture fallback, template set overrides, hot reload and noloc.
- [Requests and Responses](https://docs.digital.ai/agility-api/apis/loc-2-v1/requests-and-responses): Methods, query-string syntax, response shapes, authentication, errors and caching for the loc-2.v1 localization endpoint.
- [Tag Resolution: the Term Stack](https://docs.digital.ai/agility-api/apis/loc-2-v1/tag-resolution): How the Agility localizer resolves a tag through a stack of terms, from most specific to least specific, and what wins.
- [Nested Tag Substitution](https://docs.digital.ai/agility-api/apis/loc-2-v1/nested-tags): How {} placeholders inside a localization template are resolved recursively, how numeric term indices work, and how literal braces are escaped.
- [Culture Fallback](https://docs.digital.ai/agility-api/apis/loc-2-v1/culture-fallback): How Accept-Language maps to a localizer, how the specific/neutral/default fallback chain works, and what happens when a culture is partially or wholly unmatched.
- [Template Sets and Override Order](https://docs.digital.ai/agility-api/apis/loc-2-v1/template-sets): How Base, edition and Company template sets stack, how later sets override earlier ones, how an empty value deletes an entry, and what Agility actually loads.
- [Template File Format](https://docs.digital.ai/agility-api/apis/loc-2-v1/template-file-format): The text file format behind Agility localization template sets: naming, UTF-8 encoding, comments, escaping, multi-line values and deletions.
- [Hot Reload and Caching](https://docs.digital.ai/agility-api/apis/loc-2-v1/hot-reload): How Agility picks up edited localization template files without a restart, and the ETag caveat that can hide the change from HTTP clients.
- [Debugging with noloc](https://docs.digital.ai/agility-api/apis/loc-2-v1/noloc): Turn localization off to see raw localization tags instead of localized text — the fastest way to find out which tag drives a piece of UI or an API label.
- [Terminology Overrides](https://docs.digital.ai/agility-api/apis/loc-2-v1/overrides): api/localization and api/localizations — read and write the terminology overrides that sit at the top of the localization resolution stack.
- [Field Visibility](https://docs.digital.ai/agility-api/apis/field-visibility): Discover which attributes are appropriate to show a user for a given asset type, scope and licence — api/visibleFields, api/visibleFieldsByAsset, api/customFields and api/canbeimportant.
- [Visible Fields](https://docs.digital.ai/agility-api/apis/field-visibility/visible-fields): api/visibleFields and api/visibleFieldsByAsset — the attribute names appropriate to display for an asset type in a scope, or for one specific asset.
- [Custom Fields](https://docs.digital.ai/agility-api/apis/field-visibility/custom-fields): api/customFields — the custom fields visible for a given asset. A POST endpoint despite reading nothing but metadata.
- [Can Be Important](https://docs.digital.ai/agility-api/apis/field-visibility/can-be-important): api/canbeimportant — asks, for a batch of attribute definitions, which ones can be flagged as important. Unknown tokens are silently dropped.
- [Rooms & Panels](https://docs.digital.ai/agility-api/apis/rooms): api/teamroom and api/planningroom — configure the panels shown in a Team Room or Planning Room.
- [Room Panels](https://docs.digital.ai/agility-api/apis/rooms/panels): api/teamroom and api/planningroom — list, install, remove and update the panels in a room, including the planning-room panel configuration payload and its perspective override.
- [Project Roles (api/ProjectRoles)](https://docs.digital.ai/agility-api/apis/project-roles): Read which members hold which roles on which projects. A read-only, self-describing endpoint that publishes its own RAML specification.
- [Watch (api/watch)](https://docs.digital.ai/agility-api/apis/watch): Subscribe the calling member to an asset, check whether they are watching it, and list everything they watch.
- [Attachments and Images (attachment.img)](https://docs.digital.ai/agility-api/apis/attachments): Upload and download attachment and image binaries. Two workflows, a family of blob endpoints, and an id format that is not an OID token.
- [Valid Values (api/ValidValues)](https://docs.digital.ai/agility-api/apis/valid-values): Ask what values a relation attribute may take - the endpoint the application uses to populate its dropdowns, Team Process included.
- [Configuration (config.v1)](https://docs.digital.ai/agility-api/apis/config-v1): Read an instance's effective configuration - attachment size limit, time zone, effort tracking - without authentication.
- [Sync & Connect](https://docs.digital.ai/agility-api/apis/sync): Agility Sync / Agility Connect - the ancillary integration product and the shape of its API

## Reference

- [Query Grammar](https://docs.digital.ai/agility-api/reference/query-grammar): Normative reference for the attribute-path and filter syntax shared by rest-1.v1, query.v1 and api/asset: attribute paths, downcasts, aggregations, filter expressions, filter context, sort and paging.
- [Attribute Paths](https://docs.digital.ai/agility-api/reference/query-grammar/attribute-paths): Dot notation, downcasting to a subtype, aggregation rollups, the now-only operator, and filters applied part-way along an attribute path.
- [Filter Expressions](https://docs.digital.ai/agility-api/reference/query-grammar/filter-expressions): The where language: comparison operators including LIKE, boolean composition and grouping, value lists, unary existence assertions, and variables.
- [Filter Context](https://docs.digital.ai/agility-api/reference/query-grammar/filter-context): The with parameter: assigning variables that filter expressions reference, and how its lexing rules differ from the filter language.
- [Sort and Paging](https://docs.digital.ai/agility-api/reference/query-grammar/sort-and-paging): Ordering results with + and -, and paging with page=size,start — including the argument order that is commonly reversed.
- [Grammar Reference](https://docs.digital.ai/agility-api/reference/query-grammar/ebnf): The complete rest-1.v1 query syntax rendered as EBNF, with the raw ANTLR grammar files available for download.
- [API Glossary](https://docs.digital.ai/agility-api/reference/glossary): The vocabulary of the Agility API - asset model terms, query terms, and the UI names that differ from them
- [HTTP Status Codes Reference](https://docs.digital.ai/agility-api/reference/status-codes): What each HTTP status actually means on the Agility API, with real response bodies
- [About This Documentation](https://docs.digital.ai/agility-api/reference/sources): What this site covers, how it is verified, and where product documentation lives.
- [Attribute Types](https://docs.digital.ai/agility-api/reference/attribute-types): The complete list of Agility attribute types reported by meta.v1, with the underlying data type of each.
- [Roles and Permissions](https://docs.digital.ai/agility-api/reference/roles-and-permissions): The thirteen roles Agility supports, how Rights differ from Privileges, and what actually separates one role from another — written for integrators provisioning Members.
- [Asset Type Display Names](https://docs.digital.ai/agility-api/reference/asset-type-display-names): Every asset type system name with its default display name — an exhaustive lookup table aimed at tooling and AI agents
- [Agent Primer](https://docs.digital.ai/agility-api/reference/agent-primer): A dense, imperative briefing for AI agents calling the Agility API - decision procedures, contracts, and anti-patterns, with links to the owning pages

## Guides

- [Query Size and Performance](https://docs.digital.ai/agility-api/guides/query-size-and-performance): Agility applies no default page size, so an unbounded query tries to return every matching asset. How three separate defaults compound, and the request shape that avoids them.
- [Error Handling Guide](https://docs.digital.ai/agility-api/guides/error-handling): How Agility API errors actually present, and how to handle them: partial failures, violation tags, retries and timeouts
- [Payload Patterns Guide](https://docs.digital.ai/agility-api/guides/payload-patterns): The canonical request shapes for querying, creating, updating and operating on Agility assets
- [Performance Best Practices](https://docs.digital.ai/agility-api/guides/performance): Decision-level performance guidance for Agility integrations: what to cache, when to batch, how much to parallelize
- [Reproducing Reported Numbers](https://docs.digital.ai/agility-api/guides/reproducing-reported-numbers): Why a figure in Agility does not match the one your query returns, and how to reconstruct the calculation behind it — using velocity as the worked example.
- [Working with Comments](https://docs.digital.ai/agility-api/guides/working-with-comments): Conversations, Expressions and Mentions - the model behind comments, and how to create, reply to and read them through the API
- [Scope Context and Filtering](https://docs.digital.ai/agility-api/guides/scope-context): The scope context - how Agility narrows the Scope hierarchy for filtering, and how Rooms embody it
- [System Names and Display Names](https://docs.digital.ai/agility-api/guides/display-names): Mapping between what the UI shows and what the API calls things, using meta.v1 and the localization API
- [Members, Roles, and Scopes](https://docs.digital.ai/agility-api/guides/members-roles-scopes): How access is granted and read through the API - default-role membership, the AssignWithRole operations, and the Project Roles read API
- [Rate Limiting](https://docs.digital.ai/agility-api/guides/rate-limiting): How Agility enforces API rate limits, how to check configured quota policies, and which endpoints expose usage metrics

## Examples

- [cURL Examples](https://docs.digital.ai/agility-api/examples/curl): Runnable cURL examples for the Digital.ai Agility API
- [Python Examples](https://docs.digital.ai/agility-api/examples/python): Runnable Python examples for the Digital.ai Agility API
- [TypeScript Examples](https://docs.digital.ai/agility-api/examples/typescript): Runnable TypeScript examples for the Digital.ai Agility API

## SDK

- [Agility SDK Overview](https://docs.digital.ai/agility-api/sdk/agility-sdk): Object-oriented Java and .NET clients that wrap the Agility API, plus community-maintained SDKs for other languages
- [Java SDK Library](https://docs.digital.ai/agility-api/sdk/java/java-sdk): This topic explains how to use the Java SDK with Agility
- [Creating a Connection Java SDK](https://docs.digital.ai/agility-api/sdk/java/creating-a-connection-java-sdk): This topic explains how to connect to Digital.ai Agility using Java SDK
- [Creating a Services Object](https://docs.digital.ai/agility-api/sdk/java/creating-a-services-object-java-sdk): This topic explains how to create a services object in Agility
- [Query Assets using Java SDK](https://docs.digital.ai/agility-api/sdk/java/querying-assets-java-sdk): This topic explains how to query for assets using Java SDK
- [Querying Asset History](https://docs.digital.ai/agility-api/sdk/java/querying-asset-history-java-sdk): This topic explains how to query for asset history in Agility
- [Querying Configurations and Localizations](https://docs.digital.ai/agility-api/sdk/java/querying-configurations-and-localizations-java-sdk): This topic explains how to use Java SDK for query configurations and localization
- [Creating Assets with Java SDK](https://docs.digital.ai/agility-api/sdk/java/creating-assets-java-sdk): This topic explains how to create assets using Java SDK
- [Updating Assets using Java SDK](https://docs.digital.ai/agility-api/sdk/java/updating-assets-java-sdk): This topic explains how to update assets using Java SDK
- [Executing Operations using Java SDK](https://docs.digital.ai/agility-api/sdk/java/executing-operations-java-sdk): This topic explains how to execute operations against assets in Agility
- [Executing Pass-Through Queries Java SDK](https://docs.digital.ai/agility-api/sdk/java/executing-pass-through-queries-java-sdk): This topic explains how to execute pass through queries in Agility
- [Working with Attachments and Images with Java SDK](https://docs.digital.ai/agility-api/sdk/java/working-with-attachments-and-images-java-sdk): This topic explains how to work with attachments and images using Java SDK
- [.NET SDK Library](https://docs.digital.ai/agility-api/sdk/dotnet/dot-net-sdk): This topic explains how the .NET API is used to access Agility API
- [Creating a Connection DOTNET SDK](https://docs.digital.ai/agility-api/sdk/dotnet/creating-a-connection): This topic explains how to connect the Digital.ai Agility with .NET SDK
- [Querying Assets using Dot NET SDK](https://docs.digital.ai/agility-api/sdk/dotnet/querying-assets): This topic explains how to query for assets in Agility
- [Querying Asset History](https://docs.digital.ai/agility-api/sdk/dotnet/querying-asset-history): This topic explains how to query for asset history with optional parameter
- [Querying Configurations and Localizations with Dot NET SDK](https://docs.digital.ai/agility-api/sdk/dotnet/querying-configurations-and-localizations): This topic explains how to use .NET SDK for querying and configuration
- [Creating Assets using DotNET SDK](https://docs.digital.ai/agility-api/sdk/dotnet/creating-assets): This topic explains how to create new assets in DotNET SDK
- [Updating Asset using Dot NET SDK](https://docs.digital.ai/agility-api/sdk/dotnet/updating-assets): This topic explains how to update assets using the Dot NET SDK
- [Executing Operations](https://docs.digital.ai/agility-api/sdk/dotnet/executing-operations): This topic explains about executing operations in Agility
- [Executing Pass-Through Queries](https://docs.digital.ai/agility-api/sdk/dotnet/executing-pass-through-queries): This topic explains how to execute pass-through queries in Agility
- [Working with Attachments and Images using Dot NET SDK](https://docs.digital.ai/agility-api/sdk/dotnet/working-with-attachments-and-images): This topic explains how to work with attachments and images in Agility with Dot NET SDK

## Troubleshooting

- [Troubleshooting](https://docs.digital.ai/agility-api/troubleshooting): Diagnose Agility API problems by symptom — especially the ones that return a successful response while doing the wrong thing.

## Faq

- [FAQ - Frequently Asked Questions](https://docs.digital.ai/agility-api/faq): Short answers to the questions Agility API integrators actually ask