API: Accessing the API

TestRail's API is HTTP-based and you can use simple HTTP requests to interact with it. All write 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, learn more). Please ask your TestRail administrator if you aren't sure which option your TestRail installation uses.

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.

If you maintain your own TestRail instance on your own server, it is recommended to enable HTTPS for your TestRail installation as using the API requires sending your TestRail user name and password. For TestRail Hosted accounts maintained by Gurock, all accounts automatically use HTTPS.

Example 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:<some-password>" \
	"https://example.testrail.com/index.php?/api/v2/get_case/1"

The parts of this request in detail:

Part Description
"Content-Type: application/json" A required header
https://example.testrail.com/ The server address
index.php?/api/v2/ The path of TestRail's API
get_case The API method that is called
/1 An argument for the API method

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

Write Request

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

$ curl -H "Content-Type: application/json" \
	-u "user@example.com:<some-password>" \
	-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
	..
}