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 “projects”. Each project contains “samples”. Each sample has a sample_id (generated by Gencove) and external_id (provided to Gencove by customers).

In most cases, a user account and project 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 a project by clicking “Create a new project” or going to My Project -> Create a new project

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 project raw_data <project-id> <external-ids-file> <csv-file>

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

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

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

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

# Example to get all available VCF files, together with sample ids and external ids
$ echo | gencove project raw_data --output-format csv <project-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 sample_ids or external_ids. sample_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 sample_id or external_id:

sample_id - Gencove sample id (unique)
external_id - the external id provided in JWT when requesting access to user data
project_id - the project 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
local_ancestry_url_s3 - a presigned URL for downloading the output of Gencove’s local ancestry analysis
ancestry_url_suffix - a suffix for displaying ancestry using the Gencove map. To test, append it to https://ancestry-staging.gencove.com/
microbiome_url_s3 - a presigned URL for downloading a .json file with the output of Gencove’s microbiome analysis
traits_url_s3 - a presigned URL for downloading a .json file with the output of Gencove’s polygenic traits analyses

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. Sample
(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 project raw_data --help

# Get help
$ gencove project raw_data --help

For detailed usage instructions, use the --help flag

Automated data delivery

{
    "event": "project_sample_join",
    "data": {
          "project_id": 1,
          "sample_id": 2,
          "external_id": "sample_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 project, 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:

project_sample_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 project, 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 project 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 projects

import requests

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

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

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

Info about a single project

import requests

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

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

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

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

Data and stats for a specific project can be listed with GET HTTP requests to /projects/<project_id> and /projects/<project_id>/stats, respectively.

Listing project samples

import requests

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

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

project samples can be listed with a GET HTTP request to /projects/<project_id>/samples

Info about a specific sample

import requests

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

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

Info about a single sample can be listed with a GET HTTP request to /projects/<project_id>/samples/<sample_id>

Accessing genomic data

import requests

response = requests.post(
    'https://rest.gencove.com/projects/<int:project_id>/raw-data',
    headers={
        'Authorization': 'GENCOVE-API-KEY <your_api_key>'
    },
    json={
        'sample_ids': [<sample_id_1>, <sample_id_2>, ..., <sample_id_N>]
    }
)

response = requests.post(
    'https://rest.gencove.com/projects/<int:project_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 '{"sample_ids": [<sample_id_1>, <sample_id_2>, ..., <sample_id_N>]}'\
    https://rest.gencove.com/projects/<int:project_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/projects/<int:project_id>/raw-data

Genomic data can be accessed by POSTing a list of sample_ids or external_ids to /projects/<int:project_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