API: Configurations - TestRail

API: Configurations

Use the following API methods to request details about test plan configurations and to create or modify configurations used to generate test plans.

On this page:

    get_configs

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

    GET index.php?/api/v2/get_configs/{project_id}

    Parameters

    Name Type Required Description
    project_id
    integer true 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

    Status Code Description
    200 Success (the configurations are returned as part of the response)
    400 Invalid or unknown project
    403 No access to the project
    429 TestRail Cloud only—Too many requests (see API rate limit)

     

    add_config_group

    Creates a new configuration group – requires TestRail 5.2 or later.

    POST index.php?/api/v2/add_config_group/{project_id}

    Parameters

    Name Type Required Description
    project_id
    integer true The ID of the project the configuration group should be added to

    Request body

    Name Type Required Description
    name
    string true The name of the configuration group

    Request example

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

    {
    	"name": "Browsers"
    }
    

    Response codes

    Status Code Description
    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
    429 TestRail Cloud only—Too many requests (see API rate limit)

     

    add_config

    Creates a new configuration – requires TestRail 5.2 or later.

    POST index.php?/api/v2/add_config/{config_group_id}

    Parameters

    Name Type Required Description
    config_group_id
    integer true The ID of the configuration group the configuration should be added to

    Request body

    Name Type Required Description
    name
    string true The name of the configuration

    Request example

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

    {
    	"name": "Chrome"
    }
    

    Response codes

    Status Code Description
    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 configurations or no access to the project
    429 TestRail Cloud only—Too many requests (see API rate limit)

     

    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}

    Parameters

    Name Type Required Description
    config_group_id
    integer true The ID of the configuration group

    Request body

    Name Type Required Description
    name
    string false 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

    Status Code Description
    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
    429 TestRail Cloud only—Too many requests (see API rate limit)

     

    update_config

    Updates an existing configuration- requires TestRail 5.2 or later.

    POST index.php?/api/v2/update_config/{config_id}

    Parameters

    Name Type Required Description
    config_id
    integer true The ID of the configuration

    Request body

    Name Type Required Description
    name
    string false The name of the configuration

    Request example

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

    {
    	"name": "Firefox"
    }
    

    Response codes

    Status Code Description
    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
    429 TestRail Cloud only—Too many requests (see API rate limit)

     

    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}

    Parameters

    Name Type Required Description
    config_group_id
    integer true 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

    Status Code Description
    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
    429 TestRail Cloud only—Too many requests (see API rate limit)

     

    delete_config

    Deletes an existing configuration – requires TestRail 5.2 or later.

    POST index.php?/api/v2/delete_config/{config_id}

    Parameters

    Name Type Required Description
    config_id
    integer true 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

    Status Code Description
    200 Success (the configuration was deleted)
    400 Invalid or unknown configuration 
    403 No permissions to delete configurations or no access to the project
    429 TestRail Cloud only—Too many requests (see API rate limit)