Limiting items returned from GET resources

To limit the information returned from the when using GET resources, you can use the search or fields parameters in the request URL.

You can also use a query to return items using a POST /{projectID}/{itemType}search request. The search parameters are provided in the JSON body instead of the URL.

fields parameter

The fields parameter limits the fields returned for each item. The following example request only returns Summary and Status field information for issues in the project.

GET /helix-alm/api/v0/4/issues?fields=Summary,Status

search parameter

The search parameter only returns items that meet specified criteria. The following example request only returns issues in the project with the Cosmetic value in the Type field and Immediate value in the Priority field:

GET /helix-alm/api/v0/4/issues?search=Type=Cosmetic and Priority=Immediate

Field names that contain commas are not supported as URL parameter values. To use field names with commas, use POST /{projectID}/[itemType}/search instead because commas are supported in JSON.

Query syntax

The syntax for a query is:

<FieldName> <OptionalNegationOperator> <Operator> <Value>

For example:

Priority = "High"

Priority EQUALS "High"

Priority NOT EQUALS "High"

Logical operators

Operator	Example
AND	`Status = 'Open' and Priority ="High"`
OR	`Status = 'Open' OR Priority = 'High'`
NOT	`NOT (Status = 'Open)`

Comparison operators

Operator	Alternate operator	Example	Additional info
EQUALS	=	`Priority = 'High'`	Applies to any field type.
NOT EQUALS	!=	`Priority != 'High'`	NOT EQUALS string is combination of logical NOT and operator EQUALS. != is a single operator.
GREATER	>	`Hours > 20.0`	Applies only to numeric, hours, date, date/time fields.
GREATER_EQUAL	>=	`Hours GREATER_EQUAL 20.0`	Applies only to numeric, hours, date, date/time fields. >= is a single operator.
LESS	<	`Hours < 20.0`	Applies only to numeric, hours, date, date/time fields.
LESS_EQUAL	<=	`Hours <= 20.0`	Applies only to numeric, hours, date, date/time fields. <= is a single operator.
IN	:	`Priority in ('low', 'medium')`	Applies only to list, folder, and number fields.
		`Folders in ('Folder1', 'Folder2')`	Not a recursive comparison for folders.
		`Number in (42, 43, 44)`	Example is same as Number = 42, or Number = 43, or Number = 44.
IN_RECURSE	:?	`Folders :? ('Folder1', 'Folder2')`	Performs a recursive comparison for folders. Applies only to folder fields. :? is a single operator.
CONTAINS	~	`Summary CONTAINS 'some text'`	Applies only to text fields. Case-insensitive phrase comparison.
CONTAINS	~	`Summary ~ ('some', 'text')`	Matches any search term. Case insensitive.
CONTAINS_CASE	^	`Summary ^ 'Some Text'`	Applies only to text fields.
CONTAINS_CASE	^	`Summary CONTAINS_CASE "Test"`

Special field value constants

Constant	Example	Valid for field type
NOT_SET	`Version = NOT_SET`	Drop down
TRUE	`Has%20Attachments = TRUE`	Boolean
FALSE	`Has%20Attachments = FALSE`	Boolean

Valid URL query characters

A URL query can contain alphanumeric and percent-encoded characters. A query can also include the following unencoded characters. All other characters must be escaped with a percent signs (%value%).

/ ? : @ - . _ ~ ! $ & ' ( ) * + , ; =

For example, search=Field1='Test&Test' must be encoded as 'search=Field1=‘Test%26Test'.