API: Configurations - TestRail

API: Configurations

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

On this page:

    get_configs

    Returns a list of available configurations, grouped by configuration groups.

    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

    info 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

    info 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