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 the following example 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 test suite or specific section in a test suite.

GET index.php?/api/v2/get_cases/:project_id \ 
	&suite_id=:suite_id \
	&section_id=:section_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)
:section_id The ID of the section (optional)

Request filters

The following filters can be applied: (available since TestRail 4.0)

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 int (list) A comma-separated list of creators (user IDs) to filter by.
:milestone_id int (list) A comma-separated list of milestone IDs to filter by (not available if the milestone field is disabled for the project).
:priority_id int (list) A comma-separated list of priority IDs to filter by.
:template_id int (list) A comma-separated list of template IDs to filter by (requires TestRail 5.2 or later)
:type_id int (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 int (list) A comma-separated list of users 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

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

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 (except section_id).

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

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