API 2.0 GET usage and filters



The old navigation will be removed from Jira Align in early 2024.
Learn more about the upcoming changes

In this article, we will demonstrate the basic functionality of API 2.0. The primary focus will be using GET to query an API endpoint using cURL, as this serves as a starting point for leveraging the API for more complex queries and automation tasks.  In addition, because of the number of records that can be returned in a GET API call, 100 items is the maximum that can be returned in a single call. Thus when using the API, you must loop through batches of 100 to get all items.

A Note on Syntax

As every site and use case is different, the following examples will use place holders where the user must enter their own value. In all cases the "<" and ">" should be removed:

<key> - this is the field within the response we are looking for, for example, "title" in epics or "name" in cities would be a key. For more information on available keys, please review the schema definitions at the very end of the Swagger documentation (<yoursite>.jiraalign.com/rest/align/api/docs/index.html).

<value> - the user-defined value we are searching for. If we have a city with the name Houston, name is our key, as above, and the value of that key would be Houston. 

In the use cases to follow, we will show three examples:

  1. A plain text and easy-to-read example of the syntax
  2. A plain text example with the key and value entered
  3. A cURL ready example complete with encoding

For clarity, the examples will only show the endpoint and filter/command rather than the entire URL. For example, where we show something like:


The full command would look like:

curl -X GET 'https://<sitename>.agilecraft.com/rest/align/api/2/Epics?top=10' -H "Accept: application/json" -H 'Authorization: Bearer <your_API_token>'


How to cURL

cURL is a basic command-line tool available in most operating systems by default, although it may need to be installed separately on Windows. If in doubt, please contact your system admin. 

The use of cURL will also require the request URL to be encoded. Think of it as a website address you would enter in a browser--if you left spaces and apostrophes in the address, the browser would not be able to interpret the address and, depending on the browser, tell you the page was not found or send you to a Google search result.

What this means for us is a request to get epics where the title is 'API' would look like this:


A full list of characters and what they need to be encoded to can be found here, but these are the most commonly used:


Encode to


















Apostrophes and Quotation Marks

If you are using cURL and the command returns nothing or complains of a malformed JSON string (or any strange-looking errors) even though the command and API token looks correct, check your apostrophes (') and quotation marks (“). In most cases, the key and value for the filter will need to be enclosed in apostrophes, which then need to be encoded (%27). For long URLs, this can get a little confusing; if you are hitting an error, break it down into parts and make sure everything is where it should be and the encoding is correct.

The Authorization header should be enclosed in apostrophes (') to prevent the terminal interpretation of certain characters within the token itself.


Basic Filtering Examples

For these examples, we will use epics, but the same theory can be applied to any endpoint of the API. Not all endpoints use the same key/value pairing, so please refer to the schema definitions.


Equal to (eq)

Return all epics where the title is 'API Epic'


/Epics?$filter=<key> eq '<value>'

Plain example

/Epics?$filter=title eq 'API Epic'

cURL encoded example


Not equal (ne)

Return all epics where the title is not equal to 'API Epic'


/Epics?$filter=<key> ne '<value>'

Plain example

/Epics?$filter=title ne 'API Epic'

cURL encoded example


Greater than (gt)

Return all epics where the ID is greater than 2193

NOTE: Integers do not require apostrophe (') enclosure


/Epics?$filter=<key> gt <value>

Plain example

/Epics?$filter=id gt 2193

cURL encoded example


Less than (lt)

Return all epics where the ID is less than 10


/Epics?$filter=<key> lt <value>

Plain example

/Epics?$filter=id lt 10

cURL encoded example


Greater than, equal to (ge)

Return all epics where the ID is greater than or equal to 2193


/Epics?$filter=<key> ge <value>

Plain example

/Epics?$filter=id ge 2193

cURL encoded example



Less than, equal to (le)

Return all epics where the ID is less than or equal to 2193


/Epics?$filter=<key> le <value>

Plain example

/Epics?$filter=id le 2193

cURL encoded example




Return all epics where the title contains API



Plain example


cURL encoded example



Starts With

Return all epics where the title starts with AP



Plain example


cURL encoded example


Basic Pagination

The top and skip commands can be chained together to offer proper pagination (covered later in this article). Default order by is on ID, so the first 10 epics would mean IDs 1 - 10.


Return the first 10 Epics



cURL example



Skip the first 521 epics and return all after



cURL example


Selecting Fields to Display


Return all epics but only display their title and ID



cURL example



Filtering by Date

The Date field takes the following format:
"createDate" : "2020-05-11T05:03:25Z"

NOTE: Trying to eq to match the time will not work here. You can only gt, lt, ge & le on the date itself. Additionally, you do not need to encode the hyphens and colons in the Date/Time field.

For example, return all epics created on or after May 11 2020

/Epics?$filter=createDate ge 2020-05-11T06:48:00Z

Will return the same results as


Filter Chaining

By chaining, we mean stringing filters together to get more useful results. To do so, take the above basic filters and place them either side of an ampersand (&).

Get all items with an ID greater than X, ordered by descending Y

Return all epics with an ID greater than or equal to 2193, and order the results by descending ID (default is ascending)


/Epics?$filter=<key> gt '<value>' & $orderby=<key> desc

Plain example

/Epics?$filter=id gt 2193 &$orderby=id desc

cURL encoded example


Get the first 10 epics with the word ‘API’ in the title and display only the epic title, description, and owner


/Epics?$filter=contains(<key_1>,'<value_1>') &$top=<value_2> &$select=<key_2>,<key_3>,<key_4>


key_1 = the field we are searching for

value_1 = the thing we are searching key_1 for

value_2 = the amount of results to display

<key_[2|3|4]> = the fields we want to return

Plain example


cURL encoded example



Using And/Or 

We can also use and/or statements for boolean operations.

Return Cities named Houston or London


/Citites?$filter=name eq '<value_1>' or name eq '<value_2>'

Plain example

/Cities?$filter=name eq 'Houston' or name eq 'London'

cURL encoded example



Adding a Filter to an And/Or Request

Take out chaining with ampersands and add it onto our and/or statement:

Return all cities where the name contains ‘ton’ but is not Houston and display only the name


/Cities?$filter=contains(<key>,'value_1>') and <key> ne '<value>' &$select=<key>

Plain example

/Cities?$filter=contains(name,'ton') and name ne 'Houston' &$select=name

cURL encoded example



Was this article helpful?
3 out of 3 found this helpful
Print Friendly Version of this pagePrint Get a PDF version of this webpagePDF

Join the Atlassian Community!

The Atlassian Community is a unique, highly collaborative space where customers and Atlassians come together. Ask questions and get answers, start discussions, and collaborate with thousands of other Jira Align customers. Visit the Jira Align Community Collection today.

Need to contact Jira Align Support? Please open a support request.