Accessing the TestRail API

TestRail’s API is HTTP-based and you can use simple HTTP requests to interact with it. All written requests must use the HTTP POST method, and all read requests must use the HTTP GET method. Data is transferred in the JSON format and UTF-8 encoding.

Authentication

TestRail expects the authentication credentials to be provided via standard HTTP basic authentication for the API. There are two ways to authenticate API requests with TestRail.

Username and Password

You can either pass your standard TestRail username (which is usually your email address) and your TestRail password to TestRail for the API authentication. This needs to be sent via HTTP basic authentication.

Depending on how your TestRail authentication is configured, your password might also be your regular Active Directory or LDAP password (this depends on how TestRail is configured, check the Authentication guide to learn more). Please ask your TestRail administrator if you aren’t sure which option your TestRail installation uses.

$ curl -H "Content-Type: application/json" \ 
  -u "user@example.com:{some-password}" \
  ..

The header is defined and starts at the -H tag and ends at the second \ after the user credentials.

Username and API Key

Alternatively, TestRail also supports API keys. API keys can be generated in TestRail under My Settings. With an API key, you would still use HTTP basic authentication and you would still send your TestRail username (e.g. your email address). You would just replace your password with any of the generated/active API keys. You can generate multiple API keys for different systems or third-party tools and revoke access by deleting the API key at any time under My Settings.

$ curl -H "Content-Type: application/json" \
  -u "user@example.com:{api key}" \
  ..

API Script Repository

We do have sample API Scripts available in our public GitHub repository. You may find a script which already suits your needs or which only needs a few simple changes. Please see our TestRail customizations GitHub repository.

We also encourage anyone to submit their own scripts to this repository if the scripts could be helpful to other users.

Example GET Request

The following example shows a simple request to read a test case. We use the cURL command line tool to send the request in this example, but any HTTP tool or library will work. Please note that all user names, passwords and URLs are samples only.

$ curl -H "Content-Type: application/json" \
  -u "user@example.com:APIkey" \
  "https://example.testrail.com/index.php?/api/v2/get_case/1"

The parts of this request in detail:

The actual HTTP request and response look as follows (simplified):

GET /index.php?/api/v2/get_case/1 HTTP/1.1
Host: example.testrail.com
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id":1,
  "title":"An example test case"
  ..
}

Example POST Request

The following request shows a simple write request to submit a test result:

$ curl -H "Content-Type: application/json" \
  -u "user@example.com:" \
  -d '{ "status_id": 1 }' \
  "https://example.testrail.com//index.php?/api/v2/add_result/1"

The request and response look as follows (simplified):

POST /index.php?/api/v2/add_result/1 HTTP/1.1
Host: example.testrail.com
Content-Type: application/json

{ "status_id": 1 }

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id":1,
  "test_id":1,
  "status_id":1
  ..
}

Example Attachment Upload

The following request shows a simple write request to add an attachment to a test result:

$ curl -H "Content-Type: multipart/form-data" \ 
  -u "user@example.com:" \ 
  -F "attachment=@C:\\image.jpg" \ 
  "https://example.testrail.io/index.php?/api/v2/add_attachment_to_result/1"

The request and response look as follows (simplified):

POST /index.php?/api/v2/add_attachment_to_result/1 HTTP/1.1
Host: example.testrail.io
Content-Type: multipart/form-data

{"attachment_id":11}