Fabric Genomics provides an API based on the HTTPS protocol, using HTTP requests (GET, POST, PUT and DELETE) to securely transmit variation data, launch analyses and retrieve finished report data.


Every request must authenticate against our database of API Keys, providing the login and password according to the HTTP basic access authentication method (see Wikipedia - basic access). Please contact support to have them generate an API Key for your application. An API Key is tied to a specific Opal™ user, referred to as the API User hereon. Any email messages generated when using the Opal™ API are sent to the API User.

Fabric Genomics stores passwords in a one-way encrypted hash according to industry standard security procedures. Passwords cannot be recovered, but we can issue a new API key upon request.

The Opal™ API uses SSL-encrypted HTTP for its protocol, via the normal port for secure HTTP, 443. Attempts to query the server with non-encrypted HTTP request on port 80 (ie. instead of will return a 302 Redirect HTTP response, with no response body provided.


Most invalid requests (e.g. for invalid parameter values) return an HTTP status of 400, 404 or 422; authentication errors return an HTTP status of 401 or 403.


All dates and times are returned in PST.

Example Code

Please refer to the links below for some end-to-end examples making use of the Opal™ API:
Python Examples
Bash Examples

Use Cases

Uploading Genomes

Once you obtain an API Key you can start uploading your samples to Opal™ for annotation, analysis and clinical report generation. API Keys are associated with a single Workspace (a group of Projects and Users), and genomes must be uploaded to specific projects within that Workspace. You may either use an existing project, or leverage the API to create a new project for this purpose. To create a Project use a POST request against the Create Project endpoint. You will need to specify a Project name and optionally a description and a parameter to indicate how the project should be shared with existing and future members of your workspace. Projects are identified by a numeric ID. This ID is necessary when uploading, listing and otherwise accessing genomes and reports.

To upload a VCF file use the Upload endpoint, including the entirety of the file as the body of the request. The assembly version must be hg19 (internally we handle GRCh37 and hg19 interchangeably).

The Opal™ API accepts VCF 4.0+ (view format here) preferably containing a single sample column.

Opal™ assigns a unique ID to all uploaded genomes. These IDs are used to identify the genome within Opal. External IDs are an alternate method to identify and find genomes within Opal™. Opal™ does not enforce uniqueness of the external ID.

Multi-sample VCF’s can be uploaded, however in this case the ID returned by the upload call cannot be used to reference the individual genomes comprising the original file. The Opal™ VCF parser accepts quality and read depth data in a variety of formats. Please refer to the Opal™ user guide for more information, or contact support for specific questions.

Upon successful parsing, the uploaded genome is queued for annotation by the Opal™ Pipeline. Panel and exome VCFs usually annotate within minutes, while full genomes can take longer.

If any genome fails to annotate, the system will send an email notification to the API User as well as the Fabric Genomics Support Team.

Relevant example Python scripts: Genome Workflows

Launching Clinical Reports

A clinical report combines genome variant data with other information relevant to the sample being tested, such as patient information and quality control data.

Once all genomes are successfully uploaded, the API can be used to submit them for clinical reporting. It is also possible to create a clinical report that does not yet reference any genomes, and then attach the genomes at a later point in time using the Update Clinical Report endpoint.

Both family and panel reports can be launched using the Create Report endpoint.

For a family report (which can involve up to 4 family members in addition to the proband) the system will first ensure all requisite genomes are fully annotated, then run pertinent VAAST Solo and Trio analyses. The clinical report's submission for processing is contingent on all of its genomes and analyses running successfully to completion.

For a panel report, Opal™ will submit the report for processing as soon as its proband genome's annotation finishes.

If any of the genomes fail to annotate, or if there are issues with the VAAST runs, the system will send an email notification to the API User as well as the Fabric Genomics Support Team.

Once a clinical report has been created, the Post Patient Fields endpoint can be used to upload custom patient information.

To check a clinical report’s status, use the Get One Clinical Report endpoint and supply the ID of the report in question. Alternately, query all clinical reports by report status to at the Get Many Clinical Reports endpoint. In addition, reports can be found by accession, external ID or genome ID, also using the above endpoint.

Relevant example Python scripts: Clinical Report Workflows

Exporting Data

Once a clinical report has been completed and is ready to review, its variants can be interpreted using the Opal™ webapp, but can also be exported at any time using the API using the Get Variants endpoint. Variants of interest can be exported in JSON, CSV, or VCF format. The scoring information for variants can be exported using the Get Scored Variants endpoint. Scoring criteria, scoring status, and the scoring audit log can be exported in JSON format. After external validation has been performed, the variants’ status can be set using the Update Variant endpoint.

For auditing purposes, or to integrate with an external LIM system, it can be useful to have access to all information associated with the clinical report itself. To extract a full JSON representation of a clinical report the Get One Clinical Report endpoint will be of use.

The PDF output associated with an approved clinical report can also be exported using the Get Final PDF endpoint and stored locally. A preview PDF document can be exported from a clinical report in any other state using the Get PDF Preview endpoint.

Relevant example Python scripts: Clinical Report Workflows