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:
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
or statements, and negated using
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:
|All green stories|
|All stories with the priority
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
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:
|All yellow cards in the working phase|
|All cards with the size medium or low priority|
|All cards that don’t have the tag homepage|
You can also use parentheses to group pairs together, like this (again, on stories):
|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|
|All stories which are green or have the tag feature, and also are not colored teal and have the tag defect|