API: Cases - TestRail

API: Cases

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

get_case

Returns an existing test case.

GET index.php?/api/v2/get_case/:case_id
:case_id The ID of the test case

 

Response content

Please see below for a typical response:

{
    "created_by": 5,
    "created_on": 1392300984,
    "custom_expected": "..",
    "custom_preconds": "..",
    "custom_steps": "..",
    "custom_steps_separated": [
        {
            "content": "Step 1",
            "expected": "Expected Result 1"
        },
        {
            "content": "Step 2",
            "expected": "Expected Result 2"
        }
    ],
    "estimate": "1m 5s",
    "estimate_forecast": null,
    "id": 1,
    "milestone_id": 7,
    "priority_id": 2,
    "refs": "RF-1, RF-2",
    "section_id": 1,
    "suite_id": 1,
    "title": "Change document attributes (author, title, organization)",
    "type_id": 4,
    "updated_by": 1,
    "updated_on": 1393586511
}

The following system fields are always included in the response:

Name Type Description
created_by int 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 int The unique ID of the test case
milestone_id int The ID of the milestone that is linked to the test case
priority_id int The ID of the priority that is linked to the test case
refs string A comma-separated list of references/requirements
section_id int The ID of the section the test case belongs to
suite_id int The ID of the suite the test case belongs to
template_id int 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 int The ID of the test case type that is linked to the test case
updated_by int 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

200 Success, the test case is returned as part of the response
400 Invalid or unknown test case
403 No access to the project

 

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
:project_id The ID of the project
:suite_id The ID of the test suite (optional if the project is operating in single suite mode)

 

Request filters

The following filters can be applied:

Name Type Description
:created_after timestamp Only return test cases created after this date (as UNIX timestamp).
:created_before timestamp Only return test cases created before this date (as UNIX timestamp).
:created_by integer (list) A comma-separated list of creators (user IDs) to filter by.
:filter string Only return cases with matching filter string in the case title
:limit integer The number of test cases the response should return
:milestone_id integer (list) A comma-separated list of milestone IDs to filter by (not available if the milestone field is disabled for the project).
:offset integer Where to start counting the tests cases from (the offset)
:priority_id integer (list) A comma-separated list of priority IDs to filter by.
:refs_filter string A single Reference ID (e.g. TR-1, 4291, etc.) (requires TestRail 6.5.2 or later)
:section_id integer The ID of a test case section
:template_id integer (list) A comma-separated list of template IDs to filter by (requires TestRail 5.2 or later)
:type_id integer (list) A comma-separated list of case type IDs to filter by.
:updated_after timestamp Only return test cases updated after this date (as UNIX timestamp).
:updated_before timestamp Only return test cases updated before this date (as UNIX timestamp).
:updated_by integer (list) A comma-separated list of user IDs who updated test cases to filter by.
# All test cases for project with ID 1, suite with ID 2 and priority 3 or 4
GET index.php?/api/v2/get_cases/1&suite_id=2&priority_id=3,4

Examples:
# Limit the number of cases using :limit filter
GET index.php?/api/v2/get_cases/:project_id&limit=10

# Only start returning test cases from the offset number
GET index.php?/api/v2/get_cases/:project_id&offset=5

# Filter cases with a filter string
GET index.php?/api/v2/get_cases/:project_id&filter=login

# Combined usage
GET index.php?/api/v2/get_cases/:project_id&offset=:5&limit=:10&filter=:login

Response content

The response includes an array of test cases. Each test case in this list follows the same format as get_case.

[
	{ "id": 1, "title": "..", .. },
	{ "id": 2, "title": "..", .. },
	..
]

Response codes

200 Success, the test cases are returned as part of the response
400 Invalid or unknown project, suite or section
403 No access to the project

 

get_history_for_case/:case_id

Returns the edit history for a test case_id.

Requires TestRail 6.5.4 or later.

GET index.php?/api/v2/get_history_for_case/:case_id
:case_id The ID of the test case

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:

[
  {
    "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

200 Success, the test case changes are returned as part of the response
400 Invalid or unknown case ID
403 No access to the project

 

add_case

Creates a new test case.

POST index.php?/api/v2/add_case/:section_id
:section_id The ID of the section the test case should be added to

 

Request fields

The following POST fields are supported (system fields):

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

 

Custom fields 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 bool 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 int The ID of a dropdown value as configured in the field configuration
Integer int A valid integer
Milestone int 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 int 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:

{
	"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"
		},

		..
	]

	..
}

Response content

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

Response codes

200 Success, the test case was created and is returned as part of the response
400 Invalid or unknown section
403 No permissions to add test cases or no access to the project

 

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
:case_id The ID of the test case

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

200 Success, the test case was updated and is returned as part of the response
400 Invalid or unknown test case
403 No permissions to modify test cases or no access to the project

 

update_cases/:project_id&suite_id=X

Updates multiple test cases with the same values, such as 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_case/:project_id&suite_id=X
:project_id

The ID of the project

:suite_id The ID of the suite (Only required if the project is in multi-suite mode)

 

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

200 Success, the test case was updated and is returned as part of the response
400 Invalid or unknown test case
403 No permissions to modify test cases or no access to the project

 

delete_case

Deletes an existing test case.

POST index.php?/api/v2/delete_case/:case_id
:case_id The ID of the test case

 

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.

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

Response codes

200 Success, the test case was deleted
400 Invalid or unknown test case
403 No permissions to delete test cases or no access to the project

delete_cases/:project_id&suite_id=X&soft=1

Deletes multiple test cases from a project or test suite.

POST index.php?/api/v2/delete_cases/:project_id&suite_id&soft=1
:project_id The ID of the project
:suite_id The ID of the suite (Only required if project is in multi-suite mode)
:soft Optional parameter

 

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.

info Please Note: Deleting test cases cannot be undone and will also delete any associated tests and results in open test runs and test plans.

Request example

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

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

Response codes

200 Success, the test case was deleted
400 Invalid or unknown test case
403 No permissions to delete test cases or no access to the project