API - Basics

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.

Base URL

You will call the API from a slightly different url from your normal account. This takes the format of:

https://api.testlodge.com/v1/account/{account_id}/

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.

Account ID

When calling an API endpoint you will need to include your account ID, this can be found in the URL when you access your TestLodge account in the browser. So if you normally access your TestLodge account at https://app.testlodge.com/a/1/ your API base url will be https://api.testlodge.com/v1/account/1/.

Authentication

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'.

Example call:

curl -u email:api_key https://api.testlodge.com/v1/account/1/projects.json

Your access permissions for the API will be the exact same as your access permissions that you have within the application.

Rate Limiting

For all API requests, you can make up to 300 requests per five minute period. If you exceed this limit, a 429 error code will be returned.

Validation Errors

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"]
}

Response Codes

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)
• 429 - Too many requests

Time Zones

All date / timestamps provided within the API are in UTC.