---
title: "Test Repository - REST"
canonical: "https://docs.getxray.app/space/XRAY/301700901/Test%20Repository%20-%20REST"
format: markdown
---
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.

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Returns a JSON object with a list of the folders of the Test Repository.
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### ** **<span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `projectKey` | *String* | project key |
> 
> > ✅ **Example Request**
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X GET -u admin:admin </span>[<span style="color: #000000">http://yourserver/rest/raven/1.0/api/testrepository/<projectKey>/folders</span>](#)
> 
> ### <span style="color: #000000">Responses </span>
> 
> 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 <u>direct</u> child Tests
> - `totalTestCount`: total count of all childs Tests
> 
> 
> ##### **Example Output**
> 
> ```
> {
> "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

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Returns a JSON object with a list of the Tests contained in a given folder of the Test Repository.
> 
> This endpoint supports pagination.
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### ** **<span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `projectKey` | *String* | project key |
> | `folderId` | *Integer* | internal folder Id; "-1" corresponds to the root folder of the Test Repository |
> 
> ###### <span style="color: #003366">**QUERY **</span><span style="color: #003366">**PARAMETERS**</span>** **
> 
> | **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 |
> 
> > ✅ **Request examples**
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X GET -u admin:admin </span>[<span style="color: #000000">http://yourserver</span>](http://yourserver)/rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/tests
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X GET -u admin:admin </span>[<span style="color: #000000">http://yourserver/</span>](http://yourserver/)/rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/tests?allDescendants=true
> 
> ### <span style="color: #000000">Responses </span>
> 
> 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 <u>parent</u> 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")
> 
> 
> ##### **Output example for listing unsafe-only the direct descendants of a given folder**
> 
> ```
> {
>  "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,
> }
> ```
> 
> ##### **Output example for listing all descendants of a given folder**
> 
> ```
> {
>  "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.

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Add/remove tests to/from the given Test Repository folder. Returns error messages, if there are any.
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### <span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `projectKey` | *String* | project key |
> | folderId | *integer* | internal folder Id |
> 
> ##### **Example Input**
> 
> ```
> {
>  "add": [
>     "CALC-33",
>     "CALC-75"
>   ],
>   "remove": [
>     "CALC-25",
>     "CALC-45"
>   ]
> }
> ```
> 
> > ✅ **Request example**
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X PUT -u admin:admin --data @example.json </span>[<span style="color: #000000">http://yourserver</span>](http://yourserver)<span style="color: #000000">/rest/raven/1.0/api/testrepository/FP/folders/9/tests</span>
> 
> <span style="color: #003366">**Responses**</span>** **
> 
> 200 OK : **text/plain** : Successful. Return error messages, if there are any.
> 
> 
> ##### **Example Output**
> 
> ```
> ["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


> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Returns a JSON object with folder information.
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### <span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `projectKey` | *String* | project key |
> | folderId | *integer* | internal folder Id |
> 
> > ✅ **Request example**
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X GET -u admin:admin </span>[<span style="color: #000000">http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6</span>](http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6)
> 
> ### <span style="color: #003366">**Responses**</span>** **
> 
> 200 OK : **application/json** : Successful. Returns a JSON object.
> 
> ##### **Output example**
> 
> ```
> {
>   "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.

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Creates a folder and returns a JSON object with folder information.
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### <span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `projectKey` | *String* | project key |
> | `folderId` | *integer* | internal folder Id; "-1" corresponds to the root folder of the Test Repository |
> 
> ###### <span style="color: #003366">**JSON body attributes**</span>** **
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `name` | *String* | name of folder |
> 
> ##### **Input example**
> 
> ```
> {
>   "name": "Folder1"
> }
> ```
> 
> > ✅ **Request example**
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X POST -u admin:admin </span><span style="color: #000000">--data @example.json </span>[<span style="color: #000000">http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/-1</span>](http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/-1)
> 
> ### <span style="color: #003366">**Responses**</span>** **
> 
> 201 CREATED : **application/json** : Successful. Returns a JSON object.
> 
> ##### **Output example**
> 
> ```
> {
>   "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.

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Updates an existing folder.
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### <span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `projectKey` | *String* | project key |
> | folderId | *integer* | internal folder Id |
> 
> ###### <span style="color: #003366">**JSON body attributes**</span>** **
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `name` | *String* | name of folder |
> | rank | *Integer* | rank within the parent folder |
> 
> ##### **Example Input**
> 
> ```
> {
>   "name": "Folder1",
>   "rank": 4
> }
> ```
> 
> > ✅ **Request example**
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X PUT -u admin:admin </span><span style="color: #000000">--data @example.json </span>[<span style="color: #000000">http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6</span>](http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6)
> 
> ### <span style="color: #003366">**Responses**</span>** **
> 
> 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.

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Remove folder from the Test Repository.
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### ** **<span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `projectKey` | *String* | project key |
> | folderId | *integer* | internal folder Id |
> 
> > ✅ **Example Request**
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X DELETE -u admin:admin </span>[<span style="color: #000000">http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6</span>](http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6)
> 
> ###### <span style="color: #003366">**Responses**</span><span style="color: #000000">** **</span>
> 
> 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.