1. TestRail Support Center
  2. API Manual
  3. API reference

Cases

Updated

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.

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 that are linked to the test case
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 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 cases are 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

The following system fields are always included in the response:

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 in 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 that are linked to the test case
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 created 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 array of integers false A comma-separated list of case IDs

Response codes

Status Code Description
200 Success (the test cases are copied 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

The following POST fields are supported (system fields):

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 updated 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

The following POST fields are supported (system fields):

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 cases are updated 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

 

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).

Deletes an existing test case.

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

Parameters

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

 

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

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

Including soft=1 will not actually delete the entity.

Response codes

Status Code Description
200 Success (the test case is deleted 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

 

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).

Deletes multiple test cases from a project or test suite.

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 delete
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 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 are deleted 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)
Was this article helpful?
6 out of 12 found this helpful