HealthLytix API

Welcome to our API!

Please Note This API is still in beta version and is subject to drastic changes until we release the official version. If you have any issues, please email us at support@healthlytix.com

VERSION: 0.2.2

Getting Started

With the HealthLytix API, you can run/execute our cloud apps programmatically, query and retrieve data/results from apps, test different endpoints before pushing to production, and much more.

After reading through this section, be sure to check out the API Reference to see all available API requests below.

NodeJS SDK

Install with NPM

npm install hytx-sdk-js --save

We have an SDK for NodeJS to make it easier and faster to start using our APIs. You can install it with npm. More information at Github or at NPM

API Address

Use the address below when making api calls

SSL

We give a valid, signed certificate for all API methods. If you’re manually coding submit URLs, change http to https in the URL, and make sure your connection library supports HTTPS. We strongly recommend using only https method when interacting with our API.

Authentication

Using our SDK

// to install our sdk, do the following 'npm install hytx-sdk --save'
const HealthLytix = require('hytx-sdk-js');

// this initializes the api with the correct authentication token
const hytx = new HealthLytix(`yourApiId`, `yourApiSecret`);

Make sure to replace yourApiId and yourApiSecret with your API ID and Secret.

To authenticate, we use HTTP Basic authentication. Before using our API, please generate an API token. A token consists of an apiId and a apiSecret. Each token is tied to the organization under which the token was generated.

You can register a new HealthLytix API key here.

Unless specified otherwise, the API key is to be included in all API requests in a header that looks like the following:

Header	Value
Authorization	apiId <your-api-id> apiSecret <your-api-secret>

Ping

Headers

Authorization: apiId <your-api-id> apiSecret <your-api-secret>

Response

{
    "message": "Pong! Hi! this is the Healthlytix API  ( ͡° ͜ʖ ͡°)!"
}

Using our SDK

const HealthLytix = require('hytx-sdk-js');
const hytx = new HealthLytix(`yourApiId`, `yourApiSecret`);

hytx.ping((err, msg) => {})

// or with promises
hytx.ping()
    .then(msg => console.log(msg))
    .catch(e => console.log(e));

Use this endpoint to test that you can authenticate and talk to the Healthlytix API.

Datalake

All relatively large data types, including DICOMs and Genetic data sets, will sometimes require to be uploaded to the HealthLytix Cloud through Datalake service by using one of the methods below. If unsure whether you need to use one of these methods, please refer to the API Endpoint of the app you want to run/execute. Each of our cloud apps will have instructions on how to deal with file uploads.

Upload A File

Headers

Content-Type: application/json
Authorization: apiId <your-api-id> apiSecret <your-api-secret>

Body

{
  "type": "<content-type>" 
}

Response

{
    "requestId": "a2c87d60-f659-11e7-acc4-017cb11fad99",
    "uploadURL": "https://sample-presigned-url" 
}

How to upload using the Presigned-URL obtained above

const request = require('request')
const fs = require('fs');

// ...perform POST command from above the get presigned URL

// read the file
fs.readFile(file, (err, data) => {
  // prepare PUT request for upload file
  let options = {
    method: 'PUT',
    uri: preSignedUrl, // came from above POST command
    headers: { "content-type": "<the-content-type-used-when-getting-presigned-url>" },
    body: data // this is the data of the file read using the fs module
  }

  // PUT request 
  request(options, (err, response, body) => {});
})

Using our SDK

const HealthLytix = require('hytx-sdk-js');
const hytx = new HealthLytix(`yourApiId`, `yourApiSecret`);

// with callback
hytx.uploadFile(file, contentType, (err, requestId)=>{})

// with promises
hytx.uploadFile(file, contentType)
    .then(requestId => {})
    .catch(err => /* handle error */);

This endpoint retrieves a pre-signed URL to be used when uploading the file. After receving the pre-signed URL, you will need to upload the file using a PUT request to that url with the correct Content-Type header specified. It also returns a requestId, which will be used when running the specific app that requires this file. The requestId acts as an identifier of the file that will be uploaded. Some apps will also specify the lifecycle management for the data being uploaded. Generally all files uploaded are deleted after being processed with our cloud apps, unless specified otherwise.

Prerequisites

Condition	Description
None

POST Body Parameters

Param	Description
type	(string) The Content-Type of the file to be uploaded which conforms to the MIME type standards.

Alzheimers PHS

This section covers how to use our Alzheimers PHS cloud app through our API. This app generates a report based on a subject's genetic data gathered from 23andMe, Ancestry.com or some other similar genotype reporting service.

Run Algorithm

Headers

Content-Type: application/json
Authorization: apiId <your-api-id> apiSecret <your-api-secret>

Body

{
  "requestId": "123456789ABCDEFG",
  "age": 70 
}

Response

{
    "success": true,
    "ancestralWarning": false,
    "apoeWarning": false,
    "snpsWarning": false,
    "requestId": "6f370e30-f4b0-11e7-8abf-919aafdd8e30",
    "inputFile": "23andMe",
    "phsReport": {
        "irTable": [
            {
                "age": 60,
                "percentiles": [
                    {
                        "value": 0.084,
                        "label": "baseline"
                    },
                    {
                        "value": 0.019255375043071715,
                        "label": "1st"
                    },
                    {
                        "value": 0.041570487791937075,
                        "label": "20th"
                    },
                    {
                        "value": 0.12618730680900586,
                        "label": "80th"
                    },
                    {
                        "value": 0.41793121094027325,
                        "label": "99th"
                    },
                    {
                        "value": 0.0746904926899343,
                        "label": "55th"
                    }
                ]
            }
            // and more...
        ],
        "personal": [
            {
                "age_dt": 70,
                "risk_dt": 0
            },
            {
                "age_dt": 70.01,
                "risk_dt": 0.00003554387664350678
            },
            {
                "age_dt": 72.98000000000152,
                "risk_dt": 0.012227384821087095
            },
            {
                "age_dt": 72.99000000000153,
                "risk_dt": 0.012274238187628628
            }
        ],
        "cumulative": [
            {
                "e4Survival": 0.9983167185377051,
                "risk": 0.00046744083944356794,
                "survival": 0.9995326683940049,
                "ageVals": 60,
                "baselineSurvival": 0.9991603527012367,
                "baselineRisk": 0.000840000000000032,
                "e4Risk": 0.0016846997723691498
            },
            {
                "e4Survival": 0.9963801222218583,
                "risk": 0.001006202235558712,
                "survival": 0.9989943038161664,
                "ageVals": 61,
                "baselineSurvival": 0.998193469359609,
                "baselineRisk": 0.0018081643847710671,
                "e4Risk": 0.0036264453897972672
            },
            {
                "e4Survival": 0.994152706310828,
                "risk": 0.001627166039854288,
                "survival": 0.9983741570770654,
                "ageVals": 62,
                "baselineSurvival": 0.9970802228181339,
                "baselineRisk": 0.002924048046603476,
                "e4Risk": 0.0058644560458442204
            },
            // ...
        ],
        "currentPoint": {
            "survival": 0.9817219979369073,
            "baselineRisk": 0.34751811698111695,
            "risk": 0.30900356399997436
        }
    }
}

Using our SDK

const HealthLytix = require('hytx-sdk-js');
const hytx = new HealthLytix(`yourApiId`, `yourApiSecret`);

// how to run the Alzheimers PHS app
const subjectAge = 70;
const file = "/path/to/my/file";
const fileContentType = "text/plain";

// 1) first upload the file and get a requestId
hytx.uploadFile(file, fileContentType)
.then(requestId => {
    // file uploaded!
    // 2) run the Alzheimers PHS algo on the HealthLytix cloud
    hytx.runAlzheimersPHS(requestId, subjectAge)
    .then(results => {
        // hooray! it worked
        // results has the report
    })
    .catch(e => /* handle error */);
})
.catch(e => /* handle error */);

Use this endpoint to run the Alzheimers PHS app and process the genetic file.

Prerequisites

In order to use this endpoint, you will need to first upload the genetics file to be processed by Alzheimers PHS using either our Datalake Service data/getUploadUrl endpoint or our SDK.

Condition	Description
Genetics File Uploaded	File uploaded through the Datalake Service. File must be a 23andMe, Ancestry.com, or a VCF formatted file. File can be uploaded in a zip, gzip or tarfile, as long as as it is the only file inside the compressed file.

POST Body Parameters

Param	Description
requestId	(string) From the file upload API call response
age	(number) Subject's age

JSON Response

Key	Description
success	(boolean) true if the processing did not encounter any issues or QA failures that would deem the report not trustworthy. This will be false if ancestralWarning, apoeWarning, or snpsWarning are true
ancestralWarning	(boolean) true if the Ethnicity QA check failed. This could be true if the Ethnicity derived from the SNPs data is not supported by our model
apoeWarning	(boolean) true if APOE variants cannot be inferred from the SNPs data
snpsWarning	(boolean) true if the number of SNPs were missed below the specified threshold, comparing to the union sets of all available SNPs from 23andMe and Ancestry.com plateforms
requestId	(string) Original request ID sent with request
inputFile	(string) Type of genetics file detected by our algorithm
phsReport :	(Object) The PHS report object with the results of the algorithm
=> irTable	(Array[]:Object) Array of objects. Object Definition
=> personal	(Array[]:Object) Array of objects. Object Definition
=> cumulative	(Array[]:Object) Array of objects. Object Definition
=> currentPoint	(Object) Object Definition

Object Definition - irTable

Key	Description
age	(number) User input age
percentiles :	(Array[]:Object) PHS percentiles
=> value	(number) The annualized risk for Alzheimer's disease (Instantaneous risk)
=> label	(string) The percentile values. The last value is the personalized PHS percentile while the others are for the reference purpose.

Object Definition - personal

Key	Description
age_dt	(number) Age for interpolation, starting from current age, then extending to 3 years afterwards
risk_dt	(number) Personalized risk, assuming client has no signs of disease at all. Predicting for the risks in the following 3 years.

Object Definition - cumulative

Key	Description
e4Survival	(number) The cumulative disease-free proportions among individuals with APOE e4 variant
risk	(number) The cumulative disease risk for individuals with the same genetic profile as client
survival	(number) The cumulative disease-free proportions for individuals with the same genetic profile as client
ageVals	(number) Corresponding age points
baselineSurvival	(number) The median of the cumulative disease-free proportions among all people in USA
baselineRisk	(number) The median of the cumulative disease risk among all people in USA
e4Risk	(number) The cumulative disease risk among individuals with APOE e4 variant

Object Definition - currentPoint

Key	Description
risk	(number) Predicted age-dependent cumulative risk of disease for the client
survival	(number) Predicted cumulative disease-free proportions for the client
baselineRisk	(number) The median of the cumulative disease-free proportions among all people in the same age of the client

Retrieve Results

Headers

Authorization: apiId <your-api-id> apiSecret <your-api-secret>

Response

{
    "success": true,
    "ancestralWarning": false,
    "apoeWarning": false,
    "snpsWarning": false,
    "requestId": "6f370e30-f4b0-11e7-8abf-919aafdd8e30",
    "inputFile": "23andMe",
    "phsReport": {
        "irTable": [],
        "personal": [],
        "cumulative": [],
        "currentPoint": {}
    }
}

Using our SDK

const HealthLytix = require('hytx-sdk-js');
const hytx = new HealthLytix(`yourApiId`, `yourApiSecret`);

// this shows how to retrieve 
// a previously calculated result.
// use the same requestId as runAlzheimersPHS()
hytx.getAlzheimersPHS(requestId)
    .then(report => /* report has the results */)
    .catch(e => /* handle error */ );

Use this endpoint to retrieve some previously calculated results from the Alzheimer's PHS Algorithm

Prerequisites

Condition	Description
Genetics File Processed	A request already completed previously with app-alzgenic/run-app

GET URL Query Parameters

Param	Description
requestId	(string) Same as the one used when running app-alzgenic/run-app

JSON Response

Key	Description
Refer to description	Response is same as app-alzgenic/run-app. Refer to its response for more details.

Prostate Cancer PHS

This section covers how to use our Prostate Cancer PHS cloud app through our API. This app generates a report based on a subject's genetic data gathered from 23andMe, Ancestry.com, or VCF file.

Run Algorithm

Headers

Content-Type: application/json
Authorization: apiId <your-api-id> apiSecret <your-api-secret>

Body

{
  "requestId": "123456789ABCDEFG",
  "age": 70 
}

Response

{
    "success": true,
    "ancestralWarning": false,
    "snpsWarning": false,
    "requestId": "6f370e30-f4b0-11e7-8abf-919aafdd8e30",
    "inputFile": "23andMe",
    "phsReport": {
        "irTable": [
            {
                "age": 60,
                "percentiles": [
                    {
                        "value": 0.084,
                        "label": "baseline"
                    },
                    {
                        "value": 0.019255375043071715,
                        "label": "1st"
                    },
                    {
                        "value": 0.041570487791937075,
                        "label": "20th"
                    },
                    {
                        "value": 0.12618730680900586,
                        "label": "80th"
                    },
                    {
                        "value": 0.41793121094027325,
                        "label": "99th"
                    },
                    {
                        "value": 0.0746904926899343,
                        "label": "55th"
                    }
                ]
            }
            // and more...
        ],
        "personal": [
            {
                "age_dt": 70,
                "risk_dt": 0
            },
            {
                "age_dt": 70.01,
                "risk_dt": 0.00003554387664350678
            },
            {
                "age_dt": 72.98000000000152,
                "risk_dt": 0.012227384821087095
            },
            {
                "age_dt": 72.99000000000153,
                "risk_dt": 0.012274238187628628
            }
        ],
        "cumulative": [
            {
                "risk": 0.00046744083944356794,
                "survival": 0.9995326683940049,
                "ageVals": 60,
                "baselineSurvival": 0.9991603527012367,
                "baselineRisk": 0.000840000000000032,
            },
            {
                "risk": 0.001006202235558712,
                "survival": 0.9989943038161664,
                "ageVals": 61,
                "baselineSurvival": 0.998193469359609,
                "baselineRisk": 0.0018081643847710671,
            },
            {
                "risk": 0.001627166039854288,
                "survival": 0.9983741570770654,
                "ageVals": 62,
                "baselineSurvival": 0.9970802228181339,
                "baselineRisk": 0.002924048046603476,
            },
            // ...
        ],
        "currentPoint": {
            "survival": 0.9817219979369073,
            "baselineRisk": 0.34751811698111695,
            "risk": 0.30900356399997436
        }
    }
}

Using our SDK

const HealthLytix = require('hytx-sdk-js');
const hytx = new HealthLytix(`yourApiId`, `yourApiSecret`);

// how to run the Prosate PHS app
const subjectAge = 70;
const file = "/path/to/my/file";
const fileContentType = "text/plain";

// 1) first upload the file and get a requestId
hytx.uploadFile(file, fileContentType)
.then(requestId => {
    // file uploaded!
    // 2) run the Prostate PHS algo on the HealthLytix cloud
    hytx.runProstatePHS(requestId, subjectAge)
    .then(results => {
        // hooray! it worked
        // results has the report
    })
    .catch(e => /* handle error */);
})
.catch(e => /* handle error */);

Use this endpoint to run the Prostate PHS app and process the genetic file.

Prerequisites

In order to use this endpoint, you will need to first upload the genetics file to be processed by Prostate PHS using either our Datalake Service data/getUploadUrl endpoint or our SDK.

Condition	Description
Genetics File Uploaded	File uploaded through the Datalake Service. File must be a 23andMe, Ancestry.com, or a VCF formatted file.

POST Body Parameters

Param	Description
requestId	(string) From the file upload API call response
age	(number) Subject's age

JSON Response

Key	Description
success	(boolean) true if the processing did not encounter any issues or QA failures that would deem the report not trustworthy. This will be false if ancestralWarning, apoeWarning, or snpsWarning are true
ancestralWarning	(boolean) true if the Ethnicity QA check failed. This could be true if the Ethnicity derived from the SNPs data is not supported by our model
snpsWarning	(boolean) true if the number of SNPs were missed below the specified threshold, comparing to the union sets of all available SNPs from 23andMe and Ancestry.com plateforms
requestId	(string) Original request ID sent with request
inputFile	(string) Type of genetics file detected by our algorithm
phsReport :	(Object) The PHS report object with the results of the algorithm
=> irTable	(Array[]:Object) Array of objects. Object Definition
=> personal	(Array[]:Object) Array of objects. Object Definition
=> cumulative	(Array[]:Object) Array of objects. Object Definition
=> currentPoint	(Object) Object Definition

Object Definition - irTable

Key	Description
age	(number) User input age
percentiles :	(Array[]:Object) PHS percentiles
=> value	(number) The annualized risk for Prostate Cancer (Instantaneous risk)
=> label	(string) The percentile values. The last value is the personalized PHS percentile while the others are for the reference purpose.

Object Definition - personal

Key	Description
age_dt	(number) Age for interpolation, starting from current age, then extending to 3 years afterwards
risk_dt	(number) Personalized risk, assuming client has no signs of disease at all. Predicting for the risks in the following 3 years.

Object Definition - cumulative

Key	Description
risk	(number) The cumulative disease risk for individuals with the same genetic profile as client
survival	(number) The cumulative disease-free proportions for individuals with the same genetic profile as client
ageVals	(number) Corresponding age points
baselineSurvival	(number) The median of the cumulative disease-free proportions among all people in USA
baselineRisk	(number) The median of the cumulative disease risk among all people in USA

Object Definition - currentPoint

Key	Description
risk	(number) Predicted age-dependent cumulative risk of disease for the client
survival	(number) Predicted cumulative disease-free proportions for the client
baselineRisk	(number) The median of the cumulative disease-free proportions among all people in the same age of the client

Retrieve Results

Headers

Authorization: apiId <your-api-id> apiSecret <your-api-secret>

Response

{
    "success": true,
    "ancestralWarning": false,
    "snpsWarning": false,
    "requestId": "6f370e30-f4b0-11e7-8abf-919aafdd8e30",
    "inputFile": "23andMe",
    "phsReport": {
        "irTable": [],
        "personal": [],
        "cumulative": [],
        "currentPoint": {}
    }
}

Using our SDK

const HealthLytix = require('hytx-sdk-js');
const hytx = new HealthLytix(`yourApiId`, `yourApiSecret`);

// this shows how to retrieve 
// a previously calculated result.
// use the same requestId as runProstatePHS()
hytx.getProsatePHS(requestId)
    .then(report => /* report has the results */)
    .catch(e => /* handle error */ );

Use this endpoint to retrieve some previously calculated results from the Prosate Cancer PHS Algorithm

Prerequisites

Condition	Description
Genetics File Processed	A request already completed previously with app-pcgenic/run-app

GET URL Query Parameters

Param	Description
requestId	(string) Same as the one used when running app-pcgenic/run-app

JSON Response

Key	Description
Refer to description	Response is same as app-pcgenic/run-app. Refer to its response for more details.

Errors

The HealthLytix API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Bad formed request
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The specified api could not be found.
501	Endpoint specific failure. Will return an error key inside the response explaining the error in detail