{"article":{"id":7077292642580,"url":"https://gurock.zendesk.com/api/v2/help_center/en-us/articles/7077292642580.json","html_url":"https://support.testrail.com/hc/en-us/articles/7077292642580-Cases","author_id":415527390832,"comments_disabled":true,"draft":false,"promoted":false,"position":2,"vote_sum":1,"vote_count":23,"upvote_count":12,"downvote_count":11,"section_id":7077185274644,"created_at":"2022-06-16T10:51:45Z","updated_at":"2026-10-07T08:47:21Z","name":"Cases","title":"Cases","source_locale":"en-us","locale":"en-us","outdated":false,"outdated_locales":[],"edited_at":"2026-10-07T08:47:21Z","user_segment_id":null,"permission_group_id":6972358691476,"content_tag_ids":[],"label_names":[],"body":"

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

\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
case_idintegertrueThe ID of the test case

Example request:

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

Response content

Example response:

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

The following system fields are always included in the response:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
created_byintegerThe ID of the user who created the test case
created_ontimestampThe date/time when the test case was created (as UNIX timestamp)
estimatetimespanThe estimate, e.g. \"30s\" or \"1m 45s\"
estimate_forecasttimespanThe estimate forecast, e.g. \"30s\" or \"1m 45s\"
idintegerThe unique ID of the test case
is_ai_automatedbooleanIndicates whether the test case has been flagged for AI automation. TestRail Cloud only — always false or absent on Server instances. Requires TestRail 10.9 or later.\n
is_ai_generatedbooleanIndicates whether the test case was generated by AI. TestRail Cloud only — always false or absent on Server instances. Requires TestRail 10.9 or later.\n
milestone_idintegerThe ID of the milestone that is linked to the test case
priority_idintegerThe ID of the priority that is linked to the test case
refsstringA comma-separated list of references/requirements that are linked to the test case
section_idintegerThe ID of the section the test case belongs to
suite_idintegerThe ID of the suite the test case belongs to
template_idintegerThe ID of the template (field layout) the test case uses—requires TestRail 5.2 or later\n
titlestringThe title of the test case
type_idintegerThe ID of the test case type that is linked to the test case
updated_byintegerThe ID of the user who last updated the test case
updated_ontimestampThe date/time when the test case was last updated (as UNIX timestamp)
versionstringThe version of the test case — requires TestRail 10.9 or later\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the test case is returned as part of the response)
400Invalid or unknown test case
403No access to the project
429\nTestRail 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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
project_idintegertrueThe ID of the project
suite_idintegerSee DescriptionThe ID of the test suite (optional if the project is operating in single suite mode)
created_aftertimestampfalseOnly return test cases created after this date (as UNIX timestamp)
created_beforetimestampfalseOnly return test cases created before this date (as UNIX timestamp)
created_byinteger (list)falseA comma-separated list of creators (user IDs) to filter by
fieldsstringfalseA comma-separated list of field names to include in the response (e.g. id,title,status_id,updated_on). When omitted, all fields are returned. — requires TestRail 10.8 or later\n
filterstringfalseOnly return cases with matching filter string in the case title
limitintegerfalseThe number of test cases the response should return (The response size is 250 by default) —requires TestRail 6.7 or later\n
milestone_idinteger (list)falseA comma-separated list of milestone IDs to filter by (not available if the milestone field is disabled for the project)\n
offsetintegerfalseWhere to start counting the tests cases from (the offset)—requires TestRail 6.7 or later\n
priority_idinteger (list)falseA comma-separated list of priority IDs to filter by
refsstringfalseA single Reference ID (e.g. TR-1, 4291, etc.) —requires TestRail 6.5.2 or later\n
section_idintegerfalseThe ID of a test case section
status_id     integer (list)falseA comma-separated list of status IDs to filter by — requires TestRail 10.8 or later\n
template_idinteger (list)falseA comma-separated list of template IDs to filter by —requires TestRail 5.2 or later\n
type_idinteger (list)falseA comma-separated list of case type IDs to filter by
updated_aftertimestampfalseOnly return test cases updated after this date (as UNIX timestamp)
updated_beforetimestampfalseOnly return test cases updated before this date (as UNIX timestamp)
updated_byintegerfalseA comma-separated list of user IDs who updated test cases to filter by
label_idinteger (list)falseA comma-separated list of label IDs to filter by
assignedto_id integer (list)falseA comma-separated list of user IDs to filter by assignee — requires TestRail 10.8 or later\n

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\nGET index.php?/api/v2/get_cases/34&suite_id=2&priority_id=3,4\n\n# Get 10 test cases from project 34\nGET index.php?/api/v2/get_cases/34&limit=10\n\n# Only returning test cases from project 34 starting the offset number\nGET index.php?/api/v2/get_cases/34&offset=5\n\n# Filter cases in project 34 with a filter string of \"login\"\nGET index.php?/api/v2/get_cases/34&filter=login\n\n# Combined usage\nGET index.php?/api/v2/get_cases/34&offset=:5&limit=:10&filter=:login\n

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.

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

Response codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the test cases are returned as part of the response)
400Invalid or unknown test case
403No access to the project
429\nTestRail Cloud only—Too many requests (see API rate limit)

get_cases_count

This endpoint requires TestRail 10.9 or later.

Returns the total count of test cases for a project, along with pagination metadata indicating how many paginated requests would be required to retrieve all matching cases using get_cases.

GET index.php?/api/v2/get_cases_count/{project_id}

Parameters

Accepts the same filter parameters as get_cases (e.g. suite_id, section_id, type_id, priority_id, created_after, updated_after, etc.).

Response content

Example response:

{\n    \"count\": 1250,\n    \"pages\": 5,\n    \"requests\": 5\n}
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
countintegerThe total number of test cases matching the applied filters
pagesintegerThe number of pages required to retrieve all matching cases at the default page size (250)
requestsintegerThe number of API requests required to retrieve all matching cases at the default page size (250)

Response codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the count is returned as part of the response)
400Invalid or unknown project
403No access to the project
429\nTestRail 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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
case_idintegertrueThe ID of the test case
limitintegerfalseThe number of test case changes the response should return (The response size is 250 by default) — requires TestRail 6.7 or later\n
offsetintegerfalseWhere to start counting the tests case changes from (the offset) — requires TestRail 6.7 or later\n

The following system fields are always included in the response:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
idintegerThe ID of the test case change
created_ontimestampThe UNIX timestamp the change was made
type_idintegerThe change type. This value is typically 6, indicating an 'update'. (The type_id values in the 'changes' array are described below)\n
user_idintegerThe ID of the user who made the change
changesarrayAn array of details for the changes made to the test cases

The following fields can be included in the changes array:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
type_idintegerThe type of the updated field
1 = string
2 = integer
3 = boolean
4 = date
5 = timespan
6 = text
7 = URL
8 = steps\n
old_texttextThe previous text value of the updated field (Used for text fields)\n
new_texttextThe new text value of the updated field (Used for text fields)\n
labelstringThe field label as seen in the user interface
optionsarrayAn array of options configured in the field, such as required, default value, etc.
fieldstringThe system name of the updated field
old_valuevariesThe 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_valuevariesThe 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:

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

Response codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the test case is returned as part of the response)
400Invalid or unknown test case
403No access to the project
429\nTestRail 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):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
section_idintegertrueThe ID of the section the test case should be added to
titlestringtrueThe title of the test case
template_idintegerfalseThe ID of the template (field layout)—requires TestRail 5.2 or later\n
type_idintegerfalseThe ID of the case type
priority_idintegerfalseThe ID of the case priority
estimatetimespanfalseThe estimate, e.g. \"30s\" or \"1m 45s\"
milestone_idintegerfalseThe ID of the milestone to link to the test case
refsstringfalseA comma-separated list of references/requirements
versionstringfalseThe version of the test case — requires TestRail 10.9 or later\n
labels Array of mixed values (integer or string)falseThe ID of a label, the title of a label or both, in array form.
is_legacybooleanfalse\n

When set to \"true\", indicates the content in supported text fields are Markdown and will be later converted to HTML for use with the Rich Text Editor in the TestRail UI.

\n

Note: this setting applies to all supported text fields in the test case, including custom fields.

\n

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

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

The following custom field types are supported:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
CheckboxbooleanTrue for checked and false otherwise
DatestringA date in the same format as configured for TestRail and API user (e.g. \"07/08/2013\")
DropdownintegerThe ID of a dropdown value as configured in the field configuration
IntegerintegerA valid integer
MilestoneintegerThe ID of a milestone for the custom field
Multi-selectarrayAn array of IDs as configured in the field configuration
StepsarrayAn array of objects specifying the steps. Also see the example below
StringstringA valid string with a maximum length of 250 characters
TextstringA string without a maximum length
URLstringA string with matches the syntax of a URL
UserintegerThe 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:

{\n    \"title\": \"This is a test case\",\n    \"type_id\": 1,\n    \"priority_id\": 3,\n    \"estimate\": \"3m\",\n    \"refs\": \"RF-1, RF-2\",\n    \"custom_steps_separated\": [\n        {\n            \"content\": \"Step 1\",\n            \"expected\": \"Expected Result 1\"\n        },\n        {\n            \"content\": \"Step 2\",\n            \"expected\": \"Expected Result 2\"\n        },\n        {\n            \"shared_step_id\": 3\n        },\n    \"is_legacy\": false,\n    \"labels\": [\n     'label1, 'label5',7,9,10,'label8'\n       ]\n    ]\n}

Response content

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

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

The following system fields are always included in the response:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
created_byintegerThe ID of the user who created the test case
created_ontimestampThe date/time when the test case was created (as UNIX timestamp)
estimatetimespanThe estimate, e.g. \"30s\" or \"1m 45s\"
estimate_forecasttimespanThe estimate forecast, e.g. \"30s\" or \"1m 45s\"
idintegerThe unique ID of the test case
milestone_idintegerThe ID of the milestone that is linked to the test case
priority_idintegerThe ID of the priority that is linked to the test case
refsstringA comma-separated list of references/requirements that are linked to the test case
section_idintegerThe ID of the section the test case belongs to
suite_idintegerThe ID of the suite the test case belongs to
template_idintegerThe ID of the template (field layout) the test case uses—requires TestRail 5.2 or later\n
titlestringThe title of the test case
type_idintegerThe ID of the test case type that is linked to the test case
updated_byintegerThe ID of the user who last updated the test case
updated_ontimestampThe date/time when the test case was last updated (as UNIX timestamp)
versionstringThe version of the test case — requires TestRail 10.9 or later\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the test case is created as part of the response)
400Invalid or unknown test case
403No access to the project
429\nTestRail Cloud only—Too many requests (see API rate limit)

add_cases

Creates multiple test cases.

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

Requires TestRail 10.4 or later.

Parameters

The following POST fields are supported:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
section_idintegertrueThe ID of the section the test cases should be added to
casesarraytrueAn array of test case objects to create. Maximum 500 cases per request.

Each object in the cases array supports the following system fields:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
titlestringtrueThe title of the test case
template_idintegerfalseThe ID of the template (field layout)—requires TestRail 5.2 or later\n
type_idintegerfalseThe ID of the case type
priority_idintegerfalseThe ID of the case priority
estimatetimespanfalseThe estimate, e.g. \"30s\" or \"1m 45s\"
milestone_idintegerfalseThe ID of the milestone to link to the test case
refsstringfalseA comma-separated list of references/requirements
labels Array of mixed values (integer or string)falseThe ID of a label, the title of a label or both, in array form.
is_legacybooleanfalse\n

When set to \"true\", indicates the content in supported text fields are Markdown and will be later converted to HTML for use with the Rich Text Editor in the TestRail UI.

\n

Note: this setting applies to all supported text fields in the test case, including custom fields.

\n

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

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

Add_cases endpoint support all custom field types that are supported in the add_case endpoint. Please see add_case for a full list of available custom field types.

Request example

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

{\n    \"cases\": [\n        {\n            \"title\": \"This is a test case\",\n            \"type_id\": 1,\n            \"priority_id\": 3,\n            \"estimate\": \"3m\",\n            \"refs\": \"RF-1, RF-2\",\n            \"custom_steps_separated\": [\n                {\n                    \"content\": \"Step 1\",\n                    \"expected\": \"Expected Result 1\"\n                },\n                {\n                    \"content\": \"Step 2\",\n                    \"expected\": \"Expected Result 2\"\n                },\n                {\n                    \"shared_step_id\": 3\n                }\n            ],\n            \"is_legacy\": false,\n            \"labels\": [\"label1\", \"label5\", 7, 9, 10, \"label8\"]\n        }\n    ]\n}

Response content

If successful, this method returns an array of the new test cases using the same response format as get_case. Example response:

[\n    {\n        \"id\": 1,\n        \"title\": \"This is a test case\",\n        \"section_id\": 1,\n        \"template_id\": 1,\n        \"type_id\": 1,\n        \"priority_id\": 2,\n        \"milestone_id\": null,\n        \"refs\": \"RF-1, RF-2\",\n        \"created_by\": 1,\n        \"created_on\": 1646317844\n    }\n]\n

The following system fields are always included in the response:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
created_byintegerThe ID of the user who created the test case
created_ontimestampThe date/time when the test case was created (as UNIX timestamp)
estimatetimespanThe estimate, e.g. \"30s\" or \"1m 45s\"
estimate_forecasttimespanThe estimate forecast, e.g. \"30s\" or \"1m 45s\"
idintegerThe unique ID of the test case
milestone_idintegerThe ID of the milestone that is linked to the test case
priority_idintegerThe ID of the priority that is linked to the test case
refsstringA comma-separated list of references/requirements that are linked to the test case
section_idintegerThe ID of the section the test case belongs to
suite_idintegerThe ID of the suite the test case belongs to
template_idintegerThe ID of the template (field layout) the test case uses—requires TestRail 5.2 or later\n
titlestringThe title of the test case
type_idintegerThe ID of the test case type that is linked to the test case
updated_byintegerThe ID of the user who last updated the test case
updated_ontimestampThe 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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the test cases are created and returned as part of the response)
400Invalid or unknown section, or one or more test case objects failed validation
403No access to the project
429\nTestRail 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):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
section_idintegertrueThe ID of the section the test case should be copied to
case_idsarray of integersfalseA comma-separated list of case IDs

Response codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the test cases are copied as part of the response)
400Invalid or unknown test case
403No access to the project
429\nTestRail 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):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
case_idintegertrueThe ID of the test case
section_idintegerfalseThe ID of the section the test case should be updated to
titlestringfalseThe title of the test case
template_idintegerfalseThe ID of the template (field layout)—requires TestRail 5.2 or later\n
type_idintegerfalseThe ID of the case type
priority_idintegerfalseThe ID of the case priority
estimatetimespanfalseThe estimate, e.g. \"30s\" or \"1m 45s\"
milestone_idintegerfalseThe ID of the milestone to link to the test case
refsstringfalseA comma-separated list of references/requirements
labels Array of mixed values (integer or string)falseThe ID of a label, the title of a label or both, in array form.
is_legacybooleanfalse\n

When set to \"true\", indicates the content in supported text fields are Markdown and will be later converted to HTML for use with the Rich Text Editor in the TestRail UI.

\n

Note: this setting applies to all supported text fields in the test case, including custom fields.

\n

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:

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

Response content

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

Response codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the test case is updated as part of the response)
400Invalid or unknown test case
403No access to the project
429\nTestRail 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):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
case_idsarray of integerstrueThe ID of the cases that need to be updated
suite_idintegerSee descriptionThe ID of the test suite (optional if the project is operating in single suite mode)
section_idintegerfalseThe ID of the section the test case should be updated to
titlestringfalseThe title of the test case
template_idintegerfalseThe ID of the template (field layout)—requires TestRail 5.2 or later\n
type_idintegerfalseThe ID of the case type
priority_idintegerfalseThe ID of the case priority
estimatetimespanfalseThe estimate, e.g. \"30s\" or \"1m 45s\"
milestone_idintegerfalseThe ID of the milestone to link to the test case
refsstringfalseA comma-separated list of references/requirements
labels Array of mixed values (integer or string)falseThe ID of a label, the title of a label or both, in array form.

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:

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

Response content

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

Response codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the test case is returned as part of the response)
400Invalid or unknown test case
403No access to the project
429\nTestRail 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):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
section_idintegertrueThe ID of the section the case will be moved to
suite_idintegertrueThe ID of the suite the case will be moved to
case_idsarray of integerstrueA comma-separated list of case IDs

Response codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the test cases are updated as part of the response)
400Invalid or unknown test case
403No access to the project
429\nTestRail Cloud only—Too many requests (see API rate limit)

delete_case

\n

 

\n

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

\n

Deletes an existing test case.

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

Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
case_idintegertrueThe ID of the test case
softintegerfalsesoft=1 will return information about the data which will be deleted but will not proceed with the deletion

Soft parameter

\n

 

\n

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

\n

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

Including soft=1 will not actually delete the entity.

Response codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the test case is deleted as part of the response)
400Invalid or unknown test case
403No access to the project
429\nTestRail Cloud only—Too many requests (see API rate limit)

delete_cases

\n

 

\n

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

\n

Deletes multiple test cases from a project or test suite.

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

Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
case_idsarray of integerstrueAn array of the IDs of the test cases you would like to delete
project_idintegertrueThe ID of the project
suite_idintegerSee descriptionThe ID of the suite (Only required if project is in multi-suite mode)
softintegerfalsesoft=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.

{\n    \"case_ids\": [1, 2, 3]\n}

Response codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeDescription
200Success (the test case are deleted as part of the response)
400Invalid or unknown test case
403No access to the project
429\nTestRail Cloud only—Too many requests (see API rate limit)
","user_segment_ids":[]}}