MC10 Developer Documentation (Rev. 5/20/2019)

API Overview

The MC10 API is intended for customers who want to work with BioStamp® nPoint™ data using their own tools and methods. It is meant to supplement, not replace, MC10's FDA-regulated products, including the BioStamp® nPoint™ Investigator Portal and BioStamp® nPoint™ Link app.

Architecture

The MC10 API is a RESTful web service, allowing clients to manage data through standard HTTP methods (GET, POST, PUT and DELETE).

The base URL is https://mc10cloud.com/api.

Security

All API requests must use HTTPS and basic access authentication.

Rate Limits

API calls are limited to 10 requests per second. If you exceed this rate, the API will return a 429 status code.

Dates and Times

Dates are expressed as UTC timestamps (milliseconds since the Unix epoch) unless otherwise noted.

Acceptable time zones (where applicable) are Asia/Tokyo, US/Alaska, US/Aleutian, US/Arizona, US/Central, US/East-Indiana, US/Eastern, US/Hawaii, US/Indiana-Starke, US/Michigan, US/Mountain, US/Pacific, US/Samoa, Canada/Atlantic, Canada/Central, Canada/Eastern, Canada/Mountain, Canada/Newfoundland, Canada/Pacific, Canada/Saskatchewan, and Canada/Yukon.

Converting a UTC timestamp (e.g. 1556629241236) into a local date (e.g. "4/30/2019, 9:00:41 AM EDT") according to a specific time zone (e.g. "US/Eastern") is beyond the scope of the API.

Other Units

Weight and height are expressed in kilograms and meters, respectively. In your code, you can convert these values to imperial units as follows:

WEIGHT_IN_POUNDS = WEIGHT_IN_KILOS * 2.20462
HEIGHT_IN_INCHES = HEIGHT_IN_METERS * 39.3701

Event durations, such as the amount of time a subject performed an activity, are not explicitly provided. Rather, the API provides boundary timestamps in UTC milliseconds. In your code, you can compute an actual duration as follows:

DURATION_IN_MINUTES = (STOP_TIME_UTC - START_TIME_UTC) / 60000

File size is expressed in bytes. In your code, you can convert bytes to megabytes as follows:

SIZE_IN_MEGABYTES = SIZE_IN_BYTES / 1048576

Acceleration is expressed as gravitational force, or g-force.

Rotation is expressed in degrees per second.

Electrical potential is expressed in volts.

Data Structures

Some data structures contain optional properties. For example, a subject may or may not have a value for weight. In these cases, the property itself is ommitted entirely from the API response. Below, one subject has a value for weight and one does not:

[
  {
    "accountId": "5d3b5905-1b00-11e7-8464-0a624d7022db",
    "createdTs": 1525723958162,
    "displayName": "sub01",
    "gender": "MALE",
    "height": 1.6002,
    "id": "fd053720-5232-11e8-8695-028eb5a65596",
    "modifiedTs": 1525726299410,
    "studyId": "f7888550-4f14-11e8-a47c-028eb5a65596",
    "timezone": "US/Eastern",
    "weight": 55.791816
  },
  {
    "accountId": "5d3b5905-1b00-11e7-8464-0a624d7022db",
    "createdTs": 1525713548568,
    "displayName": "sub02",
    "gender": "MALE",
    "height": 1.8542,
    "id": "c06b3980-521a-11e8-a47c-028eb5a65596",
    "modifiedTs": 1525723165399,
    "studyId": "f7888550-4f14-11e8-a47c-028eb5a65596",
    "timezone": "US/Eastern"
  }
]

Error Handling

Some responses might return an error object along with an HTTP status code in the 400 range. The following example shows the result of a request containing a malformed ID:

{
  "details": [],
  "message": "INVALID_UUID_FORMAT",
  "type": "bad_request"
}