API: Introduction - TestRail

API: Introduction

TestRail’s API can be used to integrate TestRail with various tools, frameworks and third-party applications. For example, many customers use the API to integrate their automated tests and submit test results to TestRail. The API can be used for various other tasks as well and you can find a small list of examples below.

The API is HTTP-based and can thus be used from virtually any framework, programming language and tool. Submitting data to TestRail via the API is done via simple POST requests. Requesting data is done through GET requests. All requests and responses use the JSON format and UTF-8 encoding.

 

    The API is part of TestRail and can be enabled in TestRail’s administration area under Administration > Site Settings > API.

    Some typical scenarios the API can be used for:

    • Submit test results from automated tests
    • Migrate test cases from legacy systems
    • Synchronize test cases between different systems
    • Create test runs and plans programmatically
    • Query information for integrations
    Before reading through the API reference, please make yourself familiar with TestRail’s entities such as cases, runs & results, suites etc. To do this, please refer to TestRail’s User Guide with getting started topics and best practices.

    API Rate Limit

    Please note that the API is rate-limited on TestRail Cloud to ensure optimal performance for all users and may throttle requests. TestRail might also return a 429 Too Many Requests response, which you are expected to handle. Such a response also includes a Retry-After header indicating how many seconds to wait before you are allowed to submit the next request.

    To avoid rate limits on TestRail Cloud, try using bulk API endpoints (e.g. using as add_results_for_cases instead of add_results_for case), build a time delay into your API calls, or upgrade to TestRail Enterprise Cloud.

    Rate limits for TestRail Cloud are as follows:

    • 180 Requests per instance, per minute for TestRail Cloud Professional subscriptions.
    • 300 Requests per instance, per minute for TestRail Cloud Enterprise subscriptions.

    No API rate limits are built into TestRail Server installations.

    Conventions used in API Reference

    1. Variables with curly braces

    Replace any values with curly braces { } in API requests with actual parameters.

    For example, in the API request, GET index.php?/api/v2/get_project/{project_id}, replace {project_id} with the value for your actual project id. 

    So, if your project id is 10, the request would be GET index.php?/api/v2/get_project/10

    2. Truncated response code examples

     ..  in a code block indicates truncating.

     

    How to find ID variables?

    To find the ID which you have to use as a parameter in an API request, please check the following:

    Project ID – project_id

    1. Go to the ‘Dashboard’ on your TestRail instance.
    2. Select a project from the list.
    3. Check the URL. The numeric character you see at the end is Project ID, or you can also get the ID next to Project Name. Please make sure to omit the character ‘P’ when using API requests.

    For example, in API request, GET index.php?/api/v2/get_project/{project_id}, replace {project_id} with 3.

    So, the request would look like GET index.php?/api/v2/get_project/3.

     

    Case ID – case_id

    1. Go to the ‘Dashboard’ on your TestRail instance.
    2. Select a project from the list.
    3. Navigate to the ‘Test Cases’ tab.
    4. Select a test case from the list.
    5. Check the URL. The numeric character you see at the end is Test Case ID, or you can also get the ID next to Test Case Name. Please make sure to omit the character ‘C’ when using API requests.

    Milestone ID – milestone_id

    1. Go to the ‘Dashboard’ on your TestRail instance.
    2. Select a project from the list.
    3. Navigate to the ‘Milestones’ tab.
    4. Select a milestone from the list.
    5. Check the URL. The numeric character you see at the end is Milestone ID, or you can also get the ID next to Milestone Name. Please make sure to omit the character ‘M’ when using API requests.

    Test Plan ID – plan_id

    1. Go to the ‘Dashboard’ on your TestRail instance.
    2. Select a project from the list.
    3. Navigate to the ‘Test Runs and Results’ tab.
    4. Select a test plan from the list.
    5. Check the URL. The numeric character you see at the end is Test Plan ID, or you can also get the ID next to Test Plan Name. Please make sure to omit the character ‘R’ when using API requests.

    Test Run ID – run_id

    1. Go to the ‘Dashboard’ on your TestRail instance.
    2. Select a project from the list.
    3. Navigate to the ‘Test Runs and Results’ tab.
    4. Select a test run from the list.
    5. Check the URL. The numeric character you see at the end is Test Run ID, or you can also get the ID next to Test Run Name. Please make sure to omit the character ‘R’ when using API requests.