Skip to main content

Digital.ai Agility API Documentation

This site is the developer reference for the Digital.ai Agility API: the endpoints, the query syntax they share, and the behavior you can rely on when building an integration.

For Agility features, concepts, and other product help, see the Digital.ai Agility Documentation.

What Is the Agility API?​

The Agility API gives programmatic access to the Agility asset model over HTTP. Use it to:

  • Query data — retrieve stories, defects, tasks and other assets
  • Manage assets — create and update work items
  • Automate workflows — change statuses, assign owners, move items
  • Discover metadata — learn about asset types and available attributes
  • Perform bulk operations — query, create, update and invoke operations in a single request
Start hereWhat it covers
🚀 Getting startedMake your first authenticated API call.
🧭 Choosing an APIDecide between query.v1, rest-1.v1, api/asset and meta.v1.
🔐 AuthenticationAccess tokens, Basic authentication and the headers every request needs.
📖 API referenceRequest and response detail for every Agility API surface.
💡 ExamplesWorking code in cURL, Python and TypeScript.

The Main API Surfaces​

Add your instance URL and copy working requests

Code examples throughout this site use ~/ as a placeholder for your Agility instance base URL. Enter your base URL in the field at the top of any page and every ~/ on the page becomes your actual URL, so you can copy a request and run it as-is. Your instance URL stays in your browser's local storage and is never sent anywhere. For more information, see Base URL.

Bulk API (api/asset)​

Query, create, update and invoke operations on many assets in a single request. The most capable single endpoint: it is the only one that mixes reads, writes and operations in one call.

Use cases: mass imports, bulk status changes, data migrations, one-shot read-modify-write

Learn more about the Bulk API →

Query API (query.v1)​

Read assets with flexible filtering, sorting and paging. Perfect for retrieving stories, defects and other work items.

Use cases: story lookups, status reports, filtered queries

Learn more about the Query API →

Meta API (meta.v1)​

Discover the asset types, attributes, relationships and operations available in your Agility instance.

Use cases: dynamic form generation, validation, attribute discovery

Learn more about the Meta API →

REST API (rest-1.v1)​

A family of three namespaces sharing one URL shape: /rest-1.v1/Data for current data, /rest-1.v1/Hist for historical versions, and /rest-1.v1/New for a defaulted template for a new asset. Create and update individual assets, and send operations to change status, assign owners, and more.

Use cases: creating stories, updating status, assigning work, reading audit history

Learn more about the REST API →

Beyond these four, the API reference covers the full surface: attachments and images, localization, field visibility, the activity stream, rooms, and more.

Core Concepts​

Understanding these concepts will help you work effectively with the API:

Best Practices​

  • Always page list queries. Agility has no default page size — an unpaged query returns the entire result set. See query size and performance.
  • Select only the attributes you need. An explicit selection keeps payloads small and your integration stable as the schema evolves.
  • Prefer access tokens over username/password, and never commit them to source control.
  • Request JSON with an Accept: application/json header where the surface supports it.
  • Check the Meta API to validate that attributes exist before using them.
  • Handle errors gracefully — implement retry logic for transient failures.

Need Help?​

To learn what this site covers and how its content is verified, see About this documentation.

Ready to get started? Head to the getting started guide to make your first API call.