Join 34,000+ subscribers and receive articles from our blog about software quality, testing, QA and security.

API plans


I read in the forum that there were plans for an API, but I wasn’t able to find any other information. Is there any update on when this would potentially be in the product?

My use case is an external automation system that is already in place which I would like to tie into TestRail so that I can have one place to review all status for project testing. The basic use case would be for the ability to change the status of a test run that is pre-defined and ready for the automation to flip it to pass/fail/etc.

Of course, having the ability to manipulate all portions of a test run, and create new ones would be great.

Right now, I can’t do anything here since changing the status of a test run involves javascript (AFAIK) which is not easily scriptable from a remote automation tool.

I have yet to look at manipulating the database records directly - that’s next on my list.


I’ve tried manipulating the database tables directly, and while I can set a particular test result to pass, the other displays showing overall stats don’t update. I assume there’s more logic in choosing a state than simply changing that particular table.

While I’m sure I could figure out all of the places to change, I’m still curious about basic API support for things like this.


Hello Steve,

sorry for the late response. We definitely plan to begin the work on a basic API soon. There’s currently no concrete date for this but we expect to begin the work on an API (and also add support for automated tests) after our current roadmap is implemented:

The next release (scheduled for this week) will include support for custom fields. After we’ve added support for Unicode and changed the test case history behavior, we plan to work on automated tests and the API.

I hope that makes our plans a bit clearer.

When you change the status of a test (status_id of the tests table), TestRail also re-calculates and updates the stats of the parent test run (and also the parent test plan, if available). It’s probably too time-consuming to re-implement the whole functionality yourself (and it may require changes for future TestRail updates).

While TestRail uses Javascript and Ajax to implement the test dialog and submitting the test result, it’s actually a normal HTTP POST request. TestRail just sends a POST request to:

Arguments are passed as JSON encoded array. There are few additional details you would need to know in case you want to implement this (authentication handling, for example), just let me know in case you are interested in this option and I will prepare an example.



Thanks for the very detailed reply!

I would very much appreciate an example of the HTTP POST with the array and auth. This is a far better way of approaching our short term needs than messing with the database and potentially creating data integrity problems.


Sure, I will prepare a simple example to call the HTTP routine and either email you or post the example tomorrow. Do you have a preference for a specific platform/language? If not, I will just use cURL in a simple shell or PHP script to demonstrate this (you can use this knowledge to call the HTTP routine with basically all platforms/languages).



It’s likely we’d be using cURL from a Linux machine, and any language is fine. PHP works! Thanks very much!


Hello Steve,

Here’s the script (it’s actually a bash script, not PHP, hope it’s OK):


Definitions that must be set before using this script. Note

that the user email and password must be URL encoded.


USER_COOKIE=“cookie.txt” # where to store the returned cookie

function usage()
echo "Usage: $0 <test_id> <status_id>"
exit 1

Check the script arguments

if [ -z $1 ]
echo 'Error: Test ID missing’

if [ -z $2 ]
echo 'Error: Status ID missing.'
echo 'Please use one of the following IDs:'
echo '1: Passed’
echo '2: Blocked’
echo '3: Untested’
echo '4: Retest’
echo '5: Failed’



curl -c $USER_COOKIE -d “email=$USER_EMAIL&password=$USER_PASS” $URL?/auth/login

Update the test

curl -H “X_REQUESTED_WITH: XMLHttpRequest” -b $USER_COOKIE -d $DATA $URL?/tests/ajax_add_change >> $LOG

And logout again

curl -c $USER_COOKIE -d “” $URL?/auth/logout

You can use it as follows:

The URL, email and password for the user and some other options must be configured in the script itself. Note that the email and password must be URL-encoded (please see the example values above). The USER_TOKEN variable must be set to the csrf token of the user who submits the request (the value can be looked up in the ‘users’ database, the field is called ‘csrf’).

Just let me know in case you have questions.



Thanks very much! This is perfect. Bash is fine. I’ll give it a try today and let you know how it goes.


Just tested and it works perfectly! This solves 80% of our automation needs. Thanks very much for getting this to me so quickly.


Great to hear that, you are welcome! Just let me know in case there’s anything else.