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 API is implemented as XML over HTTP. Each part of our service - such as tests, versions, etc. - has its own URL. The aim has been to make it fully RESTful. 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 may wish to use Firefox to perform some GET requests on different parts of the application. This will let you see the XML response inside your browser, and give you a good feel for the type of data that's returned. You can see an example of this in the screenshot on the right. Most of the URLs within Litmus can be viewed as XML by appending the ".xml" file extension. For example, /tests/1234 becomes /tests/1234.xml.
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.
Curl is a really useful command line tool to explore the API before you begin writing your own code. For example, if your Litmus account is located at companyx.litmusapp.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.litmusapp.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.
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.litmusapp.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.litmusapp.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.litmusapp.com/pages.xml
curl -u john:secret -H 'Content-Type: application/xml' -d @test.xml http://companyx.litmusapp.com/pages.xml
When you successfully create something we'll respond with a "201 Created" status code. We'll also include the full XML data describing the new object in the response. This will include additional data such as the 'created at' time which is added by our system upon creation.
You can also delete data using the API. This uses the DELETE verb. For example, to delete a test:
curl -u john:secret -X DELETE http://companyx.litmusapp.com/tests/1234.xml
The response to a successful deletion is "200 OK".
Errors
If there is a problem with any request, we'll respond with an error message to let you know what went wrong, along with XML data describing the error, if applicable. As a simple example, if you request details of a test which doesn't exist we will return:
404 Record not found
Conventions in this documentation
In the rest of this API documentation, we'll be using the following conventions:
#{text}Indicates text that should be replaced by your own data.\Indicates that the code continues on the same line....Indicates content from the response has been edited for brevity. See the data reference page for a full description of the format of that response type.