Our API allows access to the data in Testuff database. All access is encrypted using SSL and restricted only to the user company data.
It is a simple REST API for ease of use.


Use the API

To use the API, you will first need to have a valid Testuff account.

The API accepts HTTP requests.

You can use any language to access the API: Python, PHP, Perl, Java or any other – whichever is easiest for you.
All API requests should start with:…. (find your service number, the X, in the API tab under the Settings window in Testuff).

Output Formats

By default, we will send an XML format response. If you prefer, you can receive:

  • json
  • jsonp
  • xml

Just add format=json (or jsonp or yaml) to your API call.

403 Error

If you use the API without valid login details, or if you have exceeded your limit for the day (We have a throttle mechanism), we will return a 403 Forbidden error.

API Reference

The Testuff REST API allows you to query our database for data. Since the API is based on REST principles, its very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API.

Your Request Credentials

All requests to Testuff REST API require you use your Testuff login details for authentication.

Retrieving Resources with the HTTP GET Method

You access the API via HTTP. Currently all API commands are for retrieving information, which uses the HTTP GET command. The easiest way to do this is to copy and paste a URL into your web browser address bar.

Possible GET Response Status Codes

Commonly used status code are:

  • 200 OK The request was successful and the response body contains the representation requested.
  • 302 FOUND A common redirect response; you can GET the representation at the URI in the Location response header.
  • 304 NOT MODIFIED Your client cached version of the representation is still up to date.
  • 401 UNAUTHORIZED The supplied credentials, if any, are not sufficient to access the resource.
  • 403 FORBIDDEN The server understood the request but is refusing to fulfil it, usually because you are over your quota limit.
  • 404 NOT FOUND We could not find what you asked for.
  • 500 SERVER ERROR We could not return the representation. Please try again.

List of resources available in API

curl -k Will return all API entry points.
The available resources are:

  • branch
  • lab
  • suite
  • test
  • defect
  • run
  • run_comment
  • run_summary
  • test_summary

You can get the schema of each resource by fetching:
curl[RESOURCE]/schema/ -u email:password
For example, you can get the SUITE schema by:
curl -u email:password

Get resource by ID

curl -u email:password

Get list of resources

curl -u email:password
In this example we are getting all passed tests in a specific suite.

Currently supported:

  • GET /test/
    • id=TEST_ID
    • suite=SUITE_ID – Get tests that belongs to suite
    • branch=BRANCH_ID – Get tests that belongs to branch
    • req=REQ_ID – Get tests that belongs to req
    • lab=REQ_ID – Get tests that belongs to lab
    • automation_id=AUTOMATION_ID
    • summary=SUMMARY
    • summary__contains=PART_OF_SUMMARY
    • test_category=CATEGORY
    • test_category__contains=PART_OF_CATEGORY
    • priority=PRIORITY
    • last_run_status=STATUS
    • labels__name=name1,name2 – Get tests by labels (AND)
    • create_date__gt=yyyy-mm-dd
    • update_date__gt=yyyy-mm-dd
    • update_user_id=USER_ID
    • create_user_id=USER_ID
  • GET /defect/
    • branch=BRANCH_ID
    • user=USER_ID
    • run=RUN_ID
    • lab=LAB_ID
    • date=report_date__gte
    • date=report_date__lte
    • date=update_date__gte
    • date=update_date__lte
    • labels__name=name1,name2 – Get tests by labels (AND)
  • GET /suite/
    • branch=BRANCH_ID
    • parent=SUITE_ID
  • GET /run/
    • branch=BRANCH_ID
    • lab=LAB_ID
    • test=TEST_ID
    • lab__name=LAB_NAME
    • lab__name__contains=PART_OF_LAB_NAME
    • labels__name=name
    • labels__name=name1,name2 – Get tests by labels (AND)
    • comments__gte=NUMBER – Get run with comments
    • create_date=None
    • create_date__gte=yyyy-mm-dd
    • create_date__lte=yyyy-mm-dd
    • run_date__gte=yyyy-mm-dd
    • run_date__lte=yyyy-mm-dd
    • due_date__gt=yyyy-mm-dd
  • GET /run_comment/
    • id=COMMENT_ID
    • run=RUN_ID
    • lab=LAB_ID
  • GET /test_comment/
    • id=COMMENT_ID
    • test=TEST_ID
    • suite=SUITE_ID
  • GET /defect_comment/
    • id=COMMENT_ID
    • defect=DEFECT_ID
  • GET /lab/
    • branch=BRANCH_ID
    • name=LAB_NAME
    • name__contains=PART_OF_LAB_NAME
    • Add lab: POST /lab/ parameters {branch_id, parent_id, name}
    • Delete lab: DELETE lab/lab_id/
  • GET /run_summary/
    • branch=BRANCH_ID
    • lab=LAB_ID
    • suite=SUITE_ID
    • user=USER_ID
    • category=CATEGORY
    • version=VERSION
    • configuration=CONFIGURATION
    • priority=PRIORITY
  • GET /test_summary/
    • branch=BRANCH_ID
    • suite=SUITE_ID
    • user=USER_ID
    • category=CATEGORY
    • stage=STAGE
    • priority=PRIORITY

Filter by any combination of available parameters

Python 2 sample: GET run resource by LAB_ID

import urllib
import urllib2
import base64
username = "TESTUFF_LOGIN"
password = "PASSWORD"
serverUrl = ""
fields = {}
fields["lab"] = LAB_ID
data = urllib.urlencode(fields)
getUrl = "%s?%s" % (serverUrl , data)
opener = urllib2.build_opener()
request = urllib2.Request(getUrl)
request.add_header("Accept", "application/json")
encoded = base64.encodestring("%s:%s" % (username, password))[:-1]
request.add_header("Authorization", "Basic %s" % encoded)
response =, None)
except Exception, e:
print str(e)

Add resource

Currently the API supports reporting of test execution results.
In the following example we are reporting test execution results. The parameters are in XML format, and we are dumping the return header:
curl --dump-header - -H "Content-Type: application/xml" -X POST --data "" -u email:password
send HTTP POSTs with the following parameters:

  • test_id – the relevant test ID for which the result is reported.
  • status – test execution status, should be passed, failed, or wontdo.
  • steps_failed – (optional) list of failed steps. Example “1,3,5”.
  • steps_passed – (optional) list of passed steps.
  • branch_name – (optional) the name of the branch where the test result should appear.
  • lab_name – (optional) the name of the lab where the test result should appear.
  • run_configuration – (optional) specifies the run configuration used for the test.
  • comment – (optional) add a free text comment to the execution.
  • version – (optional) specifies the version used for the test.

Make sure you receive an HTTP 201 response when sending the POSTs. Otherwise something has gone wrong. If something did go wrong, there should be information in the HTTP response as to what is the problem.

The result header should include a Location result, which is the URL for the newly created run.

Attaching files to test results

curl -H “Accept: application/json” -F file=@file.png -u LOGIN:PASSWORD

What about some code examples?

Make sure to use basic authentication, with your Testuff username and password.

Python 2

#! python

import urllib2
import simplejson
import base64
username = "TESTUFF_LOGIN"
password = "PASSWORD"
serverUrl = ""
fields = {}
fields["test_id"] = TEST_ID
fields["status"] = "failed"

data = simplejson.dumps(fields)

opener = urllib2.build_opener()
request = urllib2.Request(serverUrl)
request.add_header("Accept", "application/json")
request.add_header("Content-Type", "application/json")

encoded = base64.encodestring("%s:%s" % (username, password))[:-1]
request.add_header("Authorization", "Basic %s" % encoded)
response =, data)
except Exception, e:
data = e.readline()
print str(e), data
ret = response.headers["Location"]
print ret

Python 3

#! python
import urllib.error
import urllib.request
from urllib.parse import urlencode

serverUrl = ""

# set up authentication info
auth_handler = urllib.request.HTTPBasicAuthHandler()
auth_handler.add_password(realm="Testuff API",
opener = urllib.request.build_opener(auth_handler)

#This is the query
fields = {}
fields["lab"] = "1" #assume fetching by lab id=1
data = urlencode(fields)
getUrl = "/api/v0/run/?%s" % (data)

url = "%s%s" % (serverUrl, getUrl)
res =
nodes =
print ("Response ", nodes)
except urllib.error.HTTPError as e:
print ("Error fetching from the api ", e.status)


Please install the Crypt::SSLeay module beforehand.

use HTTP::Request::Common qw(POST);
use LWP::UserAgent;

my $req = POST '',Content_Type=>"application/json",

$req->authorization_basic('xxx', 'xxxxx');
my $ua = LWP::UserAgent->new;


<!--?php $login = "TESTUFF_LOGIN_EMAIL"; $pass = "TESTUFF_PASSWORD"; $url = ""; // Replace X with the currect data-center function post_testuff($test_id , $status , $steps_failed , $steps_passed , $steps_maybe , $lab_name , $version , $run_configuration , $branch_name , $comment){ $data = array("test_id" =&gt; urlencode($test_id),&lt;br ?--> "status" =&gt; urlencode($status),
"steps_failed" =&gt; urlencode($steps_failed),
"steps_passed" =&gt; urlencode($steps_passed),
"steps_maybe" =&gt; urlencode($steps_maybe),
"lab_name" =&gt; urlencode($lab_name),
"version" =&gt; urlencode($version),
"run_configuration" =&gt; urlencode($run_configuration),
"branch_name" =&gt; urlencode($branch_name),
"comment" =&gt; urlencode($comment));

$data = json_encode($data);
global $login,$pass,$url;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $login . ':' . $pass);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER ,false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($data))


{ $info = curl_getinfo($ch);
echo $info['http_code'];
else echo curl_error($ch);

try {
} catch(Exception $e){
echo $e;


Make sure all parameters are URLEncoded, for example by using the URLEncode function.

call Main()

Sub Main()
Dim strXML 'XML request string
Dim strJSON 'JSON request string
Dim strUserName 'user name to connect to the Web API service
Dim strUserPassword 'password for the user to connect to the Web API service
Dim strWebAPIURL 'Web API service URL
Dim s_test_id, s_expected_status, s_steps_failed, s_comment

' set Web API connectivity parameters
' replace email, password and serviceX with your account details
strUserName = "your_testuff_login"
strUserPassword = "your_testuff_password"
strWebAPIURL = ""

' set test scenario parameters
s_test_id = "uhpermbpkq7gh75s3x4mwuc46janat2g"
s_status = "failed"
s_steps_passed = "3"
s_steps_failed = "2,4"
s_comment = "additional info"

'prepare Web API call data
strXML = "<!--?xml version='1.0' encoding='utf-8'?-->" &amp; _

strJSON = "{" &amp; _
EmbraceInQuotes("test_id") &amp; ":" &amp; EmbraceInQuotes(s_test_id) &amp; "," &amp; _
EmbraceInQuotes("status") &amp; ":" &amp; EmbraceInQuotes(s_status) &amp; "," &amp; _
EmbraceInQuotes("steps_failed") &amp; ":" &amp; EmbraceInQuotes(s_steps_failed) &amp; "," &amp; _
EmbraceInQuotes("steps_passed") &amp; ":" &amp; EmbraceInQuotes(s_steps_passed) &amp; "," &amp; _
EmbraceInQuotes("comment") &amp; ":" &amp; EmbraceInQuotes(s_comment) &amp; _

' Try XML Request
strResult = GetDataFromURL(strWebAPIURL, strUserName, strUserPassword, "POST", "application/xml", strXML)
MsgBox "XML input, " &amp; strResult

' Try JSON Request
strResult = GetDataFromURL(strWebAPIURL, strUserName, strUserPassword, "POST", "application/json", strJSON)
MsgBox "JSON input, " &amp; strResult
End Sub

Function EmbraceInQuotes(str)
Dim res
res = Chr(34) &amp; str &amp; Chr(34)
EmbraceInQuotes = res
End Function

Function GetDataFromURL(strURL, strLogin, strPassword, strMethod, strContentType, strPostData)
Dim lngTimeout
Dim intSslErrorIgnoreFlags
Dim blnEnableRedirects
Dim blnEnableHttpsToHttpRedirects
Dim strHostOverride
Dim strResponseText
Dim objWinHttp


lngTimeout = 59000
intSslErrorIgnoreFlags = 13056 ' 13056: ignore all err, 0: accept no err
blnEnableRedirects = True
blnEnableHttpsToHttpRedirects = True
strHostOverride = ""

Set objWinHttp = CreateObject("WinHttp.WinHttpRequest.5.1")
objWinHttp.SetTimeouts lngTimeout, lngTimeout, lngTimeout, lngTimeout
objWinHttp.Open strMethod, strURL
If strMethod = "POST" Then
objWinHttp.setRequestHeader "Content-type", strContentType
End If
If strHostOverride &lt;&gt; "" Then
objWinHttp.SetRequestHeader "Host", strHostOverride
End If
objWinHttp.Option(4) = intSslErrorIgnoreFlags
objWinHttp.Option(6) = blnEnableRedirects
objWinHttp.Option(12) = blnEnableHttpsToHttpRedirects
objWinHttp.SetCredentials strLogin, strPassword, CREDENTIALS_FOR_SERVER
On Error Resume Next
If Err.Number = 0 Then
If objWinHttp.Status = "201" Then
GetDataFromURL = "Created: " &amp; objWinHttp.GetResponseHeader("Location")
GetDataFromURL = "Error: " &amp; objWinHttp.ResponseText
End If
GetDataFromURL = "Error " &amp; Err.Number &amp; " " &amp; Err.Source &amp; " " &amp; Err.Description
End If
On Error GoTo 0
Set objWinHttp = Nothing
End Function


using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.IO;
using System.Web;
using System.Net;
using System.Collections.Specialized;

namespace WebAPIConsoleApp
class Program
static void Main(string[] args)
// set Web API connectivity parameters
// replace email, password and serviceX with your account details
string s_username = "your_testuff_login";
string s_password = "your_testuff_password";
string s_url = "";

// set test scenario parameters
string s_test_id = "TEST_ID";
string s_status = "failed";
string s_steps_failed = "1,2";
string s_comment = "my comment";
StringBuilder s_JSON_builder = new StringBuilder();
s_JSON_builder.Append("{ ");
s_JSON_builder.Append("\"" + "test_id" + "\": " + "\"" + s_test_id + "\"");
s_JSON_builder.Append(",\"" + "status" + "\": " + "\"" + s_status + "\"");
s_JSON_builder.Append(",\"" + "steps_failed" + "\": " + "\"" + s_steps_failed + "\"");
s_JSON_builder.Append(",\"" + "comment" + "\": " + "\"" + s_comment + "\"");

string s_JSON = s_JSON_builder.ToString();

string res = "";
// System.Net.HttpWebRequest adds the header 'HTTP header "Expect: 100-Continue"' to every request by default
System.Net.ServicePointManager.Expect100Continue = false;
HttpWebRequest req = (HttpWebRequest)WebRequest.Create(s_url);
req.Credentials = new NetworkCredential(s_username, s_password); //This line ensures the request is processed through Basic Authentication

req.ContentType = "application/json";
req.Method = "POST";

req.KeepAlive = true;
req.Timeout = 50000;
req.AllowAutoRedirect = false;
req.ContentLength = s_JSON.Length;

Stream s = req.GetRequestStream();
s.Write(System.Text.Encoding.ASCII.GetBytes(s_JSON), 0, s_JSON.Length);

HttpWebResponse resp = (HttpWebResponse)req.GetResponse();
res = "Created: " + resp.Headers["Location"];
catch (Exception e)
res = "Error: " + e.Message + e.Data;




require 'net/http'
require 'net/https'

# Replace host name with values from Testuff API settings screen
http ='', 443)
http.use_ssl = true
path = '/api/v0/run/'
req =
# Replace email and password with your account details
req.basic_auth '', 'password'
# edit the parameters below to fit with your data and format
req.add_field 'Content-Type', 'application/json'
data = '{"test_id": "ea87af9928ebc981284", "status": "failed"}'
req.body = data
resp, data = http.request(req)
# Output response code to the screen (we should get 201)
puts 'Code = ' + resp.code
puts 'Message = ' + resp.message
puts 'resource uri = ' + resp['location']

Backing Up Your Test Data Help Index Audit Trail