The Xray REST API provides the following endpoints for managing the Test Repository information of a given project.

Some endpoints support pagination, using the page and limit query parameters.

Hierarchy

To obtain a list of all Test Repository folders of a given project, including their hierarchy information, you need to specify the key of the respective project.

Returns a JSON object with a list of the folders of the Test Repository.

Request

PATH PARAMETERS

parameter	type	description
`projectKey`	String	project key

curl -H "Content-Type: application/json" -X GET -u admin:admin http://yourserver/rest/raven/1.0/api/testrepository/<projectKey>/folders

Responses

200 OK : application/json : Successful. Returns a JSON object.

Each folder will provide some information, including:

id: internal folder Id; "-1" corresponds to the Test Repository root folder
rank: rank of the folder in the parent folder ("1" corresponds to the first element)
name: folder's name
testRepositoryPath: the full Test Repository path of this folder
folders: sub-folders
testCount: count of direct child Tests
totalTestCount: total count of all childs Tests

{
"folders": [
  {
   "id": 6,
   "rank": 1,
   "name": "Folder1",
   "testRepositoryPath": "/Folder1"
   "folders": [],
   "testCount": 0,
   "totalTestCount": 0
  },
  {
   "id": 7,
   "rank": 2,
   "name": "Folder2",
   "testRepositoryPath": "/Core",
   "folders": [
     {
       "id": 8,
       "rank": 1,
       "name": "Sub2",
       "testRepositoryPath": "/Core/UI", 
       "folders": [],
       "testCount": 1,
       "totalTestCount": 1
      },
      {
       ...
      }
    ],
    "testCount": 0,
    "totalTestCount": 3
   }
  ],

}

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray license is not valid.

500 INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folders.

Tests

To obtain a list of the Tests associated with the Test Repository of a given project, you need to specify the key of project
To obtain a list of the Tests contained within a given Test Repository folder, you need to specify its folderId, besides the project key
To change (add/remove) Tests to a given folder, you need to specify the key of the respective project

Returns a JSON object with a list of the Tests contained in a given folder of the Test Repository.

This endpoint supports pagination.

Request

PATH PARAMETERS

parameter	type	description
`projectKey`	String	project key
`folderId`	Integer	internal folder Id; "-1" corresponds to the root folder of the Test Repository

QUERY PARAMETERS

parameter	type	description
allDescendants	Boolean	include all descendants (i.e. all child Tests); "false", by default
`page`	Integer	page of paginated data (first 1)
`limit`	Integer	amount of Tests per paginated data

curl -H "Content-Type: application/json" -X GET -u admin:admin http://yourserver/rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/tests

curl -H "Content-Type: application/json" -X GET -u admin:admin http://yourserver//rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/tests?allDescendants=true

Responses

200 OK : text/plain : Successful. Returns a JSON object containing the Tests.

Each test will provide some information, including:

id: internal Test Id
key: Test's issue key
summary: Test's summary
assignee: Test's issue assignee
rank: rank of the Test in the parent folder ("1" corresponds to the first element)
workflowStatus: Test's workflow status
labels: array of all Test's assigned labels
components: array of all Test's assigned components
testType: Test type (e.g. "Manual", "Cucumber, "Generic")

{
 "tests": [
   {
    "id": 24300, 
    "key": "FP-10",
    "summary": "Issue test create inside folder",
    "assignee": "",
    "rank": 1,
    "workflowStatus": "Open",
    "labels": [],
    "components": [],
    "testType": "Manual",
   },
   {
    "id": 24301,
    "key": "FP-11",
    "summary": "Issue test create inside folder",
    "assignee": "",
    "rank": 2,
    "workflowStatus": "Open",
    "labels": [],
    "components": [],
    "testType": "Manual",
   },
   {
    ...
   }
  ],
  "total": 3,
}

{
 "tests": [
   {
    "id": 24300,
    "key": "FP-10",
    "summary": "Issue test create inside folder",
    "assignee": "",
    "rank": 1,
    "workflowStatus": "Open",
    "labels": [],
    "components": [],
    "testType": "Manual",
   },
   {
    "id": 24301,
    "key": "FP-11",
    "summary": "Issue test create inside folder",
    "assignee": "",
    "rank": 1,
    "workflowStatus": "Open",
    "labels": [],
    "components": [],
    "testType": "Manual",
   },
   {
    ...
   }
  ],
  "total": 3,
}

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray license is not valid.

500 INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the tests.

Add/remove tests to/from the given Test Repository folder. Returns error messages, if there are any.

Request

PATH PARAMETERS

parameter	type	description
`projectKey`	String	project key
folderId	integer	internal folder Id

Example

{
 "add": [
    "CALC-33",
    "CALC-75"
  ],
  "remove": [
    "CALC-25",
    "CALC-45"
  ]
}

curl -H "Content-Type: application/json" -X PUT -u admin:admin --data @example.json http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/9/tests

Responses

200 OK : text/plain : Successful. Return error messages, if there are any.

["Issue with key CALC-33 not found or is not of type Test."]

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray for JIRA license is not valid.

500 INTERNAL SERVER ERROR : text/plain : An internal error occurred associating the tests.

Folders

To obtain or update information about a given Test Repository folder, you need to specify both the project key and the internal folder Id
To remove a folder from the Test Repository, you need to specify both the project key and the internal folder Id

Returns a JSON object with folder information.

Request

PATH PARAMETERS

parameter	type	description
`projectKey`	String	project key
folderId	integer	internal folder Id

curl -H "Content-Type: application/json" -X GET -u admin:admin http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6

Responses

200 OK : application/json : Successful. Returns a JSON object.

{
  "id": 6,
  "rank": 1,
  "name": "Folder1",
  "testRepositoryPath": "/Folder1"
  "testCount": 0,
  "totalTestCount": 0
}

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray license is not valid.

500 INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folder.

Creates a folder and returns a JSON object with folder information.

Request

PATH PARAMETERS

parameter	type	description
`projectKey`	String	project key
`folderId`	integer	internal folder Id; "-1" corresponds to the root folder of the Test Repository

JSON body attributes

parameter	type	description
`name`	String	name of folder

Example

{
  "name": "Folder1"
}

curl -H "Content-Type: application/json" -X POST -u admin:admin --data @example.json http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/-1

Responses

201 CREATED : application/json : Successful. Returns a JSON object.

{
  "id": 6,
  "rank": 1,
  "name": "Folder1",
  "testRepositoryPath": "/Folder1"
  "testCount": 0,
  "totalTestCount": 0
}

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray for JIRA license is not valid.

500 INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folder.

Updates an existing folder.

Request

PATH PARAMETERS

parameter	type	description
`projectKey`	String	project key
folderId	integer	internal folder Id

JSON body attributes

parameter	type	description
`name`	String	name of folder
rank	Integer	rank within the parent folder

Example

{
  "name": "Folder1",
  "rank": 4
}

curl -H "Content-Type: application/json" -X PUT -u admin:admin --data @example.json http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6

Responses

204 No content : text/plain : Successful. Does not return anything.

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray license is not valid.

500 INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folder.

Remove folder from the Test Repository.

Request

PATH PARAMETERS

parameter	type	description
`projectKey`	String	project key
folderId	integer	internal folder Id

curl -H "Content-Type: application/json" -X DELETE -u admin:admin http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6

Responses

204 No content : text/plain : Successful.

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray license is not valid.

500 INTERNAL SERVER ERROR : text/plain : An internal error occurred removing the test.