API: Cases - TestRail

API: Cases

Use the following API methods to retrieve data about test cases—like title, case fields, and history—and to create, modify, or delete test cases.

On this page:

    get_case

    Returns an existing test case.

    GET index.php?/api/v2/get_case/{case_id}

    Parameters

    Name Type Required Description
    case_id
    integer true The ID of the test case

    Example request:


    # Get the test case with an ID of 42
    GET index.php?/api/v2/get_case/42
    

    Response content

    Example response:

    {
        "id": 1,
        "title": "Print document history and attributes",
        "section_id": 1,
        "template_id": 1,
        "type_id": 2,
        "priority_id": 2,
        "milestone_id": null,
        "refs": null,
        "created_by": 1,
        "created_on": 1646317844,
        "updated_by": 1,
        "updated_on": 1646317844,
        "estimate": null,
        "estimate_forecast": "8m 40s",
        "suite_id": 1,
        "display_order": 1,
        "is_deleted": 0,
        "custom_automation_type": 0,
        "custom_preconds": null,
        "custom_steps": null,
        "custom_expected": null,
        "custom_steps_separated": null,
        "custom_mission": null,
        "custom_goals": null
    }
    

    The following system fields are always included in the response:

    Name Type Description
    created_by integer The ID of the user who created the test case
    created_on
    timestamp The date/time when the test case was created (as UNIX timestamp)
    estimate
    timespan The estimate, e.g. “30s” or “1m 45s”
    estimate_forecast
    timespan The estimate forecast, e.g. “30s” or “1m 45s”
    id
    integer The unique ID of the test case
    milestone_id
    integer The ID of the milestone that is linked to the test case
    priority_id
    integer The ID of the priority that is linked to the test case
    refs
    string A comma-separated list of references/requirements
    section_id
    integer The ID of the section the test case belongs to
    suite_id
    integer The ID of the suite the test case belongs to
    template_id
    integer The ID of the template (field layout) the test case uses—requires TestRail 5.2 or later
    title
    string The title of the test case
    type_id
    integer The ID of the test case type that is linked to the test case
    updated_by
    integer The ID of the user who last updated the test case
    updated_on
    timestamp The date/time when the test case was last updated (as UNIX timestamp)

    Custom fields are also included in the response and use their system name prefixed with ‘custom_’ as their field identifier. Please see add_case for a full list of available custom field types.

    Response codes

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

     

    get_cases

    Returns a list of test cases for a project or specific test suite (if the project has multiple suites enabled).

    GET index.php?/api/v2/get_cases/{project_id}&suite_id={suite_id}

    Parameters

    Name Type Required Description
    project_id
    integer true The ID of the project
    suite_id
    integer See Description The ID of the test suite (optional if the project is operating in single suite mode)
    created_after
    timestamp false Only return test cases created after this date (as UNIX timestamp).
    created_before
    timestamp false Only return test cases created before this date (as UNIX timestamp).
    created_by
    integer (list) false A comma-separated list of creators (user IDs) to filter by.
    filter
    string false Only return cases with matching filter string in the case title
    limit
    integer false The number of test cases the response should return (The response size is 250 by default) —requires TestRail 6.7 or later.
    milestone_id
    integer (list) false A comma-separated list of milestone IDs to filter by (not available if the milestone field is disabled for the project).
    offset
    integer false Where to start counting the tests cases from (the offset)—requires TestRail 6.7 or later.
    priority_id
    integer (list) false A comma-separated list of priority IDs to filter by.
    refs
    string false A single Reference ID (e.g. TR-1, 4291, etc.) —requires TestRail 6.5.2 or later.
    section_id
    integer false The ID of a test case section
    template_id
    integer (list) false A comma-separated list of template IDs to filter by —requires TestRail 5.2 or later.
    type_id
    integer (list) false A comma-separated list of case type IDs to filter by.
    updated_after
    timestamp false Only return test cases updated after this date (as UNIX timestamp).
    updated_before
    timestamp false Only return test cases updated before this date (as UNIX timestamp).
    updated_by
    integer (list) false A comma-separated list of user IDs who updated test cases to filter by.

     

    Example Requests:

     

    # Get all the test cases that are in project 34 (project ID of 34), suite with ID of 2 and priority 3 or 4
    GET index.php?/api/v2/get_cases/34&suite_id=2&priority_id=3,4
    
    # Get 10 test cases from project 34
    GET index.php?/api/v2/get_cases/34&limit=10
    
    # Only returning test cases from project 34 starting the offset number
    GET index.php?/api/v2/get_cases/34&offset=5
    
    # Filter cases in project 34 with a filter string of "login"
    GET index.php?/api/v2/get_cases/34&filter=login
    
    # Combined usage
    GET index.php?/api/v2/get_cases/34&offset=:5&limit=:10&filter=:login
    

    Response content

    The response includes an array of test cases. Each test case in the array of “cases” objects follows the same format as the response to get_case.

    {"offset": 0,
      "limit": 250,
      "size": 250,
      "_links":{
        "next": "/api/v2/get_cases/1&limit=250&offset=250",
        "prev": null
        },
      "cases":[
    	  { "id": 1, "title": "..", .. },
    	  { "id": 2, "title": "..", .. },
    	  ..
        ]
    }
    

    Response codes

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

     

    get_history_for_case

    This endpoint requires TestRail 6.5.4 or later.

    Returns the edit history for a test case_id.

    GET index.php?/api/v2/get_history_for_case/{case_id}

    Parameters

    Name Type Required Description
    case_id integer true The ID of the test case
    limit integer false The number of test case changes the response should return (The response size is 250 by default) — requires TestRail 6.7 or later.
    offset integer false Where to start counting the tests case changes from (the offset) — requires TestRail 6.7 or later.

    Response Fields

    The following fields are returned:

    Name Type Description
    id
    integer The ID of the test case change.
    created_on
    timestamp The UNIX timestamp the change was made.
    type_id
    integer The change type. This value is typically 6, indicating an ‘update’. (The type_id values in the ‘changes’ array are described below).
    user_id
    integer The ID of the user who made the change.
    changes
    array An array of details for the changes made to the test cases.

    The following fields can be included in the changes array:

    Name Type Description
    type_id
    integer The type of the updated field
    1 = string
    2 = integer
    3 = boolean
    4 = date
    5 = timespan
    6 = text
    7 = URL
    8 = steps
    old_text
    text The previous text value of the updated field (Used for text fields).
    new_text
    text The new text value of the updated field (Used for text fields).
    label
    string The field label as seen in the user interface
    options
    array An array of options configured for the field, such as required, default value, etc.
    field
    string The system name of the updated field
    old_value
    varies The previous value of the updated field. This is used for any non-text field, including the separated steps field. The value can be text or an integer, depending on the field type.
    new_value
    varies The new value of the updated field. This is used for any non-text field, including the separated steps field. The value can be text or an integer, depending on the field type.

     

    Response content

    The response includes an array of test case changes. Each entry in the array is a change record:

    [
      {
        "offset": 0,
        "limit": 250,
        "size": 1,
        "_links": {
        "next": null,
        "prev": null
      },
    	"history": [
      {
        "id": 3382,
        "type_id": 6,
        "created_on": 1597927176,
        "user_id": 1,
        "changes": [
          {
            "type_id": 1,
            "old_text": "Original Section",
            "new_text": "Updated Section",
            "field": "section_id",
            "old_value": 3573,
            "new_value": 3574
          }
          {...},
          ...
        ]
      },
      {
        "id": 3389,
        "type_id": 6,
        "created_on": 1597932715,
        "user_id": 1,
        "changes": [
          {
            "type_id": 1,
            "field": "refs",
            "old_value": null,
            "new_value": "1"
          }
        ]
      },
      ...
    ]
    

    Response codes

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

     

    add_case

    Creates a new test case.

    POST index.php?/api/v2/add_case/{section_id}

    Parameters

    The following POST fields are supported (system fields):

    Name Type Required Description
    section_id integer true The ID of the section the test case should be added to
    title
    string true The title of the test case
    template_id
    integer false The ID of the template (field layout)—requires TestRail 5.2 or later.
    type_id
    integer false The ID of the case type
    priority_id
    integer false The ID of the case priority
    estimate
    timespan false The estimate, e.g. “30s” or “1m 45s”
    milestone_id
    integer false The ID of the milestone to link to the test case
    refs
    string false A comma-separated list of references/requirements

     

    Custom field parameters are supported as well and must be submitted with their system name, prefixed with ‘custom_’, e.g.:

    {
      ..
      "custom_preconds": "These are the preconditions for a test case"
      ..
    }
    

    The following custom field types are supported:

    Name Type Description
    Checkbox
    boolean True for checked and false otherwise
    Date
    string A date in the same format as configured for TestRail and API user (e.g. “07/08/2013”)
    Dropdown
    integer The ID of a dropdown value as configured in the field configuration
    Integer
    integer A valid integer
    Milestone
    integer The ID of a milestone for the custom field
    Multi-select
    array An array of IDs as configured in the field configuration
    Steps
    array An array of objects specifying the steps. Also see the example below.
    String
    string A valid string with a maximum length of 250 characters
    Text
    string A string without a maximum length
    URL
    string A string with matches the syntax of a URL
    User
    integer The ID of a user for the custom field

     

    Request example

    Also see the following example which shows how to submit steps with the structured steps custom field and a shared test step:

    {
      "title": "This is a test case",
      "type_id": 1,
      "priority_id": 3,
      "estimate": "3m",
      "refs": "RF-1, RF-2",
      ..
      "custom_steps_separated": [
        {
          "content": "Step 1",
          "expected": "Expected Result 1"
        },
        {
          "content": "Step 2",
          "expected": "Expected Result 2"
        },
        {
          "shared_step_id": 3
         },
         ..
      ]
      ..
    }
    

    Response content

    If successful, this method returns the new test case using the same response format as get_case. Example response:

    {
        "id": 1,
        "title": "Print document history and attributes",
        "section_id": 1,
        "template_id": 1,
        "type_id": 2,
        "priority_id": 2,
        "milestone_id": null,
        "refs": null,
        "created_by": 1,
        "created_on": 1646317844,
        ..
    }
    

    The following system fields are always included in the response:

    Name Type Description
    created_by integer The ID of the user who created the test case
    created_on
    timestamp The date/time when the test case was created (as UNIX timestamp)
    estimate
    timespan The estimate, e.g. “30s” or “1m 45s”
    estimate_forecast
    timespan The estimate forecast, e.g. “30s” or “1m 45s”
    id
    integer The unique ID of the test case
    milestone_id
    integer The ID of the milestone that is linked to the test case
    priority_id
    integer The ID of the priority that is linked to the test case
    refs
    string A comma-separated list of references/requirements
    section_id
    integer The ID of the section the test case belongs to
    suite_id
    integer The ID of the suite the test case belongs to
    template_id
    integer The ID of the template (field layout) the test case uses—requires TestRail 5.2 or later.
    title
    string The title of the test case
    type_id
    integer The ID of the test case type that is linked to the test case
    updated_by
    integer The ID of the user who last updated the test case
    updated_on
    timestamp The date/time when the test case was last updated (as UNIX timestamp)

    Custom fields are also included in the response and use their system name prefixed with ‘custom_’ as their field identifier. Please see add_case for a full list of available custom field types.

    Response codes

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

     

    copy_cases_to_section

    Copies the list of cases to another suite/section.

    POST index.php?/api/v2/copy_cases_to_section/{section_id}

    Parameters

    The following POST fields are supported (system fields):

    Name Type Required Description
    section_id integer true The ID of the section the test case should be copied to
    case_ids string false A comma-separated list of case IDs.

    Response codes

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

     

    update_case

    Updates an existing test case (partial updates are supported, i.e. you can submit and update specific fields only).

    POST index.php?/api/v2/update_case/{case_id}

    Parameters

    Name Type Required Description
    case_id integer true The ID of the test case
    section_id integer false The ID of the section the test case should be updated to
    title
    string false The title of the test case
    template_id
    integer false The ID of the template (field layout)—requires TestRail 5.2 or later.
    type_id
    integer false The ID of the case type
    priority_id
    integer false The ID of the case priority
    estimate
    timespan false The estimate, e.g. “30s” or “1m 45s”
    milestone_id
    integer false The ID of the milestone to link to the test case
    refs
    string false A comma-separated list of references/requirements

     

    This method supports the same POST fields as add_case. Updating a case’s section_id requires TestRail 6.5.2 or later.

    Request example

    Also see the following example which shows how to update the priority and estimate fields for a test case:

    {
      "priority_id": 1,
      "estimate": "5m"
    }
    

    Response content

    If successful, this method returns the new test case using the same response format as get_case.

    Response codes

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

     

    update_cases

    Updates multiple test cases with the same values, like setting a set of test cases to “High” priority. This does not support updating multiple test cases with different values per test case.

    POST index.php?/api/v2/update_cases/{suite_id}

    Parameters

    Name Type Required Description
    case_ids array of integers true The ID of the cases that need to be updated
    suite_id integer See description The ID of the test suite (optional if the project is operating in single suite mode)
    section_id integer false The ID of the section the test case should be updated to
    title
    string false The title of the test case
    template_id
    integer false The ID of the template (field layout)—requires TestRail 5.2 or later.
    type_id
    integer false The ID of the case type
    priority_id
    integer false The ID of the case priority
    estimate
    timespan false The estimate, e.g. “30s” or “1m 45s”
    milestone_id
    integer false The ID of the milestone to link to the test case
    refs
    string false A comma-separated list of references/requirements

     

    This method supports the same POST fields as add_case. Updating a case’s section_id requires TestRail 6.5.2 or later.

    Request example

    Also see the following example which shows how to update the priority and estimate fields for a test case. The case_ids field is a required field and indicates the test cases which should be updated:

    {
      "case_ids": [1,2,3],
      "priority_id": 1,
      "estimate": "5m"
    }
    

    Response content

    If successful, this method returns the new test case using the same response format as get_case.

    Response codes

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

     

    move_cases_to_section

    Moves cases to another suite or section.

    POST index.php?/api/v2/move_cases_to_section/{section_id}

    Parameters

    The following POST fields are supported (system fields):

    Name Type Required Description
    section_id integer true The ID of the section the case will be moved to.
    suite_id integer true The ID of the suite the case will be moved to.
    case_ids array of integers true A comma-separated list of case IDs.

     

    Response codes

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

     

    delete_case

    Deletes an existing test case.

    Please Note: Deleting a test case cannot be undone and also permanently deletes all test results in active test runs (i.e. test runs that haven’t been closed (archived) yet).

    POST index.php?/api/v2/delete_case/{case_id}

    Parameter

    Name Type Required Description
    case_id integer true The ID of the test case
    soft integer false soft=1 will return information about the data which will be deleted, but will not proceed with the deletion.

     

    Soft parameter

    If soft=1, this will return data on the number of affected tests.

    Including soft=1 will not actually delete the entity.

    Note: Omitting the soft parameter, or submitting soft=0, will delete the test case.

    Response codes

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

     

    delete_cases

    Deletes multiple test cases from a project or test suite.

    Please Note: Deleting a test case cannot be undone and also permanently deletes all test results in active test runs or test plans (i.e. test runs that haven’t been closed / archived yet).

    POST index.php?/api/v2/delete_cases/{suite_id}&soft=1

    Parameters

    Name Type Required Description
    case_ids array of integers true An array of the IDs of the test cases you would like to deleter
    project_id integer true The ID of the project
    suite_id integer See description The ID of the suite (Only required if project is in multi-suite mode)
    soft integer false Optional parameter. soft=1 will return information about the data which will be deleted, but will not proceed with the deletion.

     

    Request example

    Also see the following example which shows the case ids from the selected project.

    {
      "case_ids": [1,2,3,...]
    }
    

    Response codes

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