Getting Started

Overview

As the premium Interactive Video platform, we pride ourselves in proving the best-in-class solution to our customers needs. In addition to providing a sleek and intuitive interactive video experience, we also provide a comprehensive API that allows our users to retrieve and utilize their Mindstamp data. Mindstamp offers a JSON REST API that provides users the ability to retrieve data for views, viewers, videos, interactions, users, and more for use in their own applications.

Semantics

To access the API, it is important to understand how our endpoint is constructed. An endpoint is a URL that allows you to talk to the Mindstamp servers to extract your data. The root endpoint for the Mindstamp API is https://api.mindstamp.com. Since our API is constantly evolving and providing more functionality, we use a versioning system. The current version of the API is v1. Piecing these together, the resulting endpoint for the current version of the Mindstamp API is https://api.mindstamp.com/api/v1/.

Authentication

In order to authenticate requests made to the Minstamp API, customers with access to the API will be provided a Bearer token which must be included in all requests made to the API. A typical bearer token will look like this tuG4rqqTS_Df7Ma0W73SrzTATkSyH-D7s7NAU2JHPGQ. This token is a secret and must be kept confidential. Therefore, It should not be shared anywhere or checked into any public code repository. Additionally, the bearer tokens do not expire but they can be expired and refreshed by Mindstamp in the event of a leak or business disruption.

Requests

The API can be integrated in all major programming languages including Javascript, Python, Ruby, Java, and many more. To demonstrate how to make API requests, we will look at a basic cURL GET request to retrieve a single video. Assuming access to the video with the ID of KMxPjRVlrPnH, we can use the request to pull a single video (see the Endpoints table below).

curl https://api.mindstamp.com/api/v1/videos/KMxPjRVlrPnH -H "Authorization: Bearer tuG4rqqTS_Df7Ma0W73SrzTATkSyH-D7s7NAU2JHPGQ"

The JSON response will look like:

{
  {
		"id":"5e358f49-fb1f-400a-9abf-5bd5d71839e6",
		"token":"KMxPjRVlrPnH",
		"title":"Interactive Video #12",
		"message":"Created on Mindstamp! This message is customizable",
		"created_at":"2020-10-28T19:10:34.748Z",
		"duration":45,
		"link":"https://api.mindstamp.com/watch/KMxPjRVlrPnH",
		"thumbnail":"https://mindstamp-resources.s3-us-west-2.amazonaws.com/..."
	}
}

Response Codes

Your program should always check the response code to indicate a successful response. The most common response codes from the API will be those used across HTTP applications:

• 200 - Success
• 401 - Not Authorized
• 404 - Not Found
• 422 - Unprocessable Entity
• 5xx - Error
• 503 - Rate Limit Exceeded

Rate Limiting and Pagination

The Mindstamp API is rate limited and some endpoints are paginated to avoid sending large amounts of unnecessary data. The rate limits for enterprise customers are as follows:

• 1,000 Calls Per Hour
• 100 Calls Per Minute

Subsequent requests will be throttled. If you need to increase these limits, please contact your account representative to discuss options.

Pagination is controlled by the limit and offset parameters. The default limit is 25, but can be set to retrieve up to 250 results per call. The offset parameter determines how many results are skipped before returning results.

So, to retrieve the first 50 interactions for a viewer, you would call call:

curl https://api.mindstamp.com/api/v1/videos/KMxPjRVlrPnH/interactions?limit=50 -H "Authorization: Bearer tuG4rqqTS_Df7Ma0W73SrzTATkSyH-D7s7NAU2JHPGQ"

To retrieve interactions 51 - 151 (if exists), the next call would be:

curl https://api.mindstamp.com/api/v1/videos/KMxPjRVlrPnH/interactions?offset=50&limit=250 -H "Authorization: Bearer tuG4rqqTS_Df7Ma0W73SrzTATkSyH-D7s7NAU2JHPGQ"

Response Objects

Successful requests return one or many JSON objects.

A JSON object field that does not have data will come back as null. Your application should not assume that any field is populated.

Endpoints

The following API endpoints are available. For full documentation and parameters, please contact your account representative.