Lifenome API (1.0.0)

Download OpenAPI specification:Download

Introduction

Lifenome API is a REST web service which exposes genotype-related functionalities:

  • create/read/update/delete operations for a Profile
  • upload genotype data for an existing Profile
  • read Trait assessments computed for a Profile

Changelog

16 Oct 2018

  • Added operation for genotype file uploading using time-limited secure URLs generated on-the-fly

API support

Contact API support directly via email (api-support@lifenome.com) or report a bug or feature request on the Trello board (Trello account must be created and permission must be granted to the board by the API support team. The board itself contains information on how to use the issue tracker).

Authentication

OAuth2 - an open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications.

api_auth

The OAuth 2.0 grant that machine-to-machine interfaces utilize in order to access an API, is the Client Credentials Grant.

With Client Credentials Grant (defined in RFC 6749, section 4.4) a Non Interactive Client (a CLI, a daemon, or a Service running on your backend), can directly ask Auth0 for an access_token, by using its Client Credentials (Client Id and Client Secret) to authenticate. In this case the token represents the Non Interactive Client itself, instead of an end user.

How to obtain a token for your application?

You can ask Lifenome API for tokens for any of your authorized applications with issuing the following API call:

  curl --request POST \
    --url https://lifenome.auth0.com/oauth/token \
    --header 'content-type: application/json' \
    --data '{"client_id": "<CLIENT_ID>", "client_secret": "<CLIENT_SECRET>", "audience": "https://api.lifenome.com/profiles",  "grant_type": "client_credentials"}'

Response:

  {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1EbERRalV6T1VRMU1USkJNMFJGUVVFek5EUXdOalE1TWpWRE9EYzJRVFl6UWpZMU9UWkNRZyJ9.eyJpc3MiOiJodHRwczovL2xpZmVub21lLmF1dGgwLmNvbS8iLCJzdWIiOiJpTTJLTGVTbU5HbXRnNkdNT1dMVlg5NDNjemM5cFNsaUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGkubGlmZW5vbWUuY29tL2duYyIsImlhdCI6MTUyOTA0NDM0MiwiZXhwIjoxNTI5MTMwNzQyLCJhenAiOiJpTTJLTGVTbU5HbXRnNkdNT1dMVlg5NDNjemM5cFNsaSIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyJ9.TAcAdOmTttP1FadqwCkdTTV3KZwda29ERpHgcwZ7bu2YnV7QrladjUAm7U-4mriRTsDo0CdZIpH7Nw_Tt1MbESLO-WQfHw0R_FgsfCUCdK3kaEy2veD0mD34evsXQXsdRL4Us4ZXKqzfd-gYmSy8ub56XMekPuupt4RqAi-GnNrtagIMBy9nUrvWE6vSiBi9zVlkcjkAGM5Pj3_Ldgh9m0d1MR_KyveTc10BnNQdYMS7vnF77r1D37tvBe8R_J1R0VhEZzszKY2YGw7t6aBTkoscktYYx2ovR8Qit9ke9qaU9JVc2iX72zBgkCDOut1ygvLCIwwzdikUzMW14vCsuw",
    "token_type": "Bearer"
  }

You can now extract the access_token property from the response to make authorized requests to your API.

Sending the token to the API

You can use this Bearer token with an Authorization Header in your request to obtain authorized access to your API.

  curl --request GET \
    --url https://api-profiles.lifenome.com/api/<ENDPOINT>/ \
    --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1EbERRalV6T1VRMU1USkJNMFJGUVVFek5EUXdOalE1TWpWRE9EYzJRVFl6UWpZMU9UWkNRZyJ9.eyJpc3MiOiJodHRwczovL2xpZmVub21lLmF1dGgwLmNvbS8iLCJzdWIiOiJpTTJLTGVTbU5HbXRnNkdNT1dMVlg5NDNjemM5cFNsaUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGkubGlmZW5vbWUuY29tL2duYyIsImlhdCI6MTUyOTA0NDM0MiwiZXhwIjoxNTI5MTMwNzQyLCJhenAiOiJpTTJLTGVTbU5HbXRnNkdNT1dMVlg5NDNjemM5cFNsaSIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyJ9.TAcAdOmTttP1FadqwCkdTTV3KZwda29ERpHgcwZ7bu2YnV7QrladjUAm7U-4mriRTsDo0CdZIpH7Nw_Tt1MbESLO-WQfHw0R_FgsfCUCdK3kaEy2veD0mD34evsXQXsdRL4Us4ZXKqzfd-gYmSy8ub56XMekPuupt4RqAi-GnNrtagIMBy9nUrvWE6vSiBi9zVlkcjkAGM5Pj3_Ldgh9m0d1MR_KyveTc10BnNQdYMS7vnF77r1D37tvBe8R_J1R0VhEZzszKY2YGw7t6aBTkoscktYYx2ovR8Qit9ke9qaU9JVc2iX72zBgkCDOut1ygvLCIwwzdikUzMW14vCsuw'
Security scheme type: OAuth2
clientCredentials OAuth Flow
Token URL: https://lifenome.auth0.com/oauth/token
Scopes:
  • write:profiles -

    modify profiles

  • read:profiles -

    read your profiles

Usage guide

This section lists one possible usage scenario for the Lifenome API with the demonstration of the complete workflow - starting from the authentication procedure and finishing with the reading of the trait assessments for the newly created profile.

Main API entities are:

  • Profile: represents single person with genotype data and optional phenotype data (e.g. email address, names, gender).
  • Trait: represents genetically determined characteristic for which assessments can be computed (e.g. Overweight potential). Access to trait results is charged, but there might be a set of free traits assigned to the client.
  • Trait assessment: represents assessment results based on the provided genetic data for the given trait (e.g. Overweight potential trait is elevated for the Profile X)

In order to read the genetic trait assessments for the existing genetic data, API client needs to:

  1. Obtain the access token
  2. Create profile
  3. Upload genetic data
  4. (Optional) Get list of traits with pricing info assigned to the client
  5. Get annotated list of traits available for the profile
  6. Get trait assessments for free traits (if any)
  7. Computing the assessment data for basic (non-free) traits
  8. Reading the trait assessments

Steps 1-8. are described in the following sections.

1. Authentication

First, authentication token must be obtained by calling the authentication endpoint:

  curl --url "https://lifenome.auth0.com/oauth/token" \
       --request POST \
       --header 'content-type: application/json' \
       --data '{"client_id": "<CLIENT_ID>", "client_secret": "<CLIENT_SECRET>", "audience": "https://api.lifenome.com/profiles",  "grant_type": "client_credentials"}'

Also, token can be extracted into environment variable using e.g. jq tool:

  export ACCESS_TOKEN=`curl --url 'https://lifenome.auth0.com/oauth/token' --request POST --header 'content-type: application/json'   --data '{"grant_type":"client_credentials","client_id": "<CLIENT_ID>","client_secret": "<CLIENT_SECRET>","audience": "https://api.lifenome.com/profiles"}' | jq -r '.access_token'`

Fetched access token must be included into the Authorization header for every subsequent request to protected resources of the API.

Note that <CLIENT_ID> and <CLIENT_SECRET> can be obtained by contacting the API support.

2. Profile creation

Every genetic file that will be analyzed must be connected to a Profile resource. Before uploading of the genetic file and obtaining the assessment data, profile must be created:

  curl --url "https://api-profiles.lifenome.com/api/profiles/" \
       --request POST \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json" \
       --data '{"first_name": "John", "last_name": "Doe", "age": 32}'

  {
    "id": "<PROFILE_ID>",
    "email": "",
    "first_name": "John",
    "last_name": "Doe",
    "gender": 0,
    "age": 32,
    "ethnicity": 0
  }

Successful operation will return status code 201 Created and the added profile will be assigned with the unique profile id string (<PROFILE_ID>) that will be used for accessing operations on the profile.

Using the profile id, the profile that was just created will be available at the profile endpoint:

  curl --url "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/" \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  {
    "id": "<PROFILE_ID>",
    "email": "",
    "first_name": "John",
    "last_name": "Doe",
    "gender": 0,
    "age": 32,
    "ethnicity": 0
  }

Also, added profile will be listed at the profile collection endpoint:

  curl --url "https://api-profiles.lifenome.com/api/profiles/" \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  [
      {
           "id": "<PROFILE_ID>",
           "email": "",
           "first_name": "John",
           "last_name": "Doe",
           "gender": 0,
           "age": 32,
           "ethnicity": 0
       }
  ]

3. Genotype file upload

Genetic files are uploaded directly to Lifenome storage servers by first fetching the time-limited secure storage URL for the corresponding profile (<PROFILE_ID>) using the endpoint:

  curl --url "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/genotype/upload/" \
       --request GET \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  {
    "url": "<UPLOAD_URL>"
  }

Genetic file itself (<FILE_PATH>) can be uploaded directly to the provided <UPLOAD_URL>:

  curl -X PUT -H 'content-type: text/plain' --data-binary @<FILE_PATH> "<UPLOAD_URL>"

Please note the method PUT used for the upload (POST will not work).

When the file upload completes, Lifenome backend will automatically start processing the file. Results will be available for retrieval once all the calculations are completed. Currently, the only way to test if the asynchronous automatic processing finished is to poll the Profile Traits endpoint (see sections 5. and 6. in this chapter). Also, file processing can be initiated using the synchronous call that will block the caller using the operation:

  curl --url https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/genotype/upload/ \
       --request POST \
       --header "Authorization: Bearer ${TOKEN}" \
       --header "Content-Type: application/json"

4. Fetching traits assigned to the client with pricing info

Lifenome API calculates genetic assessments for the selected set of Traits. Every trait is represented with the unique trait code. List of all traits assigned to the given API client, with included pricing type, is exposed at the endpoint:

  curl --url "https://api-profiles.lifenome.com/api/traits/" \
       --request GET \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  [
    {
      "trait" : {
        "code": "trait_code_1",
        "name": "Trait 1",
        "overview": "<p>This is the description of Trait 1.</p>",
        "connotation": "risky"
      },
      "type": "basic"
    },          
    {
      "trait" : {
        "code": "trait_code_2",
        "name": "Trait 2",
        "overview": "<p>This is the description of Trait 2.</p>",
        "connotation": "risky"
      },
      "type": "basic"
    },
    {
      "trait" : {
        "code": "trait_code_3",
        "name": "Trait 3",
        "overview": "<p>This is the description of Trait 3.</p>",
        "connotation": "good"
      },
      "type": "free"
    },
    {
      "trait" : {
        "code": "trait_code_4",
        "name": "Trait 4",
        "overview": "<p>This is the description of Trait 4.</p>",
        "connotation": "good"
      },
      "type": "basic"
    },
    ...
  ]

The endpoint returns list of Trait objects with trait code and additional trait metadata. All traits obtained from this endpoint will be considered for computation for the given API client.

In general, access to trait assessments is charged according to the existing pricing models. However, free traits can be assigned to clients. Each trait in the previous response includes trait type field which defines the pricing model. In the example, access to all traits will be charged, with the exception of Trait 3. Please use this endpoint to obtain list of free traits defined for your API client.

5. Fetching traits for the existing profile

Some traits may not be available for the selected profile, regardless of the pricing model defined by type attribute. For example, maybe genetic data is incomplete and required genetic markers are missing for the particular trait. In order to get annotated list of traits that are analyzed and connected to a certain profile, Profile Traits endpoint must be called:

  curl --url "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/traits/" \
       --request GET \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  [
    {
      "trait": {
        "code": "trait_code_1",
        "name": "Trait 1",
        "overview": "<p>This is the description of Trait 1.</p>",
        "connotation": "risky"
        },
      "status": "available"
    },
    {
      "trait": {
        "code": "trait_code_2",
        "name": "Trait 2",
        "overview": "<p>This is the description of Trait 2.</p>",
        "connotation": "risky"
        },
      "status": "available"
    },
    {
      "trait": {
        "code": "trait_code_3",
        "name": "Trait 3",
        "overview": "<p>This is the description of Trait 3.</p>",
        "connotation": "good"
        },
      "status": "computed"
    },
    {
      "trait": {
        "code": "trait_code_4",
        "name": "Trait 4",
        "overview": "<p>This is the description of Trait 4.</p>",
        "connotation": "good"
        },
      "status": "unavailable"
    },
    ...
  ]

Response contains list of trait objects with trait codes and statuses. Detailed description of statuses is available here. If the Profile Traits endpoint returns empty response, this means that the genetic file is missing or the file upload/processing is still in progress.

6. Get trait assessments for free traits (if any)

Profile traits endpoint can be used for quick access to all free trait assessments in a single call, if there are any free traits defined for the client. If score query parameter is provided for the GET method on the Profile traits endpoint, the response will include assessment data for the computed traits (free traits are always automatically computed, unless it is not possible to compute them, e.g. incomplete genetic data):

  curl --url "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/traits/?score" \
       --request GET \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  [
    {
      "trait": {
        "code": "trait_code_3",
        "name": "Trait 3",
        "overview": "<p>This is the description of Trait 3.</p>",
        "connotation": "good"
      },
      "status": "computed",
      "assessment_level": 1,
      "recommendations": "...",
      "percentile": 45.0,
      "snps": ["rs12345"]
    }
  ]

7. Computing the assessment data for basic (non-free) traits

In order to read assessments for the selected set of (non-free) traits, assessment computation needs to be initiated. Note that computation can only be initiated for the traits that have available value for the status attribute. If the trait assessments cannot be computed for a given profile, those traits will have status=unavailable (e.g. incomplete genetic data). Moreover, if there are free traits assigned to your client, those traits will be automatically computed (status=computed) and trait assessments can be retrieved without initiating the computation (Trait 3 in the previous example).

Assessment computation for the set of traits can be initiated with the call:

  curl --url "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/traits/" \
       --request POST \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json" \
       --data '{"trait_codes": ["trait_code_1", "trait_code_2"]}'

  [
    {
      "trait": {
        "code": "trait_code_1",
        "name": "Trait 1",
        "overview": "<p>This is the description of Trait 1.</p>",
        "connotation": "risky"
        },
      "status": "computed",
      "assessment_level": 0,
      "recommendations": "...",
      "percentile": 15.0,
      "snps": ["rs978739"]
    },
    {
      "trait": {
        "code": "trait_code_2",
        "name": "Trait 2",
        "overview": "<p>This is the description of Trait 2.</p>",
        "connotation": "risky"
        },
      "status": "computed",
      "assessment_level": 0,
      "recommendations": "...",
      "percentile": 5.0,
      "snps": ["rs1175549"]
    }
  ]

Response already includes list of trait codes with statuses and computed assessments. Request can include arbitrary number of trait codes, but only those traits with status=available will be computed. Note that statuses of the computed traits will be changed to computed.

8. Reading the assessment data for the single trait

Assessment for the previously computed selected profile trait can be fetched anytime using the known <PROFILE_ID> and <TRAIT_CODE> with the call:

  curl --url "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/traits/<TRAIT_CODE>/" \
       --request GET \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"

  {
    "trait": {
      "code": "trait_code_1",
      "name": "Trait 1",
      "overview": "<p>This is the description of Trait 1.</p>",
      "connotation": "risky"
    },
    "status": "computed",
    "assessment_level": 0,
    "recommendations": "...",
    "percentile": 15.0,
    "snps": ["rs978739"]
  }

Additionally, computation of the assessments can also be initiated anytime for a single trait using the same endpoint (with PUT operation) and the response will include full computed assessment data:

  curl --url "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/traits/<TRAIT_CODE>/" \
       --request PUT \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header "Content-Type: application/json"
  {
    "trait": {
      "code": "trait_code_x",
      "name": "Trait x",
      "overview": "<p>This is the description of Trait x.</p>",
      "connotation": "risky"
    },
    "status": "computed",
    "assessment_level": 0,
    "recommendations": "...",
    "percentile": 45.0,
    "snps": ["rs12345"]
  }

Supported Genotype Input File Format

When creating genotype profiles using the API, client needs to submit files that contain genetic data. Genetic data is stored using simple textual file, usually with .txt or .csv extensions, but the API also supports upload of compressed archives (.zip). Genetic data stored inside textual files is divided in header and genetic data. All header lines are prefixed with # character:

  # header line 1
  # header line 2
  # ...

  genetic data line 1
  genetic data line 2
  ...

Standard data formats

Genetic data files downloaded directly from corresponding services can be submitted directly, without any extra file content manipulation. Supported services are:

  • 23andMe
  • Ancestry.com
  • FamilyTreeDNA

23andMe

Files provided by 23andMe have the following structure (some header lines omitted):

  # This data file generated by 23andMe ...
  # …
  # Below is a text version of your data. Fields are TAB-separated. Each line
  # corresponds to a single SNP. For each SNP, we provide its identifier (an rsid or
  # an internal id), its location on the reference human genome, and the genotype
  # call oriented with respect to the plus strand on the human reference sequence.
  # ...
  # rsid    chromosome    position    genotype
  rs1       1             734462      AA
  ...

Note that line with column names is prefixed with # character in this format.

Ancestry.com

Files provided by Ancestry.com have the following structure (some header lines omitted):

  #AncestryDNA raw data download
  #This file was generated by AncestryDNA at ...
  #...
  #Genetic data is provided below as five TAB delimited columns. Each line
  #corresponds to a SNP.  Column one provides the SNP identifier (rsID where
  #possible).  Columns two and three contain the chromosome and basepair position
  #of the SNP using human reference build 37.1 coordinates. Columns four and five
  #contain the two alleles observed at this SNP (genotype)...
  rsid    chromosome    position    allele1    allele2
  rs1     1             82154       A          G
  ...

Note that line with column names is not prefixed with # character in this format.

FamilyTreeDNA

Files provided by FamilyTreeDNA have the following structure:

  RSID,CHROMOSOME,POSITION,RESULT
  "rs1","1","734462","AA"

Note that line with column names is not prefixed with # character in this format.

Profiles

Profile resource

Profile resources are used to store person's metadata and person's genotype data which are used to compute genetic assessments of various traits.

Following endpoints expose operations on Profile resources:

  • Basic profile management operations:
    • Create new profile
    • List existing profiles
    • Update existing profile metadata (complete and partial update are supported)
    • Delete profile

Create profile

Creates a new profile.

header Parameters
Authorization
required
string

Authorization header with access token.

Request Body schema: application/json
first_name
string

First name

last_name
string

Last name

gender
int
Enum:0 1 2

Male = 1, Female = 2, Unknown = 0

age
int

Age

ethnicity
int
Enum:0 1 2 3 4 5

European (White) = 1, American (Hispanic or Latino) = 2, African (Black or African American) = 3, East Asian = 4, South Asian = 5, Unknown = 0

Responses

201

Created

405

Invalid input

post /profiles
Demo server
null//api-profiles.lifenome.com/profiles/profiles
Production server
null//api.lifenome.com/api/profiles/profiles

Request samples

application/json
Copy
Expand all Collapse all
{
  • "first_name": "John",
  • "last_name": "Doe",
  • "gender": 0,
  • "age": null,
  • "ethnicity": 0
}

List profiles

Returns list of all existing profiles.

header Parameters
Authorization
required
string

Authorization header with access token.

Responses

200

Success

401

Unauthorized

get /profiles
Demo server
null//api-profiles.lifenome.com/profiles/profiles
Production server
null//api.lifenome.com/api/profiles/profiles

Request samples

Copy
curl "https://api-profiles.lifenome.com/api/profiles/" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Content-Type: application/json"

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get profile

Reads data for the existing profile.

path Parameters
profile_id
required
string <uuid>

Profile identifier

header Parameters
Authorization
required
string

Authorization header with access token.

Responses

200

Success

401

Unauthorized

404

Not Found

get /profiles/{profile_id}/
Demo server
null//api-profiles.lifenome.com/profiles/profiles/{profile_id}/
Production server
null//api.lifenome.com/api/profiles/profiles/{profile_id}/

Request samples

Copy
curl "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Content-Type: application/json"

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "first_name": "John",
  • "last_name": "Doe",
  • "gender": 0,
  • "age": null,
  • "ethnicity": 0
}

Update profile

Updates existing profile. This operation will perform complete update which means that all properties of profile will be updated. Properties missing in request body will be set to default value. If you like to perform partial update then use PATCH operation.

path Parameters
profile_id
required
string <uuid>

Profile identifier

header Parameters
Authorization
required
string

Authorization header with access token.

Request Body schema: application/json
first_name
string

First name

last_name
string

Last name

gender
int
Enum:0 1 2

Male = 1, Female = 2, Unknown = 0

age
int

Age

ethnicity
int
Enum:0 1 2 3 4 5

European (White) = 1, American (Hispanic or Latino) = 2, African (Black or African American) = 3, East Asian = 4, South Asian = 5, Unknown = 0

Responses

200

Success

401

Unauthorized

404

Not Found

put /profiles/{profile_id}/
Demo server
null//api-profiles.lifenome.com/profiles/profiles/{profile_id}/
Production server
null//api.lifenome.com/api/profiles/profiles/{profile_id}/

Request samples

application/json
Copy
Expand all Collapse all
{
  • "first_name": "John",
  • "last_name": "Doe",
  • "gender": 0,
  • "age": null,
  • "ethnicity": 0
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "first_name": "John",
  • "last_name": "Doe",
  • "gender": 0,
  • "age": null,
  • "ethnicity": 0
}

Partially update profile

Partially updates existing profile. This operation will only update properties which are present in request body. All other properties of the profile will not be changed. If you like to perform complete update then use PUT operation.

path Parameters
profile_id
required
string <uuid>

Profile identifier

header Parameters
Authorization
required
string

Authorization header with access token.

Request Body schema: application/json
first_name
string

First name

last_name
string

Last name

gender
int
Enum:0 1 2

Male = 1, Female = 2, Unknown = 0

age
int

Age

ethnicity
int
Enum:0 1 2 3 4 5

European (White) = 1, American (Hispanic or Latino) = 2, African (Black or African American) = 3, East Asian = 4, South Asian = 5, Unknown = 0

Responses

200

Success

401

Unauthorized

404

Not Found

patch /profiles/{profile_id}/
Demo server
null//api-profiles.lifenome.com/profiles/profiles/{profile_id}/
Production server
null//api.lifenome.com/api/profiles/profiles/{profile_id}/

Request samples

application/json
Copy
Expand all Collapse all
{
  • "first_name": "John",
  • "last_name": "Doe",
  • "gender": 0,
  • "age": null,
  • "ethnicity": 0
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "first_name": "John",
  • "last_name": "Doe",
  • "gender": 0,
  • "age": null,
  • "ethnicity": 0
}

Delete profile

Deletes profile and all existing files.

path Parameters
profile_id
required
string <uuid>

Profile identifier

header Parameters
Authorization
required
string

Authorization header with access token.

Responses

200

Success

401

Unauthorized

404

Not Found

delete /profiles/{profile_id}/
Demo server
null//api-profiles.lifenome.com/profiles/profiles/{profile_id}/
Production server
null//api.lifenome.com/api/profiles/profiles/{profile_id}/

Request samples

Copy
curl -X delete \
"https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Response samples

application/json
Copy
Expand all Collapse all
{
  • "detail": "string"
}

Get genotype metadata

Returns genotype metadata for the existing profile. Returns empty object if genetic file was not previously uploaded.

path Parameters
profile_id
required
string <uuid>

Profile identifier

header Parameters
Authorization
required
string

Authorization header with access token.

Responses

200

Success

401

Unauthorized

404

Not Found

get /profiles/{profile_id}/genotype/
Demo server
null//api-profiles.lifenome.com/profiles/profiles/{profile_id}/genotype/
Production server
null//api.lifenome.com/api/profiles/profiles/{profile_id}/genotype/

Request samples

Copy
curl "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/genotype/" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Content-Type: application/json"

Response samples

application/json
Copy
Expand all Collapse all
{
  • "content_type": "string",
  • "size": "string",
  • "md5_hash": "string",
  • "crc32c": "string",
  • "created_at": "2018-11-05",
  • "updated_at": "2018-11-05",
  • "metadata": { }
}

Profile Traits

Profile Traits resources are child resources of the Profile resource. Following endpoints expose operations on Profile Traits resources:

  • Basic profile trait management operations:
    • List traits available for given profile
    • Initiate assessment data for a set of profile traits
    • Fetch the assessment data for a single trait
    • Initiate assessment data computation for a single trait

List Profile Traits

Lists Profile's Traits annotated with assessment status. A trait assessment status can be:

  • available: Assessment can be computed for a given trait. Note that client needs to initiate computation in order to fetch the assessment. In order to initiate computation, method Initiate computation for a set of traits can be used.
  • unavailable: Assessment can not be computed for a given trait. The most common reason is that profile's genotype data does not contain genetic markers required for a trait assessment computation.
  • computed: Assessment is already computed for the trait and the data is ready to be fetched by a client. Note: free traits will be automatically computed, if possible.

Additionally, for the GET method, if parameter score is specified, then response will also include any existing assessment data.

Note: In case of non-existing genetic data or if the file processing is still in progress, response will contain empty list.

path Parameters
profile_id
required
string <uuid>

Profile identifier

query Parameters
score
string
Example: "profiles/{profile_id}/traits/?score"

Adding this parameter to the request will fetch traits together with assessment data. Be aware that this means that only traits for which assessments are computed will be included in the response.

header Parameters
Authorization
required
string

Authorization header with access token.

Responses

200

Success

401

Unauthorized

get /profiles/{profile_id}/traits/
Demo server
null//api-profiles.lifenome.com/profiles/profiles/{profile_id}/traits/
Production server
null//api.lifenome.com/api/profiles/profiles/{profile_id}/traits/

Request samples

Copy
curl --url "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/traits/" \
     --request GET \
     --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json"

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Initiate computation for a set of traits

Initiates the trait assessment computation for a given set of Profile Traits. List of trait codes is provided in the request body. Available trait codes can be obtained from the Client traits endpoint or the Profile Traits endpoint (includes trait statuses). This operation also immediately returns the assessment data for a given set of profile traits in order to avoid additional calls to Trait assessment endpoint.

path Parameters
profile_id
required
string <uuid>

Profile identifier

header Parameters
Authorization
required
string

Authorization header with access token.

Request Body schema: application/json
Array
string (TraitCode)

Trait code

Responses

200

Success

401

Unauthorized

post /profiles/{profile_id}/traits/
Demo server
null//api-profiles.lifenome.com/profiles/profiles/{profile_id}/traits/
Production server
null//api.lifenome.com/api/profiles/profiles/{profile_id}/traits/

Request samples

application/json
Copy
Expand all Collapse all
[
  • "string"
]

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get trait assessment

Returns assessment for a given profile trait.

path Parameters
profile_id
required
string <uuid>

Profile identifier

trait_code
required
string

Trait code

header Parameters
Authorization
required
string

Authorization header with access token.

Responses

200

Success

401

Unauthorized

get /profiles/{profile_id}/traits/{trait_code}/
Demo server
null//api-profiles.lifenome.com/profiles/profiles/{profile_id}/traits/{trait_code}/
Production server
null//api.lifenome.com/api/profiles/profiles/{profile_id}/traits/{trait_code}/

Request samples

Copy
curl --url "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/traits/<TRAIT_CODE>/" \
     --request GET \
     --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json"

Response samples

application/json
Copy
Expand all Collapse all
{
  • "trait":
    {
    },
  • "status": "available",
  • "assessment_level": 0,
  • "percentile": 0,
  • "recommendations": "string",
  • "snps":
    [
    ]
}

Initiate computation for a single trait

Initiates assessment computation for the given profile trait and returns computed assessment.

path Parameters
profile_id
required
string <uuid>

Profile identifier

trait_code
required
string

Trait code

header Parameters
Authorization
required
string

Authorization header with access token.

Responses

200

Success

401

Unauthorized

put /profiles/{profile_id}/traits/{trait_code}/
Demo server
null//api-profiles.lifenome.com/profiles/profiles/{profile_id}/traits/{trait_code}/
Production server
null//api.lifenome.com/api/profiles/profiles/{profile_id}/traits/{trait_code}/

Request samples

Copy
curl --url "https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/traits/<TRAIT_CODE>/" \
     --request PUT \
     --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json"

Response samples

application/json
Copy
Expand all Collapse all
{
  • "trait":
    {
    },
  • "status": "available",
  • "assessment_level": 0,
  • "percentile": 0,
  • "recommendations": "string",
  • "snps":
    [
    ]
}

URL upload

Lifenome's fast and secure genotype storage is powered by Google Cloud infrastructure. Genetic files are uploaded directly to storage servers using time-limited secure URLs generated on-the-fly resulting in secure and scalable solution for genetic file uploading. Upon completion of the file upload, Lifenome backend will automatically start processing the uploaded file. For security reasons, time-limited secure URLs provide access to storage for only limited amount of time (currently 3 minutes). When the received URL expires, storage API will return appropriate response and client must ask for a new URL. The API currently supports only textual files (e.g. .txt, .csv, .tsv) with content type text/plain.

Get upload URL

Returns secure URL for a time-limited access to profile's genotype storage. After the URL is fetched, client must upload the file directly to the given URL using the PUT method with corresponding content type, usually text/plain (see code snippet).

path Parameters
profile_id
required
string <uuid>

Profile identifier

query Parameters
content-type
string

Content type of the genotype file to be uploaded. Currently supported content types are "text/plain" (default) and "application/zip". Provided content type must be given on file upload.

header Parameters
Authorization
required
string

Authorization header with access token.

Responses

200

Success

401

Unauthorized

404

Not Found

get /profiles/{profile_id}/genotype/upload/
Demo server
null//api-profiles.lifenome.com/profiles/profiles/{profile_id}/genotype/upload/
Production server
null//api.lifenome.com/api/profiles/profiles/{profile_id}/genotype/upload/

Request samples

Copy
curl --request GET --url https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/genotype/upload/ --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json"
curl -X PUT -H 'content-type: text/plain' --data-binary @file.csv "<UPLOAD_URL>"

Response samples

application/json
Copy
Expand all Collapse all
{
  • "url": "string"
}

Synchronous file processing

This operation is used for starting synchronous processing of the previously uploaded genotype file. Note that genotype file processing will be initiated automatically. However, calling this endpoint will block the caller until file is processed and thus polling is avoided.

path Parameters
profile_id
required
string <uuid>

Profile identifier

header Parameters
Authorization
required
string

Authorization header with access token.

Responses

200

Success

401

Unauthorized or called before genetic data upload.

404

Not Found

post /profiles/{profile_id}/genotype/upload/
Demo server
null//api-profiles.lifenome.com/profiles/profiles/{profile_id}/genotype/upload/
Production server
null//api.lifenome.com/api/profiles/profiles/{profile_id}/genotype/upload/

Request samples

Copy
curl --request POST --url https://api-profiles.lifenome.com/api/profiles/<PROFILE_ID>/genotype/upload/ --header "Authorization: Bearer ${TOKEN}"

Response samples

application/json
Copy
Expand all Collapse all
{
  • "detail": "string"
}

Client Traits

Traits configured for authenticated API client.

Client traits

Fetches list of traits configured for the authenticated user. Every trait object contains trait code and the additional metadata, including the pricing information. Note that this call lists all traits that are available to the API client, regardless of the fact that assessment for some traits might not be possible to compute for some Profiles. In order to get annotated list of traits linked to specific Profile, see this endpoint.

query Parameters
q
string

This parameter is used for filtering the response trait set. If the string value is given, the response will contain only those traits whose trait codes or trait names contain the given string.

header Parameters
Authorization
required
string

Authorization header with access token.

Responses

200

List of traits

401

Unauthorized access

default

Unexpected error

get /traits/
Demo server
null//api-profiles.lifenome.com/profiles/traits/
Production server
null//api.lifenome.com/api/profiles/traits/

Request samples

Copy
curl --url "https://api-profiles.lifenome.com/api/traits/" \
     --request GET \
     --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json"

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]