Skip to main content
System StatusContact Support Agility Community

Getting Started with the API

This feature is available in all editions.



The API facilitates integration with external systems and allows direct queries to the Lifecycle data. This list contains some pointers for those getting started with the API.

Common Assets & Translations

The API uses the database name of each asset. Here are a few common assets that are helpful to know when you create your queries:

API Name Application UI Name
Scope Project
Timebox Iteration or Sprint
Story Story, Backlog Item, or Requirement
Actual Effort or Done

Know that you can always query the localization API to determine if an API name has a translated UI name in your system. Because the UI labels can be customized, the application UI name in your own system can differ from the common set above.

List of Assets and Attributes

Query the meta API to get a list of all the assets in the system as well as the attributes and relations of each. Use the following query to apply xsl which formats the list for easier viewing.

<Server Base URI>/meta.v1?xsl=api.xsl

Replace the <v1-server> and <v1-app-name> tags in the above with your specific system information.

Alternatively, you could get all the attributes and relations of a single asset by adding that asset name to the query, for example:

<Server Base URI>/meta.v1/Story?xsl=api.xsl

Asset States

AssetState is used to define the system-known lifecycle for an asset. The UI, for example, will typically query assets that are not = 'Dead' to automatically exclude those items from the return results.

0 => Future
64 => Active
128 => Closed
200 => Template (Dead)
208 => Broken Down (Dead)
255 => Deleted (Dead)

Formatting Output

Use xsl to format the output of API queries. A couple of xsl files have been created to format output in popular ways.

  • Table View (table.xsl)- see results as an easily-readable report with values in columns
  • Story Card View (storyCards.xsl ) - format and print out story cards from your backlog
  • Epic Card View (epicCards.xsl) - Format and print out epic cards with ID, Name, Owner, and Team

If you want these loaded to your hosted instance, please send an email to and make sure to mention your instance URL and which XSL you want loaded. We will install them in the /custom folder.

This is Open source/Community supported and not supported by 

On-Premises (local) installations

Right-click the links below to download and save the files locally:

To use them in your system, you will need to install the xsl files in a /custom directory on your web server under the VersionOne application. However, to actually access the cards and use the storycards, you need to run a query similar to this: 

<Server Base URI>/rest-1.v1/Data/Story?Where=Scope.Name="ProjectName"&xsl=custom/storyCards.xsl

Make sure there is no slash in front of "custom". To make changes to the storycards xsl file, you will need to have a bit of API knowledge. If you require assistance, please contact Support and discuss a Services engagement for assistance.

On-Demand (Hosted) customers

To request these .xsl files, contact VersionOne Support.

For example, to turn this API query:

<Server Base URI>/rest-1.v1/Data/Story?select=Name,Description

...on a hosted system into one that outputs the contents in tabular format, you can specify using the table.xsl by referencing it's location in /custom/table.xsl like so:

<Server Base URI>/rest-1.v1/Data/Story?select=Name,Description&xsl=custom/table.xsl


Additional Help for REST API Queries

There is built in API specific Help available on your instance. 

<Server Base URI>/help/api/rest-1.html

This Help feature shows examples of code and queries and syntax that should assist you in getting your own API code up and running.