Getting Started with the Agility API

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 for the full picture.

2. Set up Your Environment

Create environment variables for your credentials:

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

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

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

Save this as query.json and execute:

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

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 - Discover what's available in your instance
2. Learn Query Syntax - Build powerful queries with filters and sorting
3. Authentication Guide - Understand security best practices
4. Code Examples - 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, Query API and the query grammar on this site
• Troubleshooting: diagnose by symptom — most Agility traps return a successful response with the wrong data
• Community: Visit Digital.ai Community for discussions
• Support: Contact Digital.ai Support for technical issues

Additional Resources

• REST API Tutorial - Step-by-step exercises
• API Endpoints Reference - Complete endpoint list
• Sample Code - Official code samples