AgileZen API Documentation

Filters

Normally, when you make a request to a container resource, the response will be a paginated list of all items within that container. You can customize the items that are returned by specifying a filter with your request.

To specify a filter, supply a where parameter when making the request. For example, this request will retrieve all blocked stories in the project with id 1:

https://agilezen.com/api/v1/projects/1/stories?where=status:blocked

Filter Expressions

The syntax for filters in the API is the same as that used in the application itself. Filters are created using a language called filter expressions. Expressions consist of pairs of properties (like color) and values (like red) that you want to match. These pairs can be joined together using logical and and or statements, and negated using not statements.

Since each resource has different properties, each resource type has a different set of filters. The filters available for each resource type are defined on the individual resource pages.

Here are a couple examples of filters that work on story endpoints:

ExpressionMatches
color:greenAll green stories
priority:importantAll stories with the priority important

If the value you’re looking for is more than one word, you can use double quotes around the value, like text:"needs to be fixed".

Filtering on Multiple Properties

As we already mentioned, you can filter on more than one property by using and and or statements. You can also negate a pair using a not statement — this will match everything except what the filter describes.

Here are some examples of logical operations that work on stories:

ExpressionMatches
color:yellow and phase:workingAll yellow cards in the working phase
size:medium or priority:lowAll cards with the size medium or low priority
not(tag:homepage)All cards that don’t have the tag homepage

You can also use parentheses to group pairs together, like this (again, on stories):

ExpressionMatches
(color:red and text:"user interface") or (owner:nkohari and phase:design)All stories which are either red and contain the text “user interface”, or are owned by the user nkohari and are in the phase named design
(color:green or tag:feature) and not(color:teal and tag:defect)All stories which are green or have the tag feature, and also are not colored teal and have the tag defect