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.

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)

API: Cases

On this page:

get_case

Parameters

Response content

Response codes

get_cases

Parameters

Response content

Response codes

get_history_for_case

Parameters

Response Fields

Response content

Response codes

add_case

Parameters

Request example

Response content

Response codes

copy_cases_to_section

Parameters

Response codes

update_case

Parameters

Request example

Response content

Response codes

update_cases

Parameters

Request example

Response content

Response codes

move_cases_to_section

Parameters

Response codes

delete_case

Parameter

Soft parameter

Response codes

delete_cases

Parameters

Request example

Response codes