Introduction

Welcome to the Gencove API docs!

The Gencove REST API makes it easy to download genomic data, track sample status, and automate data delivery.

Read on to get started and try out the examples on the side along the way.

Also, the full API reference for publicly available endpoints is available here: API reference

Gencove data

Genomic data is organized into “apps”, which represent projects. Each app contains “members”, which represent samples. Each member has a member_id (generated by Gencove) and external_id (provided to Gencove by customers).

In most cases, a user account and app will be created for you by our team.

In case you would like to explore the Gencove data delivery dashboard, feel free to create an account and explore as follows:

Create a free Gencove account using the dashboard
Create an app by clicking “Create an new app” or going to My Apps -> Create a new app

API Key

The API key is used for programatically accessing Gencove.

You can find your API key by logging into the dashboard, clicking on your avatar in the top right corner of the page, and navigating to Settings. Once in Settings, scroll to the bottom of the screen, click “Show/hide API Key”, and a 36-character string will reveal itself.

The Gencove CLI

The Gencove command-line interface (CLI) can be used to easily access user genomic data.

Installation

# In shell:
pip install gencove

$ pip install gencove

The Gencove CLI can be installed using the Python package manager pip. The source code is available on GitLab.

Usage

# In shell (standard invocation)
gencove app raw_data <app-id> <external-ids-file> <csv-file>

# Using stdin and stdout:
cat <member-ids-file> | gencove app raw_data --output-format json --id-type member <app-id> - - > <json-file>

# Example to get all available VCF files, together with member ids and external ids
echo | gencove app raw_data --output-format csv <app-id>  - - | cut -d , -f 1,2,5 > output.csv

# Standard invocation:
$ gencove app raw_data <app-id> <external-ids-file> <csv-file>

# Using stdin and stdout:
$ cat <member-ids-file> | gencove app raw_data --output-format json --id-type member <app-id> - - > <json-file>

# Example to get all available VCF files, together with member ids and external ids
$ echo | gencove app raw_data --output-format csv <app-id>  - - | cut -d , -f 1,2,5 > output.csv

The Gencove CLI enables exporting user data in bulk to csv or json format.

The API key can be provided in the environment variable $GENCOVE_API_KEY or inline via the --api-key option. We recommend using the $GENCOVE_API_KEY environment variable for shared environments like HPC clusters.

Input and output can be a file path or “-” for stdin and stdout.

The input stream is expected to be one id per line.

Users’ genomic data can be accessed by providing a list of member_ids or external_ids. member_ids are Gencove ids for samples, while external_ids are ids provided to us by customers.

The tool will return a list of objects containing the following data for each member_id or external_id:

member_id - Gencove member id (unique)
external_id - the external id provided in JWT when requesting access to user data
app_id - the app id
vcf_url_s3 - a presigned URL for downloading the imputed .vcf file
snp_url_s3 - a presigned URL for downloading the original AncestryDNA, 23andMe, etc. data file
bam_url_s3 - a presigned URL for downloading the raw .bam file (if the user got their genomic data through Gencove)
bai_url_s3 - a presigned URL for downloading the .bam file index
fastq_nongrch37_url_s3 - a presigned URL for downloading the .fastq file with non-human reads
ancestry_url_s3 - a presigned URL for downloading a .json file with the output of Gencove’s ancestry analysis
microbiome_url_s3 - a presigned URL for downloading a .json file with the output of Gencove’s microbiome analysis

The presigned download URLs expire after 2 days, but there is no limit on the number of generated presigned URLs.

If using the default “external” id type, multiple entries for the same external id may be returned, since it is not guaranteed to be unique. Member (i.e., Gencove) ids are guaranteed to be unique.

In case data is not available for a given id or the id is not found, it is skipped.

Order of ids from input is not guaranteed to be preserved in output.

# In shell (get help)
gencove app raw_data --help

# Get help
$ gencove app raw_data --help

For detailed usage instructions, use the --help flag

Automated data delivery

{
    "event": "app_member_join",
    "data": {
          "app_id": 1,
          "member_id": 2,
          "external_id": "member_100003",
          "subsidy_in_cents": 0,
          "participating": true,
          "jwt_log": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOjEsImV4dGVybmFsX2lkIjoibWVtYmVyXzEwMDAwMSIsInN1YnNpZHlfaW5fY2VudHMiOjB9.TR4FVXDxdD0EL-LaHOaoOKQhv1N8UN0eYdvlt3nQ5ao"
    }
}

Data delivery can be automated using webhooks.

A webhook URL may be defined for an app, where events will be submitted via HTTP POST requests. The content of the webhook contains:

Type of event, event
Data describing the event in more detail, data

Currently, there are 2 types of events:

app_member_results_ready: generated when data becomes available when it was not available before.
test: generated when validating the webhook URL. If a webhook_url is defined when creating or updating an app, the Gencove backend will attempt to validate the URL by generating a HTTP POST request with this event type.

Example of an event can found in the sidebar.

Webhooks are only active when the app is in the enabled state.

Using the API

Authentication

# API key
import requests

response = requests.get(
    'https://rest.gencove.com/welcome-api-key',
    headers={
        'Authorization': 'GENCOVE-API-KEY <your_api_key>'
    }
)

# API key
$ curl -H 'Authorization: GENCOVE-API-KEY <your_api_key>'\
    https://rest.gencove.com/welcome-api-key

The API is accessed by placing your API key in the Authorization header of HTTP requests: Authorization: GENCOVE-API-KEY <api_key>

Listing your apps

import requests

response = requests.get(
    'https://rest.gencove.com/apps',
    headers={
        'Authorization': 'GENCOVE-API-KEY <your_api_key>'
    }
)

$ curl -H "Authorization: GENCOVE-API-KEY <your_api_key>"\
    https://rest.gencove.com/apps

Your apps can be listed with a GET HTTP request to /apps

Info about a single app

import requests

response = requests.get(
    'https://rest.gencove.com/apps/<app_id>',
    headers={
        'Authorization': 'GENCOVE-API-KEY <your_api_key>'
    }
)

response = requests.get(
    'https://rest.gencove.com/apps/<app_id>/stats',
    headers={
        'Authorization': 'GENCOVE-API-KEY <your_api_key>'
    }
)

$ curl -H "Authorization: GENCOVE-API-KEY <your_api_key>"\
    https://rest.gencove.com/apps/<app_id>

$ curl -H "Authorization: GENCOVE-API-KEY <your_api_key>"\
    https://rest.gencove.com/apps/<app_id>/stats

Data and stats for a specific app can be listed with GET HTTP requests to /apps/<app_id> and /apps/<app_id>/stats, respectively.

Listing app members

import requests

response = requests.get(
    'https://rest.gencove.com/apps/<app_id>/members',
    headers={
        'Authorization': 'GENCOVE-API-KEY <your_api_key>'
    }
)

$ curl -H "Authorization: GENCOVE-API-KEY <your_api_key>"\
    https://rest.gencove.com/apps/<app_id>/members

App users can be listed with a GET HTTP request to /apps/<app_id>/members

Info about a specific member

import requests

response = requests.get(
    'https://rest.gencove.com/apps/<app_id>/members/<member_id>',
    headers={
        'Authorization': 'GENCOVE-API-KEY <your_api_key>'
    }
)

$ curl -H "Authorization: GENCOVE-API-KEY <your_api_key>"\
    https://rest.gencove.com/apps/<app_id>/members/<member_id>

Info about a single member can be listed with a GET HTTP request to /apps/<app_id>/members/<member_id>

Accessing genomic data

import requests

response = requests.post(
    'https://rest.gencove.com/apps/<int:app_id>/raw-data',
    headers={
        'Authorization': 'GENCOVE-API-KEY <your_api_key>'
    },
    json={
        'member_ids': [<member_id_1>, <member_id_2>, ..., <member_id_N>]
    }
)

response = requests.post(
    'https://rest.gencove.com/apps/<int:app_id>/raw-data',
    headers={
        'Authorization': 'GENCOVE-API-KEY <your_api_key>'
    },
    json={
        'external_ids': [<external_id_1>, <external_id_2>, ..., <external_id_N>]
    }
)

$ curl -H "Authorization: GENCOVE-API-KEY <your_api_key>"\
    -H "Content-Type: application/json"\
    -X POST\
    -d '{"member_ids": [<member_id_1>, <member_id_2>, ..., <member_id_N>]}'\
    https://rest.gencove.com/apps/<int:app_id>/raw-data

$ curl -H "Authorization: GENCOVE-API-KEY <your_api_key>"\
    -H "Content-Type: application/json"\
    -X POST\
    -d '{"external_ids": [<external_id_1>, <external_id_2>, ..., <external_id_N>]}'\
    https://rest.gencove.com/apps/<int:app_id>/raw-data

Genomic data can be accessed by POSTing a list of member_ids or external_ids to /apps/<int:app_id>/raw-data .

The endpoint provides the same data as outlined above for the Gencove CLI.

Testing environment

Developers may use the Gencove staging environment for development and testing.

The staging developer website URL is: https://app-staging.gencove.com

The staging API URL is: https://rest-staging.gencove.com

API Reference

The full API reference for publicly available endpoints is available here: API reference

Terms

We reserve the right to remove your access to our API for any reason at our sole discretion.

FAQ

User FAQ