API: Variables - TestRail

API: Variables

Use the following API methods to upload, retrieve, update, and delete variables that exist in datasets.

On this page:

    get_variables

    Retrieves the requested variables.

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

    Parameters

    Name Type Required Description
    project_id
    integer true The ID of the project from which to retrieve variables.

    Example request:


    # Get the variables with an ID of 12
    GET index.php?/api/v2/get_variables/12
    

    Response content

    {
        "offset": 0,
        "limit": 250,
        "size": 2,
        "_links": {
            "next": null,
            "prev": null
        },
        "variables": [
            {
                "id": 611,
                "name": "d"
            },
            {
                "id": 612,
                "name": "e"
            }
        ]
    }
    

    Response Fields

    Name Type Description
    Pagination related fields
    array Fields consistent with pagination of existing bulk GET API endpoints
    variables
    array An array of objects. Each entry in the array contains:
    id – The ID of the variable in the database

    name – the name of the variable

    Response codes

    Status Code Description
    200 Success
    400

    Invalid project_id

    Missing project_id

    401 Authentication Failure
    403

    Insufficient permissions (cannot access this project)

    Not an Enterprise license/subscription

    add_variable

    Creates a new variable.

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

    Parameters

    Name Type Required Description
    project_id
    integer true The ID of the project to which the variable should be added.

    Example request:


    # Post the variable with an ID of 12
    POST index.php?/api/v2/add_variable/12
    

    Request Body

    {
        "id": 613,
        "name": "f"
    }
    

    Response content

    {
        "id": 1675,
        "name": "f"
    }
    

    Response Fields

    Name Type Description
    id
    integer ID of the newly added variable
    name
    string Name of the newly added variable

    Response codes

    Status Code Description
    200 Success
    400

    Invalid project_id

    Missing project_id

    Invalid variable name

    Name of variable already exists within the current project

    Number of allowed variables exceeded

    401 Authentication Failure
    403

    Insufficient permissions (cannot access project)

    Insufficient permissions (no add/edit permission for Test Data within the project)

    Not an Enterprise license/subscription

    update_variable

    Updates an existing variable.

    POST index.php?/api/v2/update_variable/{variable_id}

    Parameters

    Name Type Required Description
    variable_id
    integer true The ID of the variable to update.

    Example request:


    # Post the variable with an ID of 611
    POST index.php?/api/v2/update_variable/611
    

    Request Body

    The request body for the new dataset has the same response format as add_variable.

    Response content

    If successful, this method returns the new dataset using the same response format as add_variable.

    Response Fields

    Name Type Description
    id
    integer ID of the variable to update
    name
    string Name of the variable to update

    Response codes

    Status Code Description
    200 Success
    400

    Invalid variable_id

    Missing variable_id

    Invalid variable name

    Name of variable already exists within the current project

    401 Authentication Failure
    403

    Insufficient permissions (cannot access project)

    Insufficient permissions (no add/edit permission for Test Data within the project)

    Not an Enterprise license/subscription

    delete_variable

    Deletes an existing variable.

    POST index.php?/api/v2/delete_variable/{variable_id}

    Parameters

    Name Type Required Description
    variable_id
    integer true The ID of the variable to be deleted.

    info Please Note: Deleting a variable should also delete corresponding values from datasets.

    Response codes

    Status Code Description
    200 Success
    400

    Invalid variable_id

    Missing variable_id

    401 Authentication Failure
    403

    Insufficient permissions (cannot access project)

    Insufficient permissions (no delete permission for Test Data within the project)

    Not an Enterprise license/subscription