---
id: quickstart
title: 'Getting Started with the Agility API'
description: 'Learn how to authenticate and make your first API calls to Digital.ai Agility'
sidebar_label: 'Quickstart'
sidebar_position: 1
tags: ['getting-started', 'authentication', 'api', 'quickstart']
---

The Agility API gives programmatic access to Agility's asset model, enabling you to integrate with external systems, automate workflows, and build custom tools.

## Overview

The Agility API lets you:

- Query assets (Stories, Defects, Tasks, Tests, etc.)
- Create and update assets
- Execute operations (status changes, assignments)
- Discover metadata about your Agility instance
- Perform bulk operations for large-scale changes

## Quick Start

### 1. Get Your API Credentials

Before you can make API calls, you need an access token:

1. Log into your Agility instance
2. Open the member menu (your avatar) and choose **Applications**
3. Add a personal application: give it a name and apply — the access token is
   displayed **once**, at creation
4. Copy the token and store it securely

**Important**: Treat your access token like a password. Never commit it to source control.

:::note
An administrator can disable access tokens for an instance. If the
Applications page will not issue one, ask your administrator — see
[Authentication](/getting-started/authentication) for the full picture.
:::

### 2. Set up Your Environment

Create environment variables for your credentials:

```bash
# Your Agility instance URL (no trailing slash)
export AGILITY_BASE_URL="https://www7.v1host.com/YourInstance"

# Your personal access token
export AGILITY_ACCESS_TOKEN="your-token-here"
```

### 3. Test Your Connection

Ask the instance who you are:

```bash
curl "${AGILITY_BASE_URL}/rest-1.v1/Data/Member?where=IsSelf='true'&sel=Name&page=1,0" \
  -H "Authorization: Bearer ${AGILITY_ACCESS_TOKEN}" \
  -H "Accept: application/json"
```

A `200` with your own Member record proves the token works; a bad token is a
`401`. Don't test with [`meta.v1`](/apis/meta-v1) or `config.v1` — both answer
**anonymously**, so they return `200` whether your token is valid or not, and a
broken credential then surfaces later as a confusing failure on your first real
call.

## Common Asset Types

Agility uses internal names for assets that may differ from the UI labels. Here are the most common ones:

| API Name  | Common UI Name                   |
| --------- | -------------------------------- |
| `Story`   | Story, Backlog Item, Requirement |
| `Defect`  | Defect, Bug                      |
| `Task`    | Task                             |
| `Test`    | Test                             |
| `Scope`   | Project                          |
| `Timebox` | Iteration, Sprint                |
| `Epic`    | Portfolio Item                   |
| `Theme`   | Backlog Group                    |
| `Member`  | Team Member                      |

:::tip
Your Agility instance may have customized labels. Use the Meta API to see exactly what's available in your environment.
:::

## Your First Query

Let's query for a story by its number:

```json
{
  "from": "Story",
  "select": ["Number", "Name", "Status.Name", "Scope.Name", "Owners.Name"],
  "where": {
    "Number": "S-01234"
  }
}
```

Save this as `query.json` and execute:

```bash
curl "${AGILITY_BASE_URL}/query.v1" \
  -H "Authorization: Bearer ${AGILITY_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @query.json
```

## Understanding Asset States

Assets in Agility have states that control their visibility:

| State       | Value | Description                                            |
| ----------- | ----- | ------------------------------------------------------ |
| Future      | 0     | Not yet active                                         |
| Active      | 64    | Currently active                                       |
| Closed      | 128   | Closed — also called **Inactive** for many asset types |
| Template    | 200   | Workitem template (dead)                               |
| Broken Down | 208   | Legacy: story broken into children (dead)              |
| Deleted     | 255   | Deleted — still stored, and recoverable until purged   |

States of 192 and above are "dead": the UI excludes them by default, and API
queries can do the same by filtering on `AssetState`. Two things trip people
up:

- **"Closed" and "Inactive" are the same state (128).** Which word you see
  depends on the asset type — workitems close, while lists, projects and
  members are inactivated.
- **Deleted assets are not gone.** They remain queryable — see
  [troubleshooting](/troubleshooting) for how to include them — and can be
  recovered until an administrator purges them.

## Key Endpoints

| Endpoint          | Purpose                                       | Authentication Required |
| ----------------- | --------------------------------------------- | ----------------------- |
| `/meta.v1`        | Discover asset types, attributes, relations   | No\*                    |
| `/query.v1`       | Query assets with filters and projections     | Yes                     |
| `/rest-1.v1/Data` | Query, create and update current assets       | Yes                     |
| `/rest-1.v1/Hist` | Read historical versions of assets            | Yes                     |
| `/rest-1.v1/New`  | Get templates for new assets                  | Yes                     |
| `/api/asset`      | Query, create, update and execute in bulk     | Yes                     |

\*`meta.v1` is anonymous by design — the schema is not instance data. An
on-premise installation that puts its own authentication in front of the whole
site (for example at the web-server level) can still gate it.

## Required Headers

Always include these headers when making API calls:

```http
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json
```

## Next Steps

Now that you have a working connection:

1. **[Explore the Meta API](/apis/meta-v1)** - Discover what's available in your instance
2. **[Learn Query Syntax](/apis/query-v1)** - Build powerful queries with filters and sorting
3. **[Authentication Guide](/getting-started/authentication)** - Understand security best practices
4. **[Code Examples](/examples/curl)** - See examples in cURL, Python, and TypeScript

## Common Pitfalls

- **Mixed authentication modes**: Don't send both basic auth and bearer token
- **XML vs JSON**: Always specify `Accept: application/json` to avoid XML responses
- **Asset state confusion**: Remember that deleted assets still exist with state=255
- **Case sensitivity**: Attribute names are case-sensitive

## Getting Help

- **API reference**: [REST API](/apis/rest-1), [Query API](/apis/query-v1) and the
  [query grammar](/reference/query-grammar) on this site
- **Troubleshooting**: [diagnose by symptom](/troubleshooting) — most Agility traps return a
  successful response with the wrong data
- **Community**: Visit [Digital.ai Community](https://community.digital.ai/) for discussions
- **Support**: Contact [Digital.ai Support](https://support.digital.ai/hc/en-us) for technical issues

## Additional Resources

- [REST API Tutorial](https://docs.digital.ai/agility/docs/developerlibrary/version-one-rest-api-tutorial) - Step-by-step exercises
- [API Endpoints Reference](https://docs.digital.ai/agility/docs/developerlibrary/endpoints) - Complete endpoint list
- [Sample Code](https://docs.digital.ai/agility/docs/sample-code) - Official code samples