These docs are for v1.0. Click to read the latest docs for v2.0.

The Taplytics API is a REST based endpoint for remotely accessing data from Taplytics.
Note: API access is only available to users on an Enterprise plan.

API Endpoint

The API endpoint is available at https://api.taplytics.com.

Authentication

All access to the Taplytics API is done using token based authentication. Multiple API keys can be used at the same time, and they can be managed via your account.

Also, note that all requests must be made via https. Any requests over http will be denied.

Authentication is done through your project's REST API Key. This can be found on the left sidebar under 'Settings' for your project. Every request you send through the API must contain this key. It can either be sent as a query parameter called api_token. Example:

https://api.taplytics.com?api_token=e3dddfb4068e-414a-92f1-390ha54603ff

Or, it can be sent in the body of a POST request, if that happens to be what you're sending to the API:

{
    "api_token": "3dddfb4068e-414a-92f1-390ha54603ff"
}

Or, lastly, it can be sent as an HTTP header called x-access-token.

HTTP Responses & Errors

Taplytics uses standard HTTP status codes to identify whether requests are succesful or have failed.

  • 200 OK - All systems go!
  • 204 No Content - The record was succesfully deleted
  • 400 Bad Request - Something's missing (probably a parameter)
  • 401 Unauthorized - Invalid API key
  • 402 Request Failed - The parameters in your request were valid, but something failed
  • 404 Not Found - The request item does not exist
  • 50x Server Error - Something else went wrong

Custom Data

Most user updatable objects in Taplytics support custom_data as a parameter. The custom_data object is a key:value store for any custom data that you would like to associate with that object.

For example, if you would like to store a custom user id, you can pass the following type of data in to your user object:

{
    "custom_data":
    {
        "my_user_id" : "12345",
        "first_name" : "Paul",
        "last_name"  : "Graham"
    }
}

Webhooks

Taplytics also supports webhooks as a way to be notified when changes occur. These are included with all enterprise plans, and support a number of events, such as:

  • A new user is added
  • A user starts an experiment
  • A new experiment is started
  • Experiment results have reached confidence

Pagination

When querying collections of data, such as multiple users, push notifications, etc, the Taplytics API uses pagination to return the data. This is done through specifying a page, the number of the page of data you wish to access, as well as the number of unique records you wish to see per_page.

So, if somebody had 100 users they have to GET, they could query https://taplytics.com/users?page=1&per_page=50 to get the first 50 users and https://taplytics.com/users?page=2&per_page=50 to get the last 50 users they have. All collections in the API are sorted by the default time at which they were created.

To crawls large sets of data, the client will often query the data and then traverse through the next pages of the document automatically to get more data. It is not recommended that you try and guess the constructed URLs for pagination.

Thus, Taplytics provides all paginated responses with a Link header included. This header will provide the first and last page of the document, as well as the previous and next page, if available. So, to query a project that has roughly 400 hundreds on the third page of data with 100 users per page would look like:

https://api.taplytics.com/v2/users?api_token=YOUR_API_TOKEN&page=3&per_page=100

With a Link header:

Link: <https://api.taplytics.com/v2/users?api_token=YOUR_API_TOKEN&page=4&per_page=100>; rel='last', <https://api.taplytics.com/v2/users?api_token=YOUR_API_TOKEN&page=2&per_page=100>; rel='next', <https://api.taplytics.com/v2/users?api_token=YOUR_API_TOKEN&page=1&per_page=100>; rel='first'"

Please note that by default, accounts have a pagination limit of 100 items per page.