API Basics

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/v1.

All responses, except where noted, return JSON data with the content type application/json.

Clients must specify the content type application/json when creating or updating data.

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 the number of milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC) unless otherwise noted.

For example, the timestamp 1525724473431 translates to "May 7, 2018, 4:21:13 PM EDT" in the US/Eastern time zone or "May 7, 2018, 1:21:13 PM PDT" in the US/Pacific time zone.

Each subject in a study has a time zone, one of:

  • Asia/Tokyo

  • US/Alaska

  • US/Aleutian

  • US/Arizona

  • US/Central

  • US/East-Indiana

  • US/Eastern

  • US/Hawaii

  • US/Indiana-Starke

  • US/Mountain

  • US/Pacific

  • US/Samoa

  • Canada/Atlantic

  • Canada/Central

  • Canada/Eastern

  • Canada/Mountain

  • Canada/Newfoundland

  • Canada/Pacific

  • Canada/Saskatchewan

  • Canada/Yukon

Converting timestamps into locale-sensitive strings requires a date/time library with time zone support, such as datetime.py or Moment.js. In your code, you might use a recording timestamp and a subject time zone as follows:

DATE_TIME = DT.FROM_MILLIS(recording.recordingStartTs)
TIME_ZONE = TZ.FROM_STRING(subject.timezone)
DT_STRING = DT.TO_STRING("ddd, MMM D, YYYY h:mm:ss A", TIME_ZONE)

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

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

DURATION_IN_MINUTES = (STOP_TIMESTAMP - START_TIMESTAMP) / 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.

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

HTTP Status Codes

The API returns the following HTTP status codes:

  • 200 Success

  • 201 Success (Created)

  • 202 Accepted

  • 204 Success (No content)

  • 303 See other (Redirect)

  • 400 Malformed request

  • 401 Invalid API credentials

  • 403 Unauthorized access

  • 404 Not found

  • 409 Conflict

  • 413 Payload too large

  • 415 Unsupported media type

  • 429 Too many requests

  • 498 Expired API access token

  • 500 Internal server error

  • 503 Service unavailable

As a rule, you should inspect the response status code before attempting to evaluate the response body. A status code in the 200-204 range means your request was successful; all others indicate some kind of failure.

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