---
title: "Test Plans - REST"
canonical: "https://docs.getxray.app/space/XRAY/301474100/Test%20Plans%20-%20REST"
format: markdown
---
You can manage (i.e., create, update, delete) Test Plans directly through [Jira's native REST API](https://docs.atlassian.com/jira/REST/latest/).

The Xray REST API provides the following endpoints.

# Test Plan Tests

- To view the Test associated with a Test Plan, you need to specify the key of the Test Plan you wish to view.
- To associate or remove a Test from a Test Plan, you need to send a JSON with a list of the keys. When associating, these keys can be Test keys or Test Set keys; when removing, they can only be Test keys.
- To remove a Test from a Test Plan, you need to specify the key of the Test you wish to remove.


> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Returns a JSON object with a list of the test associated with the test plan. Note that this endpoint may be paginated.
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### ** **<span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `testPlanKey` | *String* | - key of the test plan. |
> 
> ###### <span style="color: #003366">**QUERY PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `limit` | *Integer* | - limits the number of results per page. Should be greater or equal to 0 and lower or equal to the maximum set in the Global Configuration. |
> | `page` | *Integer* | -numberof the page to beretuned. Should be greater or equal to 1. |
> 
> > ✅ **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/testplan/TEST-123/test</span>](http://yourserver/rest/raven/1.0/api/testplan/TEST-123/test)
> 
> ### <span style="color: #000000">Responses </span>
> 
> 200 OK : **text/plain** : Successful. Return a json.
> 
> 
> ##### **Example Output**
> 
> ```
> [  
>    {  
>       "id":12215,
>       "key":"DEMO-12",
>       "latestStatus":"PASS"
>    },
>    {  
>       "id":13207,
>       "key":"DEMO-29",
>       "latestStatus":"TODO"
>    },
>    {  
>       "id":13602,
>       "key":"DEMO-44",
>       "latestStatus":"Fail"
>    }
> ]
> ```
> 
> 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 tests.


> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Associate tests with the test plan. Return 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** |
> | --- | --- | --- |
> | `testPlanKey` | *String* | - key of the test plan. |
> 
> ##### **Example Input**
> 
> ```
> {
> 	"add": [
> 		"CALC-14",
> 		"CALC-29"
> 	],
> 	"remove": [
> 		"CALC-15",
> 		"CALC-50"
> 	]
> }
> ```
> 
> > ✅ **Example Request**
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X POST -u admin:admin --data @example.json </span>[<span style="color: #000000">http://yourserver</span>](http://yourserver)<span style="color: #000000">/</span><span style="color: #000000">rest/raven/1.0/api/testplan/TEST-123/test</span>
> 
> <span style="color: #003366">**Responses**</span>** **
> 
> 200 OK : **text/plain** : Successful. Returns error messages if there are any.
> 
> 
> ##### **Example Output**
> 
> ```
> ["Test or Test Set with key CALC-29 not found or is not Type Test or Test Set"]
> ```
> 
> 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.

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Remove test from the test plan.
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### ** **<span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | testPlanKey | *String* | - key of the test plan. |
> | testKey | *String* | - key of the test. |
> 
> ##### **Example Input**
> 
> ```
> {
> 	"add": [
> 		"CALC-14",
> 		"CALC-29"
> 	],
> 	"remove": [
> 		"CALC-15",
> 		"CALC-50"
> 	]
> }
> ```
> 
> > ✅ **Example Request**
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X DELETE -u admin:admin </span>[<span style="color: #000000">http://yourserver</span>](http://yourserver)<span style="color: #000000">/</span><span style="color: #000000">rest/raven/1.0/api/testplan/TEST-123/test/TEST-321</span>
> 
> ###### <span style="color: #003366">**Responses**</span>** **
> 
> 200 OK : **text/plain** : Successful.
> 
> 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 removing the test .

# Test Plan Test Executions

- To view the Test Executions associated with a Test Plan, you need to specify the key of the Test Plan you wish to view.
  - Both regular and Archived Test Executions associated with a Test Plan will be returned, being differentiated by the property **"archived"** set as <u>false</u> or <u>true</u> respectively;
- To associate or remove a Test Execution from a Test Plan, you need to send a JSON with a list of the Test Execution keys.
  - Both regular and Archived Test Executions associated with a Test Plan will be returned, can be associated or removed from a Test Plan;
- To remove a Test Execution from a Test Plan, you need to specify the key of the Test Execution you wish to remove.


> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Returns a JSON object with a list of the test executions associated with the test plan.
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### ** **<span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `testPlanKey` | *String* | - key of the test plan. |
> 
> 
> > ✅ **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/testplan/TEST-123/testexecution</span>](http://yourserver/rest/raven/1.0/api/testplan/TEST-123/testexecution)
> 
> ### Responses
> 
> 200 OK : **text/plain** : Successful. Return a json.
> 
> 
> ##### **Example Output**
> 
> ```
> [  
>    {  
>       "id":12215,
>       "key":"DEMO-12",
>       "summary":"Test Execution for Test Plan Test-123",
> 	  "self":"http://localhost:5980/testJira/rest/api/2/issue/12215",
> 	  "environments" : [
> 		"IOS",
> 		"Android"
> 	  ],
>  	  "archived": false
>    },
>    {  
>       "id":12315,
>       "key":"DEMO-15",
>       "summary":"Test Execution for Test Plan Test-123",
> 	  "self":"http://localhost:5980/testJira/rest/api/2/issue/12315",
> 	  "environments" : [
> 		"IOS",
> 		"Android"
> 	  ],
>  	  "archived": false
>    }
> ]
> ```
> 
> 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 test executions.

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Associate test executions with the test plan. Return error messages, if there are any.
> 
> <span style="color: #333333">It's possible to specify if the tests in the test execution should be added to the test plan using the "addTestsToPlan" property in the JSON file. If this setting is empty in the JSON file, the config in the Xray miscellaneous will be used.</span>
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### ** **<span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | `testPlanKey` | *String* | - key of the test plan. |
> 
> ##### **Example Input**
> 
> ```
> {
> 	"addTestsToPlan": false,
> 	"add": [
> 		"CALC-14",
> 		"CALC-29"
> 	],
> 	"remove": [
> 		"CALC-15",
> 		"CALC-50"
> 	]
> }
> ```
> 
> > ✅ **Example Request**
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X POST -u admin:admin --data @example.json </span>[<span style="color: #000000">http://yourserver/</span>](http://yourserver/)<span style="color: #000000">/</span><span style="color: #000000">rest/raven/1.0/api/testplan/TEST-123/testexecution</span>
> 
> <span style="color: #003366">**Responses**</span>** **
> 
> 200 OK : **text/plain** : Successful. Returns error messages if there are any.
> 
> 
> ##### **Example Output**
> 
> ```
> ["Issue with key CALC-29 not found or is not of type Test Execution"]
> ```
> 
> 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 test executions.

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> Remove test execution from the test plan.
> 
> ### ** **<span style="color: #003366">**Request**</span>** **
> 
> ###### ** **<span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span>
> 
> | **parameter** | **type** | **description** |
> | --- | --- | --- |
> | testPlanKey | *String* | - key of the test plan. |
> | testExecKey | *String* | - key of the test. |
> 
> > ✅ **Example Request**
> > ✅ 
> > ✅ <span style="color: #000000">curl -H "Content-Type: application/json" -X DELETE -u admin:admin </span>[<span style="color: #000000">http://yourserver/</span>](http://yourserver/)<span style="color: #000000">/</span><span style="color: #000000">rest/raven/1.0/api/testplan/TEST-123/testexecution/TEST-321</span>
> 
> ###### <span style="color: #003366">**Responses**</span>** **
> 
> 200 OK : **text/plain** : Successful.
> 
> 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 removing the test execution.