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.

Rate Limit

Please note that the API is rate limited on TestRail Hosted 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.