Back to Customer API documentation

 

Introduction

 

The Litmus customer API gives you complete access to your Litmus account programmatically. There are lots of exciting ways you can use this facility to develop your own add-on tools and features. For example, you might like to integrate your test results from Litmus into your design agency's intranet. Or, you might like to write a tool which makes testing fit even better into your personal workflow. You could even re-create the functionality found in our web-based application as a native Windows or OS X application. There are limitless possibilities for development using our API. The Litmus API was used to implement our own Alkaline OS X Desktop application.

 

The API is implemented as RESTful XML over HTTP. Each part of our service - such as tests, versions, etc. - has its own URL. As such, it is possible to easily work with the Litmus API in a wide variety of programming languages.

 

Licensing terms

 

We want to encourage active development of software with our API, but please remember that you are not permitted to resell our testing facility through this API. You are welcome to make use of this API within your own commercial software, but your users must be required to purchase their own individual Litmus account from us, in order to make use of any testing features you provide. If you wish to sell a testing service under your own branding, we'd be delighted to help you with that. Take a look at our integration options if that's what you're interested in doing.

 

Additionally, we have a fair usage limit in place to restrict very high levels of usage via the API. This is so as to keep the system responding quickly for all users. This API is not intended for high volume testing. If you have an application which will require high levels of testing, please contact us in advance so we can provision additional resources and arrange a custom price plan for your company.

If you have any questions about the license and usage terms, please email us and we'll be happy to help.

 

Overview

 

The diagram below should help to give you an overview of the relationships between resources within Litmus.

 

 

A test can be a test of a web page or an email. Each time a web page or email is re-tested, a new version is created. For each version, there are multiple results - one for each web browser or email client which the page/email was tested against. These results are made up of multiple result images (screenshots). An email result, for example, will have screenshots for both the email as it appears in a user's inbox, and when it is opened full screen. Finally, each result also has information about the testing application which was used - for instance whether it was a web-based email service.

 

To explore the API initially, you should have a go with curl (available on OS X and Unix systems) or the online service hurl, following the examples in these documents, to perform some GET requests on different parts of the application. This will let you see the XML responses Litmus will return and give you a good feel for the type of data that's returned. 

 

 

Authentication

 

To use the API you'll need a Litmus account. If you don't already have one, you can sign up here. You'll then use your regular login credentials to authenticate for access via the API. There is no special API key required. We use HTTP Basic Authentication to request your username and password when accessing the API.

 

The url you use to access Litmus is based on the account key you chose when you signed up, e.g. if your Litmus account is located at companyx.litmus.com, your username is "john" and your password is "secret", then you could use curl to load a list of the tests in your account by running.

 

curl -u john:secret http://companyx.litmus.com/tests.xml

Of course, if you change your username or password from within Litmus, you'll need to use your new credentials to access the API as well.

Please note that if you have SSL enabled on your account for additional security, you'll need to use the "https://" prefix on all URLs when interacting with the API. If you do not do this then the API will return a 302 redirect to the https url, likely your client will not recover from this and it will show as an error, so please check this first.

 

 

Reading data via the API

 

When you read data via the Litmus API, you'll be given either an individual piece of data, or a collection of data. For example, if you perform a GET request on the /tests.xml URL, you'll be sent the data for every test that is present in your account.

 

curl -u john:secret http://companyx.litmus.com/tests.xml

However, if you address a specific test ID, then you'll be sent data for just that individual test (in this case the test with ID "1234"):

 

curl -u john:secret http://companyx.litmus.com/tests/1234.xml

When your request is successful, we'll return a "200 OK" status code. You can read more about the XML data you'll receive back from Litmus - and the requests you can make - in the other sections of this documentation.

 

 

Writing data via the API

 

You can also update, delete and create tests and other data easily via the API. To do this, you'll be sending XML data to Litmus. You need to let the system know that by adding the header "Content-type: application/xml", so we know that it's not form-encoded data coming in. Then you include the XML of the resource in the body of your request.

 

Here are two examples of creating new web page tests in Litmus. For more information about creating tests see the Tests reference. The first example shows the XML inline, the second references the XML from an external file:

 

curl -u john:secret -H 'Content-Type: application/xml' -d '<test_set><url>http://google.com</url> \
<use_defaults>true</use_defaults></test_set>' http://companyx.litmus.com/pages.xml

Conventions in this documentation

 

In the rest of this API documentation, we'll be using the following conventions: