This topic describes the API operation you can use to perform advanced search in Zephyr Enterprise. To get started with Zephyr Enterprise REST API, see Zephyr Enterprise REST API Documentation.

Use the following operation to search for items in Zephyr Enterprise by using a filter:

GET /flex/services/rest/latest/advancesearch?word=&entitytype=&releaseid=&zql=&isascorder=&order=&firstresult=&maxresults=&is_cfield=&isOld=

Request format

To search for items, send a GET request to the following URL:

Panel

panelIconId	atlassian-info
panelIcon	:info:
bgColor	#FFBDAD

Starting October 11, 2024 (Zephyr Enterprise 8.2), the Zephyr Enterprise documentation moved from its current location on Atlassian to a dedicated, standalone Zephyr Enterprise documentation page. Please see: https://support.smartbear.com/zephyr-enterprise/docs/en/zephyr-enterprise/zephyr-rest-api/search-api.html

You can use Zephyr Enterprise REST API to search for test cases, requirements, and executions programmatically.

Request URL

Code Block

language	text

GET http(s)://{ZEPHYR-SERVER}/flex/services/rest/latest/advancesearch?
      word=<text>
      &entitytype=<entitytype>
      &releaseid=<id>
      &zql=

...

false
      &isascorder=true
      &order=<fieldname>
      &firstresult=0
      &maxresults=100
      &is_cfield=

...

false

Parameters

...

Value

...

Value type

Authentication

You can authenticate your requests by using one of the methods described in the Zephyr REST API topic.

Request parameters

Value	Type	Description
word (required)	string	A string to search for.

entitytype

string

The type of the entity to search for.

releaseid

long

The ID of the release the entity belongs to.

zql

Boolean

Specifies whether ZQL is used.

isascorder

Boolean

Switches the ascending order.

order

string

The column order. For example, the parameter value can be orderId.

firstresult

int

The starting point of the record.

maxresults

int

The number of records to be fetched.

is_cfield

Boolean

Custom field order.

isOld

Boolean

Specifies whether the test case is old.

Sample request

Code Block
{ "entityType": "testcase", "isZql": true, "releaseId": 1 }

Sample response

...

language	json

...

You can specify some text or a ZQL query (in the latter case, you will have to specify `zql=true` in the request URL). For example: Text: `any text` ZQL query: `creator="test.manager" and priority="P1"`
entitytype (required)	string	The type of the entity to search for. Possible values: `requirement` `testcase` `execution`
releaseid (required)	long	The ID of the release the entity belongs to. To see the release ID in Zephyr, click Manage Release in the top-right corner and take a look at the value of the ID column in the subsequent window: Image Added
zql (required)	boolean	Specifies whether ZQL is used. `false` by default. Set it to `true` if the `word` parameter contains a ZQL query.
isascorder (optional)	boolean	Switches the ascending order. Specify `true` to sort the results in the ascending order or `false` to sort them in the descending order. By default, it is `true`.
order (optional)	string	The field to sort data by (this can be either a standard or a custom field). For example: `testcaseId`, `automated`, `priority`, `creatorId`, `orderId` and so on. Click here to refer to the Supported fields list. The default parameter value is `orderId`. If you specify a custom field, you will also have to set the `is_cfield` parameter to `true` (see below).
firstresult (required)	integer	The first element of the retrieved results. The parameter is zero-based, which means you need to specify `0` as the start position to begin with the first element.
maxresults (required)	integer	The number of records to be fetched. The maximum number is 100.
is_cfield (optional)	boolean	If the `order` parameter specifies a custom field, set `is_cfield` to `true`. By default, it is `false`.

You can specify the first element of the retrieved results and the number of items to show by using the firstresult and maxresults query parameters respectively. The firstresult parameter is zero-based, which means you need to specify 0 as the start position to begin with the first element. The sample request below will show a list of results starting from the first element, and the maximum number of retrieved items will be 100:

GET /flex/services/rest/latest/advancesearch?word=test&entitytype=testcase&releaseid=1&zql=false&firstresult=0&maxresults=100

Sample requests

ZQL is not used:

GET /flex/services/rest/latest/advancesearch?word=test&entitytype=testcase&releaseid=1&zql=false&firstresult=0&maxresults=100

ZQL is used:

GET /flex/services/rest/latest/advancesearch?word=creator="test.manager" and priority="P1"&entitytype=testcase&releaseid=1&zql=true&firstresult=0&maxresults=100

Sample response

On success, the operation returns status code 200 and a JSON object containing metadata and found results. The structure of these results varies depending on the sought-for entities, items and so on. Below is a sample response obtained when searching for an execution:

Code Block

language	json

[
   {
      "firstResult": 0,
      "tcrCatalogTreeIdresultSize":30 1,
      "results": [
         "revision":9,
  {
            "stateFlagid":0 147,     ----------------------------------- The RTS ID (the execution ID)
     "lastModifiedOn":1600168120466,
         "assignmentDate": "2020-09-15",
            "versionNumberactualTime":1 600,
             "versionId":  "createDatetime1":1600168114777,
 
             "createdByIdcomment":5, "This is a comment",
            "modifiedByIdtesterId": 5,
               "testcase":{
  "executedBy": 5,
               "customPropertiestcrTreeTestcase":{
                  },
 {
                 "customProcessedPropertiesid":{                   },
                  "id":165, ------308,  ----------------------------------- The testTCR Catalog caseTree versionTestCase ID (tctid)
                 "nametcrCatalogTreeId":"edited 159 testcase edit",
   30,
               "descriptionrevision":"" 9,
 
                "lastModifiedOnstateFlag":1600169396082 0,

                 "creationDatelastModifiedOn":1600128000000 1600168120466,
                  "createDatetimeversionNumber":1600168102437 1,
               "createDatetime": 1600168114777,
 "tcCreationDate":"09/15/2020",
                  "commentscreatedById":"",
   5,
               "isComplexmodifiedById":false 5,
  
               "estimatedTimetestcase":600, {
                  "writerIdcustomProperties":0, {
                  "creatorId":5},
                  "lastUpdaterIdcustomProcessedProperties":5, {
                  "oldId":0},
                  "automatedid":false,
      165, ----------------------------------- The test case version ID
            "customFieldProcessed":false,      "name": "edited 159 testcase edit",
                  "customFieldValuesdescription":[ "",
                  "lastModifiedOn": 1600169396082,
                  "creationDate": ]1600128000000,
                  "testcaseSequencecreateDatetime":{   1600168102437,
                  "seqNumbertcCreationDate":159
 "09/15/2020",
                 } "comments": "",
                  "testcaseIdisComplex":159, ----------------------------------- The test case ID false,
                      "versionNumber":1"estimatedTime": 600,
                  "projectIdwriterId":3 0,
                  "testcaseTypecreatorId":"ORIGINAL" 5,
                  "requirementIdslastUpdaterId":[ 5,
                  "oldId": 0,
                  "automated": ]false,
                  "projectNamecustomFieldProcessed":"P1" false,
                  "requirementIdsNewcustomFieldValues": [
                     
                  ],
                  "creatorNametestcaseSequence":"divya divya",{
                     "lastModifierNameseqNumber":"divya divya",159
                  "automatedDefault":false},
                  "testcaseSharedtestcaseId":false
               },
               "projectId":3, 159, ----------------------------------- The test case ID
                  "releaseIdversionNumber":5 1,
                  "isDerivedFromBDDprojectId":false 3,
                  "orderIdtestcaseType":453, "ORIGINAL",
                  "maxVersionNumberrequirementIds":1, [
                 "projectIdParam":3,    
           "original":false       ],
     },             "cyclePhaseIdprojectName":7, "P1",
                  "lastTestResultrequirementIdsNew":{ [
               "id":58,      
         "executionDate":1600169404251,         ],
                  "execDatecreatorName":"09/15/2020 "John Smith",
                  "executionStatuslastModifierName": "4John Smith",
                  "testerIdautomatedDefault":5 false,
                  "releaseTestScheduleIdtestcaseShared":147, false
               "createDatetime":1600169404253},
               "modifiedDatetimeprojectId":1600169404250 3,
               "createdByIdreleaseId": 5,
               "modifiedByIdisDerivedFromBDD":5 false,
           },    "orderId": 453,
       "defects":[        "maxVersionNumber": 1,
               "projectIdParam": 3,
  ],             "attachmentCountoriginal":0, false
           "lastModifiedBy":5,
 },
            "cyclePhaseId": 7,
            "lastTestResult": {
               "createdById":5,
            "lastModifiedOn":1600169404255,
            "createDatetime":1600168120467
         }
      ],
      "type":"testSchedule"
   }
]

Response codes

...

HTTP Status Code

...

Description

...

200

...

The request completed successfully.

...

400

...

Bad request. At least one releaseid or departmentid parameter is required.

...

401

...

The authentication token is missing.

...

403

...

The user has no permissions to perform this operation.

...

500

...

id": 58,
               "executionDate": 1600169404251,
               "execDate": "09/15/2020",
               "executionStatus": "4",
               "testerId": 5,
               "releaseTestScheduleId": 147,
               "createDatetime": 1600169404253,
               "modifiedDatetime": 1600169404250,
               "createdById": 5,
               "modifiedById": 5
            },
            "defects": [
               
            ],
            "attachmentCount": 0,
            "lastModifiedBy": 5,
            "createdById": 5,
            "lastModifiedOn": 1600169404255,
            "createDatetime": 1600168120467
         }
      ],
      "type": "testSchedule"
   }
]

If no items matching the specified criteria are found, an empty results array is returned:

Code Block
[ { "firstResult": 0, "resultSize": 0, "results": [], "type": "testcase" } ]

Response Codes

HTTP Status Code	Description
200	The request completed successfully.
400	Bad request.
401	The authentication token is missing.
403	The user has no permissions to perform this operation.
500	Unknown internal error.

Anchor
List-of-Supported-Fields
List-of-Supported-Fields
List of Supported Fields

Expand

title	Supported Fields for TestCase:

testcaseId
estimatedTime
creator
orderId
release
creatorId
project
priority
version
altId
revision
execDate
treeid
automated
versionId
parenttreeid
folder
contents
releaseid
name
comment
id
tag
projectid

Expand

title	Supported fields for Requirement:

creator
release
creatorId
project
priority
altId
url
requirementTree
releaseid
name
details
id
projectid
requirementTreeId

Expand

title	Supported fields for Execution:

testcaseId
notes
orderId
executorid
release
creatorId
project
cycle
assigneeid
treeid
cyclephaseid
id
tag
projectid
estimatedTime
executedBy
actualtime
creator
cycleid
priority
version
altId
revision
execDate
automated
versionId
parenttreeid
folder
contents
releaseid
name
comment
assignee
cyclephase
scheduleid
status

Version	Old Version 1	New Version Current
Changes made by	Edward Stolyar (Deactivated)	Dominik Trygar
Saved on	Feb 02, 2021	Oct 10, 2024

Versions Compared

Key

Request URL

Parameters

Authentication

Request parameters

Sample request

Sample response

Sample requests

ZQL is not used:

ZQL is used:

Sample response

Response codes

Response Codes

Anchor
List-of-Supported-Fields
List-of-Supported-Fields
List of Supported Fields

Page Comparison

Versions Compared

Key

Request URL

Parameters

Authentication

Request parameters

Sample request

Sample response

Pagination

Sample requests

ZQL is not used:

ZQL is used:

Sample response

Response codes

Response Codes

AnchorList-of-Supported-FieldsList-of-Supported-FieldsList of Supported Fields

Anchor
List-of-Supported-Fields
List-of-Supported-Fields
List of Supported Fields