Query string parameters can be used to filter down a result set and generally format API responses.
In general, most complex querying & formatting is difficult to cache and therefor a burden on both client bandwidth and server processing. For this reason, we encourage biasing your decisions in favor of avoiding these features where possible. As we begin to enforce rate limiting in the future, you may find that complex queries & formatting requests count against your limit in a way that more basic requests do not.
?limit (integer): Limit the number of results returned on a GET
query. The default limit is 20, and can be overridden up to 100.
?page (integer): Specify the page number for results returned on a GET
query. The default page number is 1.
?sort (string): Specify an API attribute to sort results by when performing a
GET query. Optionally, an array of attributes to sort by can be defined like so:
?sort[]=attribute1&sort[]=attribute2. By default, all result sets are sorted by a
resource's primary ID.
?direction (string): Specify a direction to sort results by: asc
or desc. This direction should corresponding to the attribute name provided in
sort and can also take the form of an array. By default, all result sets are
sorted ascending.
Operators may be used when performing a GET query, providing an ample amount of
search & filtering capability. Equals prefixes represent an exact match;
contains, starts-with, and ends-with prefixes represent
partial match searches.
?attribute=value: attribute
equals value?not-attribute=value: attribute
does not equal value?contains-attribute=value: attribute
contains value?not-contains-attribute=value: attribute
does not contain value?starts-with-attribute=value: attribute
starts with value?ends-with-attribute=value: attribute
ends with value?min-attribute=5: attribute
is at least 5?max-attribute=10: attribute
is no more than 10Multiple conditions are assumed to be joined by AND. For example:
?attribute1=1&attribute2=999 is the equivalent of asking the API
to give you all results where attribute1 equals 1 AND
attribute2 equals 999. There is currently no way to
create OR conditions across attributes when querying the API dynamically.
Within one attribute, multiple values can be separated by a pipe to create OR conditions.
For example: ?attribute1=1|2 is the equivalent of asking the API
to give you all results where attribute1 equals 1 OR 2.
Combining these concepts, you can pass a query such as ?attribute1=1|2&attribute2=999 to
ask the API for all results where (attribute1 equals 1 OR
2) AND (attribute2 equals 999).
?attributes can be used to limit the attributes returned in a GET request, usually to help save network bandwidth and/or simplify caching. For example:
?attributes=first,second will ensure that only the attributes named first and second, respectively, are returned in the result set.
?related allows for querying resources which are related to the current GET request. For example: ?related=RelatedResource will join in the RelatedResource object. It is strongly encouraged to avoid using this option unless absolutely necessary. It is not easy to cache and is therefore a burden on both bandwidth and processing. If you need to make multiple requests, this parameter is useful for reducing the number of requests and saving overall request time. To see the available relations on a resource, you can look at the implementation notes for a GET request of that resource in the Resources section. For example, the relations for a workspace are listed here.
By default, all user-centric datetimes are output in UTC. It is possible to ask the
API for these datetimes in the timezone of the current user. To do so, specify a ?timezone
with either a numerical offset or a string value from the
Olson database. For example:
?timezone=America/New_York. To use datetimes in the timezone of the current authenticated
you would use: ?timezone=user.