API: Cases - TestRail

API: Cases

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

On this page:

    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",
                "additional_info": "Supplementary Information for Step 1",
                "expected": "Expected Result 1",
                "refs": "ABC-123"
            },
            {
                "shared_step_id": 3,
                "content": "Shared Test Step",
                "additional_info": "Supplementary Information for Shared Test Step",
                "expected": "Expected Result",
                "refs": "ABC-124"
            }
        ],
        "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 (The response size is 250 by default) (requires TestRail 6.7 or later)
    :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) (requires TestRail 6.7 or later)
    :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": "..", .. },
    	..
    ]
    

    info Please Note: As of February 26, 2021 the data structure returned by bulk GET API endpoints will change. These bulk endpoints will no longer return an array of all entities, but will instead return an object with additional pagination fields and an array of up to 250 entities.To see the new response structure and test any necessary code changes, include the following header and value in your API requests: x-api-ident: beta.

    New Response Content

    The response includes an array of test cases. Each test case in this list follows the same format as 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

    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

    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

    Request filters

    The following filters can be applied:

    Name Type Description
    :limit integer The number of test cases the response should return (The response size is 250 by default) (requires TestRail 6.7 or later)
    :offset integer Where to start counting the tests cases 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:

    [
      {
        "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"
          }
        ] 
      ...
    ]
    

    info Please Note: As of February 26, 2021 the data structure returned by bulk GET API endpoints will change. These bulk endpoints will no longer return an array of all entities, but will instead return an object with additional pagination fields and an array of up to 250 entities.To see the new response structure and test any necessary code changes, include the following header and value in your API requests: x-api-ident: beta.

    New 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

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

    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

     

    copy_cases_to_section

    Copies the list of cases to another suite/section.

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

     

    Request fields

    The following POST fields are supported (system fields):

    Name Type Description
    case_ids string A comma-separated list of case IDs.

    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

    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_cases/: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

     

    move_cases_to_section

    Moves cases to another suite or section.

    POST index.php?/api/v2/move_cases_to_section/:section_id
    :section_id The ID of the section the case will be moved to.
    :suite_id The ID of the suite the case will be moved to.

     

    Request fields

    The following POST fields are supported (system fields):

    Name Type Description
    case_ids string A comma-separated list of case IDs.

    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

    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=1 will return information about the data which will be deleted, but will not proceed with the deletion.

     

    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