API for Automation

This document describes the REST endpoints that manage automation agents, scheduled execution commands, execution history, and the import of automated test results into QMetry.

Get List of all Automation Agents

This endpoint returns the automation agents registered in your instance.

POST /rest/admin/agent/read

Request

Content-Type: application/json

Parameters

The following table describes the request parameters.

Table 212. Get List of all Automation Agents Request

Name	Located in	Required	Description	Defualt	Schema
`start`	body	yes	Start index of records	-	integer
`limit`	body	yes	Number of records per page	-	integer
`page`	body	yes	Page number to be displayed	-	integer

Response

Content-Type: application/json

The following table describes the response codes.

Table 213. Get List of all Automation Agents Response

Status Code	Reason	Response Model
200	List of agents fetched successfully	ResponseEntity
400	Invalid JSON object or mandatory fields missing	-
401	Unauthorised or session expired	-
500	Returned when server connection times out	-

Fetch Scheduled Execution Command

This endpoint returns the scheduled execution commands for a specific automation agent.

POST /rest/admin/agent/listSchedules

Request

Content-Type: application/json

Parameters

The following table describes the request parameters.

Table 214. Fetch Scheduled Execution Command Request

Name	Located in	Required	Description	Defualt	Schema
data	body	yes	data	-	string
limit	body	yes	Number of records per page	-	integer
page	body	yes	Page number to be displayed	-	integer
pluginAgentId	body	yes	Unique identifier of pluginAgent		integer
start	body	no	Start index of records		integer

Response

Content-Type: application/json

The following table describes the response codes.

Table 215. Fetch Scheduled Execution Command Response

Status Code	Reason	Response Model
200	Fetch schedule for agent successfully	-
400	Invalid json object or mandatory fields missing	-
401	Unauthorised or session expired	-
500	Returned when server connection times out	-

Fetch Agent Details

This endpoint returns agent details such as the operating system and the agent type.

POST /rest/testsuites/linkplatform/assignagent/fetchScheduleDetails

Request

Content-Type: application/json

Parameters

The following table describes the request parameters.

Table 216. Fetch Agent Details like OS, Agent Type Request

Name	Located in	Required	Description	Defualt	Schema
data	body	yes	data	-	string
pluginAgentId	body	yes	Unique identifier of pluginAgent	-	integer
scheduleId	body	yes	Unique identifier of schedule	-	integer
schedultType	body	yes	scheduleType	-	string
agentCronScheduleId	body	no	Unique identifier of schedule agent		integer

Response

Content-Type: application/json

The following table describes the response codes.

Table 217. Fetch Agent Details like OS, Agent Type Response

Status Code	Reason	Response Model
200	Fetch agent details successfully	-
400	Invalid json object or mandatory fields missing	-
401	Unauthorised or session expired	-
500	Returned when server connection times out	-

Update Scheduled Command

This endpoint updates an existing scheduled execution command for an automation agent.

POST /rest/testsuites/linkplatform/assignagent/updateSchedule

Request

Content-Type: application/json

Parameters

Table 218. Update Scheduled Command Request

Name	Located in	Required	Description	Defualt	Schema
dropID	query	no	dropID	-	string
platformId	query	no	Unique identifier of platform	-	string
pluginAgentId	query	no	Unique identifier of pluginAgent	-	string
scheduledate	query	no	schedule date	-	string
scheduletime	query	no	schedule time	-	string
testSuiteId	query	no	Unique Identifier of the testSuiteI	-	string
tsRunId	query	no	Unique Identifier of Test Suite Run	-	string

Response

Content-Type: application/json

The following table describes the response codes.

Table 219. Update Scheduled Command Response

Status Code	Reason	Response Model
200	Fetch agent details successfully	-
400	Invalid json object or mandatory fields missing	-
401	Unauthorised or session expired	-
500	Returned when server connection times out	-

Delete Scheduled Execution Command

POST /rest/admin/agent/deleteSchedule

Request

Content-Type: application/json

Parameters

The following table describes the request parameters.

Table 220. Delete Scheduled Execution Command Request

Name	Located in	Required	Description	Defualt	Schema
`data`	body	yes	data	-	string
`pluginAgentId`	body	yes	Unique identifier of pluginAgent	-	integer
`scheduleId`	body	no	Unique identifier of schedule	-	integer
`scheduleType`	body	no	scheduleType	-	string

Response

Content-Type: application/json

The following table describes the response codes.

Table 221. Delete Scheduled Execution Command Response

Status Code	Reason	Response Model
200	Scheduled command deleted for the agent successfully	-
400	Invalid JSON object or mandatory fields missing	-
401	Unauthorised or session expired	-
500	Returned when server connection times out	-

Read the Execution History of an Agent

POST /rest/admin/agent/readExecutionHistory

Request

Content-Type: application/json

The following table describes the request parameters.

Parameters

Table 222. Read the Execution History of an Agent

Name	Located in	Required	Description	Defualt	Schema
`data`	body	yes	Data	-	string
`limit`	body	no	Number of records per page	-	integer
`page`	body	no	Page number to display	-	integer
`pluginAgentId`	body	yes	Unique identifier of the plugin agent	-	integer
`start`	body	no	Start index of records	-	integer

Response

Content-Type: application/json

The following table describes the response codes.

Status Code	Reason	Response Model
200	Read ExecutionHistory for agent successfully	-
400	Invalid json object or mandatory fields missing	-
401	Unauthorised or session expired	-
500	Returned when server connection times out	-

Create Test Suites through Automation

This endpoint imports automated test results and creates test suites in QMetry.

POST /rest/import/createandscheduletestresults/{headerRow}

Request

Content-Type:multipart/form-data

Parameters

The following table describes the request parameters.

Name	Located in	Required	Description	Default	Schema
scope	header	yes	scope	-	string
apikey	header	yes	Generated Automation API key	-	string
headerRow	path	yes	Default value is 1	-	string
file	formData	yes	Supported file extensions: .json, .xml, and .zip. (A .zip file must contain files of the format given in the entityType parameter.) When you use a custom template, only .xml files are supported.	-	string
entityType	formData	yes	Supported formats: TESTNG, or CUCUMBER, JUNIT, or HPUFT, ROBOT and QAF, XMLCUSTOM	-	string
cycleID	formData	no	Target Cycle Id, or Cycle Name. You can fetch the Cycle Id using the List Cycle API, and the Cycle Name from the detail view of the target Cycle.	-	string
platformID	formData	no	Target Platform Id or Platform Name. Platform Id, can be fetched using the List Platform API, and Platform Name can be obtained from the detail view of the target Platform.	-	string
testsuiteId	formData	no	Target Test Suite ID or Entity Key. You can fetch the TestsuiteId using the List Testsuite API, and the Entity Key from the detail view of the target Test Suite. If you are using a Custom Automation Template, specify this parameter to associate the imported results with an existing test suite. QMetry ignores this parameter in case automationHierarchy for JUnit result upload is 3 (multiple Test Suites). If Test Suite mapping is available in template, this parameter will be ignored.	-	string
testsuiteName	formData	no	Name of the new test suite. When you use a custom template that maps Test Suite Summary, QMetry ignores this parameter and generates the name from the mapping. QMetry ignores this parameter in case automationHierarchy for JUnit result upload is 3 (multiple Test Suites).	-	string
tsFolderPath	formData	no	The system creates new test suites in a specified test suite folder while importing automated test results. If the folder does not exist, the system creates it. This parameter is ignored if the test suite is being reused.	-	string
projectID	formData	no	You can fetch the Target Project ID, or project Key, or the project name. Project id using List Project API, and the Entity Key or name from the list view of the target Project.	-	string
releaseID	formData	no	Target Release ID or Release name. You can fetch the release id using the List Release API from the list details of the target Project.	-	string
buildID	formData	no	Target Build ID or Build name. You can fetch the build ID using the List Build API from the list details of the target Project.	-	string
automationHierarchy (ignored when you use a Custom Automation Template)	formData	no	The parameter has to be used only for TestNG and JUnit frameworks. For TestNG 1 creates Test Case -Test Step. 2 creates only a Test Case. For JUnit 1 creates Test Case-Test Step. 2 creates Test Case. 3 create Test Suite-Test Case. The default value is 1.	-	string
testcase_fields	formData	no	Mention system-defined fields and user-defined fields for the test case as shown in Test Case JSON Format. Mention all the mandatory fields other than Summary in this parameter.	-	`JSON`
testsuite_fields	formData	no	Mention all mandatory fields other than Summary in this parameter, as shown in Test Suite JSON Format The system ignores this parameter if you use the existing Test suite Id to upload results.	-	`JSON`
skipWarning	formData	no	0 - Test Case Import fails if the result file contains a test case summary with more than 255 characters. 1 - You can still import Test Cases by ignoring the warning. In this case, the system truncates the summary to 255 characters.	0	string
is_matching_required	formData	no	True - The system creates a new test case or test case version when the summary and steps do not match any version in the result file. False - The system reuses the linked test case version or auto-links the latest version when the entity key or summary matches, and updates the execution	True	string
customTemplate Name	string	Required when entityType is set to XMLCUSTOM	Exact name of the Custom Automation Template defined under Custom Automation Templates.

Note

When you import results with a custom template, the template name must exactly match a template defined under the Custom Automation Templates tab, and the result file must be in XML format.

Supported Fields

You reference fields by the field name shown under Manage Fields. The following rules apply to lookup list and multi-lookup list fields.

If the value does not exist in the project and auto-create value is enabled, the system adds the value to the list and assigns it to the test case.
If the value does not exist in the project and auto-create is disabled, the system does not add the value, and the test case field remains blank or keeps its default value.
If you add a new value to a multi-lookup list, the older values remain unchanged and the system adds the new value to the list.
The system adds list values to the same version of the test case.

System fields

The following table describes the system fields that you can set for a test case or a test suite.

Field	Example	Test Case	Test Suite	Notes
`component`	"component" : ["Label1, "Label2"]	Yes	No	Old values persist and new value gets set e.g., L1 and L2 are set and L3 is assigned, then the updated values for component will be L1, L2 and L3.
`priority`	"priority" : "Minor"	Yes	No	As mentioned for Look Up and Multi Look Up lists above.
`testCaseState`	"testCaseState":"Open"	Yes	No
`testCaseType`	"testCaseType":"Automated"	Yes	No
`testcaseOwner`	"testCaseOwner":"John"	Yes	No	Pass userAlias in the request. The system will not set the owner if it cannot find the requested user or if the user lacks rights to the Test Case module.
`description`	"description":"Sample Description."	Yes	Yes	Set as requested.
`estimatedTime`	"estimatedTime":30	Yes	No	Set as requested. (Allowed value is from 0 to 99999 minutes)
`testSuiteState`	"testSuiteState":"Open"	No	Yes	A new Status value is added if it does not exist in the project.
`testsuiteOwner`	"testsuiteOwner":"lizamathew"	No	Yes	Pass userAlias in the request. The system will not set the owner if it cannot find the requested user or if the user lacks rights to the Test Case module.

User Defined Fields

The following table describes the user-defined field types and their validation rules.

Custom Field Type	Validation Rule	Example	Notes
STRING	It accepts text in a single line	"tagName": "Sample test asset."	Set as requested.
LARGETEXT	It accepts text in multiple lines	"additionalComment": "this is a sample test asset"	Set as requested.
LOOKUPLIST	It accepts a single value on the list	"country": ["United States"]	Lookup type will be set as requested if its list value exists. If the value does not exist in the Project and auto-create is enabled, the value is added in the list and assigned to the test case. If the value does not exist in the Project and auto create value is disabled, the value is not added. The test case field remains blank or has default value in it.
MULTILOOKUPLIST	It accepts comma separated multiple values	"langaugePreference": ["English",Portuguese"]	Set as requested if its list value exists. If the value does not exist in the Project and auto-create is enabled, the value is added in the list and assigned to the test case. Additional value is selected, keeping the old values unchanged. E.g., A and B are set and we update with C, then updated values for the list will be A, B, and C.
DATEPICKER	It accepts the Date format that has been set in user profile	"reviewedDate": "08-30-2019"	Set as requested.
NUMBER	It accepts any number with decimal	"executionTime": 4	Set as requested.

Test Case Fields with UDFs in JSON format

{

"component":["com1", "com2"],
"priority":"High",
"testCaseState":"Open",
"testCaseType":"Manual",
"testcaseOwner":"lizamathew",
"estimatedTime":60,
"description":"Sample Description",

"userDefinedFields" : {

"reviewedDate": "08-30-2019",
"executionTime": 40,
"tagName": "Sample test asset.",
"additionalComment": "This is a sample test asset",
"country": ["United States"],
"langaugePreference": ["English","Portuguese"]

}

}

Test Suite Fields with UDFs in JSON format

{

"testSuiteState":"Open",
"testsuiteOwner":"lizamathew",
"description":"Testing 8.5.4 API Changes",

"userDefinedFields" : {

"reviewedDate": "08-30-2019",
"executionTime": 40,
"tagName": "Sample test asset.",
"additionalComment": "this is a sample test asset",
"country": ["United States"],
"langaugePreference": ["English","Portuguese"]
}

}

Import Result Scenarios

The following table shows the import result for each combination of field type, auto-create setting, and value existence.

Is System Field/UDF Mandatory?	Is Auto-Create Enabled?	Does UDF Value exist?	Import Result
No	No	No	Fail
No	No	Yes	Success
No	Yes	No	Success
No	Yes	Yes	Success
Yes	No	No	Fail
Yes	No	Yes	Success
Yes	Yes	No	Success

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Test Suites created successfully	ResponseEntity
400	Invalid json object or mandatory fields missing	-
401	Unauthorised or session expired	-
500	Returned when server connection times out	-

Get List of Custom Automation Import Templates

This endpoint returns the Custom Automation Import Templates defined in your instance.

Get /rest/parser/list

Request

Content-Type: application/json

Parameters

The following table describes the request parameters.

Table 223. Get list of Custom Automation Import Templates — request

Name	Located in	Required	Description	Default	Schema
start	body	Yes	Start index of records	-	integer
limit	body	Yes	Number of records per page	-	integer

Sample Request

{
  "start": 0,
  "limit": 30
}

Response

Content-Type: application/json

The response returns the total number of templates and a data array.

Sample Response

{
  "total": 2,
  "data": [
    {
      "ID": 40,
      "name": "run_results_customiz",
      "description": "with strict false",
      "jsonMapping": "{ \"name\": \"run_results_customiz\", \"strict\": false, \"jsonMapping\": { ... } }",
      "strictParse": false,
      "isJsonUpdated": true,
      "createdDate": "07-02-2026 12:12 PM",
      "createdBy": "NishantM",
      "updatedDate": "07-02-2026 12:12 PM",
      "updatedBy": "NishantM",
      "fieldMappings": [
        {
          "cpfID": 1,
          "fileFieldLabel": "${Results.ReportNode.ReportNode.Data.Name}",
          "qtmFieldLabel": "Test Case Summary"
        }
      ]
    }
  ]
}

Response Code

The following table describes the response codes.

Status Code	Reason	Response Model
200	Test Suites created successfully	ResponseEntity
400	Invalid json object or mandatory fields missing	-
401	Unauthorised or session expired	-
500	Returned when server connection times out	-

Definitions

ResponseEntity

name	type	required	description
headers	object	optional	-
body	object	optional	-
statusCode	string	optional	-

In this section:

API for Automation

Get List of all Automation Agents

Fetch Scheduled Execution Command

Fetch Agent Details

Update Scheduled Command

Delete Scheduled Execution Command

Read the Execution History of an Agent

Create Test Suites through Automation

Note

User Defined Fields

Test Case Fields with UDFs in JSON format

Test Suite Fields with UDFs in JSON format

Get List of Custom Automation Import Templates

Definitions

ResponseEntity

Search results