---
id: intro
slug: /
title: 'Digital.ai Agility API Documentation'
description: 'Developer reference for the Digital.ai Agility API: endpoints, query syntax, and the behaviour you can rely on.'
sidebar_label: 'Introduction'
sidebar_position: 1
tags: ['overview', '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](https://docs.digital.ai/agility/).

## 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

## Quick Links

| Start here | What it covers |
| --- | --- |
| 🚀 [Getting started](/getting-started/quickstart) | Make your first authenticated API call. |
| 🧭 [Choosing an API](/getting-started/choosing-an-api) | Decide between `query.v1`, `rest-1.v1`, `api/asset` and `meta.v1`. |
| 🔐 [Authentication](/getting-started/authentication) | Access tokens, Basic authentication and the headers every request needs. |
| 📖 [API reference](/apis) | Request and response detail for every Agility API surface. |
| 💡 [Examples](/examples) | Working code in cURL, Python and TypeScript. |

## The Main API Surfaces

:::tip[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](./apis/conventions/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 →](/apis/asset-bulk)

### 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 →](/apis/query-v1)

### 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 →](/apis/meta-v1)

### 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 →](/apis/rest-1)

Beyond these four, the [API reference](/apis) 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:

- **[Assets, asset states and OIDs](/concepts/assets)** — work items, their lifecycle, and how assets are identified
- **[Attributes](/concepts/attributes)** and **[relations](/concepts/relations)** — properties and the links between assets
- **[Operations](/concepts/operations)** — actions that can be performed on assets
- **[Scopes and projects](/concepts/scope-projects)** — how work is organized
- **[Workflows and status](/concepts/workflows)** — moving items through your process

## 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](/guides/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](/guides/error-handling)** — implement retry logic for
  transient failures.

## Need Help?

- **[FAQ](/faq)** — answers to frequently asked questions
- **[Troubleshooting](/troubleshooting)** — common issues and solutions
- **[API Console](https://docs.digital.ai/agility/docs/developerlibrary/exercise-1-basic-use-of-the-api-console)** — interactive API explorer built into Agility
- **[Community forums](https://community.digital.ai/)** — ask questions and share knowledge
- **[Support](https://support.digital.ai/hc/en-us)** — contact the Digital.ai support team

To learn what this site covers and how its content is verified, see
[About this documentation](/reference/sources).

---

Ready to get started? Head to the [getting started guide](/getting-started/quickstart) to
make your first API call.