In this post we list the basics of the TestLodge API, including the base URL, authentication, validation errors, response codes and time zones.
The TestLodge REST API provides endpoints for all common features and is available over JSON.
You will call the API from a slightly different url from your normal account. This takes the format of:
So if you normally access your TestLodge account via http://example.testlodge.com your API url will be https://example.api.testlodge.com. In the rest of the documentation we may refer to this URL as the 'base_url'.
Please note: All API requests are performed over HTTPS and HTTP calls will not be accepted.
Access to the API is provided by basic authentication and you should use a users email address / API key to authenticate each request.
To generate an API key, visit the TestLodge account that you wish to access and navigate to 'My profile' -> 'API keys'.
curl -u email:api_key https://example.api.testlodge.com/v1/projects.json
Your access permissions for the API will be the exact same as your access permissions that you have within the application.
For all API requests, you can make up to 300 requests per five minute period. If you exceed this limit, you will be shown a forbidden error page.
If there are validation errors when you are attempting to create or update an object, you will receive a 422 response code and the response body will contain further details. e.g.
"name": ["can't be blank", "..."],
"description": ["can't be blank"]
TestLodge will always return a http response code with every request and you should consider this when checking that your API call has been successful. The most common response codes that you can expect are:
- 200 - OK
- 201 - Created
- 204 - No content (Most likely after a request to delete an object)
- 400 - Bad request
- 401 - Unauthorized
- 403 - Forbidden
- 404 - Not found
- 409 - Conflict
- 415 - Unsupported media type (Make sure your requests end with .json)
- 422 - Unprocessable Entity (Most likely a validation error - See body for further details)
All date / timestamps provided within the API are in UTC.