Welcome to the Gencove API docs!
The Gencove REST API makes it easy to:
- upload low-pass sequencing FASTQ files to the Gencove analysis pipeline
- download analysis results
- track sample status
- automate data delivery.
Read on to get started and try out the examples on the side along the way.
Genomic data is organized into “projects”. Each
project contains “samples”. Each sample has an
id (generated by Gencove) and
client_id (provided to
Gencove by clients).
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 going to My Projects -> Add new project
The Gencove CLI
The Gencove command-line interface (CLI) can be used to easily access the API.
It is mostly used for:
- Uploading FASTQ files for analysis
- Downloading analysis results
$ pip install gencove $ gencove upload <local-directory-path>
# In shell: pip install gencove gencove upload <local-directory-path>
Install the Gencove CLI using the Python package manager
pip and upload
files to your Gencove account.
Hint: for the newest pre-release versions, check: PyPI
$ pip install gencove
# In shell: pip install gencove
The Gencove CLI can be installed using the Python package manager
pip. The source code is available on
Python and pip are commonly preinstalled on most Mac and Linux systems. In case you do need to install Python, commonly used instructions are available here.
Due to a known issue with Python that ships
with Mac OS, the install command should be modified as follows:
pip install gencove --ignore-installed six. Alternatively, installation into the
local user environment is also a possible solution:
pip install --user gencove
$ export GENCOVE_EMAIL='<your-email>' $ export GENCOVE_PASSWORD='<your-password>'
export GENCOVE_EMAIL='<your-email>' export GENCOVE_PASSWORD='<your-password>'
Your credentials can be provided to the Gencove CLI via the environment variables
Uploading FASTQ files
In order to enable FASTQ uploads for your account, log into your account and go to My FASTQs, where instructions will be provided (in case you already do not have access). You can expect a response from Gencove support within 24h.
Once uploads are enabled, users can upload files to the Gencove upload area using the Gencove CLI and assign the files to projects using the Gencove Dashboard. Once files are assigned to a project, they will be processed by the Gencove analysis pipeline. Analysis results will be available via the Gencove API and Dashboard once analysis is complete.
We highly recommend using the standard Illumina naming convention for FASTQ files. If files are named in this manner, Gencove systems will automatically detect:
- the sample identifier (and use it as the sample’s
- R1/R2 designations of files
A summary of the naming convetion is:
SAMPLE ID +
_ + … +
_ + (
_ + … +
Uploading using the CLI
gencove upload <source-path> [<destination-path>]
Syncs local directories to directories in your Gencove upload area. Recursively copies new and updated files from the source directory to the destination. Only creates folders in the destination if they contain one or more files.
$ gencove upload my-fastq-files/
gencove upload my-fastq-files/
The example command will recursively copy all files in the
my-fastq-files/ directory on your host system to a directory with an
automatically generated name the Gencove upload area.
$ gencove upload my-fastq-files/ gncv://my-fastq/batch-1/
gencove upload my-fastq-files/ gncv://my-fastqs/batch-1/
In case more control is needed over the upload destination, a destination path
gncv:// may be provided. This pattern is commonly used for
separating upload batches when continuously uploading data to your Gencove
account and is useful for easily filtering files in the Gencove Dashboard. A
common directory structure for batching uploads is:
- In case a file in the local directory already exists in the destination, it will not be overwritten
- In case a file exists in the destination, but not the local directory, it will not be deleted
Gencove provides a number of deliverables for each sample that is processed as part of a project. In case a sample fails processing due to quality control, only the original input files are provided as deliverables.
Downloading using the CLI
$ gencove download . --project-id my-project-id
gencove download . --project-id my-project-id
gencove download <local-destination-path> --project-id <project-id>
Downloads all deliverables for all samples in project the specified project, with the following naming scheme:
This directory structure reflects the fact that uniqueness of
client-ids is not
enforced, while uniqueness of
gencove-id is enforced.
When downloading, existing files on the local filesystem are not overwritten if the file
already exists and has the same size in bytes as the file that would be downloaded. This
behavior can be tweaked with the
$ gencove download . --sample-ids sample-id-1,sample-id-2,sample-id-3 --file-types impute-vcf,impute-tbi
gencove download . --sample-ids sample-id-1,sample-id-2,sample-id-3 --file-types impute-vcf,impute-tbi
Behavior of the download can also be tweaked in the following manner:
- Download only a specific set of sample ids by providing the
--sample-idsflag instead of the
- Download only a specific set of file types by providing the
--file-typesflag. Currently available file types are listed below (not all file types may be available for every project).
Developers may use the Gencove staging environment for development and testing.
The staging developer website URL is: https://web-stage.gencove.com
The staging API URL is: https://api-stage.gencove.com
The full API reference for publicly available endpoints is available here: API reference
The full CLI reference is available here: CLI reference
We reserve the right to remove your access to our API for any reason at our sole discretion.
Contact us at email@example.com