API: Configurations

Use the following API methods to request details about configurations and to create or modify configurations.

get_configs

Returns a list of available configurations, grouped by configuration groups (requires TestRail 3.1 or later).

GET index.php?/api/v2/get_configs/:project_id

:project_id The ID of the project

Response content

The response includes an array of configuration groups, each with a list of configurations. Please see below for a typical example:

[
	{
		"configs": [
			{
				"group_id": 1,
				"id": 1,
				"name": "Chrome"
			},
			{
				"group_id": 1,
				"id": 2,
				"name": "Firefox"
			},
			{
				"group_id": 1,
				"id": 3,
				"name": "Internet Explorer"
			}
		],
		"id": 1,
		"name": "Browsers",
		"project_id": 1
	},
	{
		"configs": [
			{
				"group_id": 2,
				"id": 6,
				"name": "Ubuntu 12"
			},
			{
				"group_id": 2,
				"id": 4,
				"name": "Windows 7"
			},
			{
				"group_id": 2,
				"id": 5,
				"name": "Windows 8"
			}
		],
		"id": 2,
		"name": "Operating Systems",
		"project_id": 1
	}
]

The example response includes two configuration groups (Browsers and Operating Systems), each with three example configurations:

ID Group Configuration
1 Browsers Chrome
2 Browsers Firefox
3 Browsers Internet Explorer
4 Operating Systems Windows 7
5 Operating Systems Windows 8
6 Operating Systems Ubuntu 12

Please also see add_plan_entry and add_plan for an example on how to use configurations.

Response codes

200 Success, the configurations are returned as part of the response
400 Invalid or unknown project
403 No access to the project

add_config_group

Creates a new configuration group (requires TestRail 5.2 or later).

POST index.php?/api/v2/add_config_group/:project_id

:project_id The ID of the project the configuration group should be added to

Request fields

The following POST fields are supported:

Name Type Description
name string The name of the configuration group (required)

Request example

Also see the following example which shows how to create a new configuration group:

{
	"name": "Browsers"
}

Response codes

200 Success, the configuration group was created and is returned as part of the response
400 Invalid or unknown project
403 No permissions to add configuration groups or no access to the project

add_config

Creates a new configuration (requires TestRail 5.2 or later).

POST index.php?/api/v2/add_config/:config_group_id

:config_group_id The ID of the configuration group the configuration should be added to

Request fields

The following POST fields are supported:

Name Type Description
name string The name of the configuration (required)

Request example

Also see the following example which shows how to create a new configuration:

{
	"name": "Chrome"
}

Response codes

200 Success, the configuration was created and is returned as part of the response
400 Invalid or unknown project
403 No permissions to add configurations or no access to the project

update_config_group

Updates an existing configuration group (requires TestRail 5.2 or later).

POST index.php?/api/v2/update_config_group/:config_group_id

:config_group_id The ID of the configuration group

Request fields

The following POST fields are supported:

Name Type Description
name string The name of the configuration group

Request example

Also see the following example which shows how to update a configuration group:

{
	"name": "Operating Systems"
}

Response codes

200 Success, the configuration group was updated and is returned as part of the response
400 Invalid or unknown configuration group
403 No permissions to modify configuration groups or no access to the project

update_config

Updates an existing configuration (requires TestRail 5.2 or later).

POST index.php?/api/v2/update_config/:config_id

:config_id The ID of the configuration

Request fields

The following POST fields are supported:

Name Type Description
name string The name of the configuration

Request example

Also see the following example which shows how to update a configuration:

{
	"name": "Firefox"
}

Response codes

200 Success, the configuration was updated and is returned as part of the response
400 Invalid or unknown configuration
403 No permissions to modify configurations or no access to the project

delete_config_group

Deletes an existing configuration group and its configurations (requires TestRail 5.2 or later).

POST index.php?/api/v2/delete_config_group/:config_group_id

:config_group_id The ID of the configuration group

Please note: Deleting a configuration group cannot be undone and also permanently deletes all configurations in this group. It does not, however, affect closed test plans/runs, or active test plans/runs unless they are updated.

Response codes

200 Success, the configuration group and all its configurations were deleted
400 Invalid or unknown configuration group
403 No permissions to delete configuration groups or no access to the project

delete_config

Deletes an existing configuration (requires TestRail 5.2 or later).

POST index.php?/api/v2/delete_config/:config_id

:config_id The ID of the configuration

Please note: Deleting a configuration cannot be undone. It does not, however, affect closed test plans/runs, or active test plans/runs unless they are updated.

Response codes

200 Success, the configuration was deleted
400 Invalid or unknown configuration
403 No permissions to delete configurations or no access to the project