API Beginner Guide

This guide provides instructions on using the Curate API to create, update, and search for variants and genes, and on exporting Curate data to a CSV.

API Introduction

Operations from the Emedgene Curate's graphical user interface (GUI) can also be performed by using the Emedgene Curate's API.

Following are some basic examples of how to use Emedgene Curate's API with Python.

For instructions on using the API with other programming languages, please refer to their respective documentation.

Prerequisites

• An installed copy of Python (https://www.python.org/)

• The Python package installer, pip (https://pip.pypa.io/)

• The requests library installed (run pip install requests)

• Each API call requires the user to have the corresponding role. See User roles for more information.

Authentication

In order to perform a secure session with Emedgene's API servers you should first accomplish the authentication phase and retrieve the bearer token. To accomplish this, follow the Authentication steps here.

API Reference

The different API commands can be found at https://<hostname>.emedgene.com/api/kms/apidoc/swagger or https://<hostname>.emg.illumina.com/api/kms/apidoc/swagger

It is useful to explore possible APIs and get an overview of the available parameters.

Creating Python requests from curl

The examples in the API Reference page use curl (Client URL), while Python uses requests. To convert from curl to Python follow the converstion steps here.

Examples

Variant

Create a New Variant

To create a new variant, send a POST request with the required variant details.

Request Example (Python):

import requests

url = "https://<hostname>.emg.illumina.com/api/kms/variants/v2/variants"
headers = {
    "Authorization": "Bearer <your-auth-token>"
}
data = {
    "chromosome": "3",
    "start": 122004036,
    "ref": "T",
    "alt": "C",
    "human_reference": "GRCh38",
    "variant_type": "SNV"
}

response = requests.post(url, json=data, headers=headers)

Response Fields:

The API response includes multiple fields, but the key values needed for future updates are:

• id: The unique identifier of the variant.

• variant_interpretation_ids: A list of interpretation IDs associated with the variant.

These fields are required for updating the variant later.

Search for a Variant by chromosome position

To retrieve variant details by chromosome position, send a GET request.

Request Example (Python):

import requests

chromsome = <chr>
start = <pos>
ref = <ref>

url = f"https://<hostname>.emg.illumina.com/api/api/kms/variants/v2/variants/search"
headers = {
    "Authorization": "Bearer <your-auth-token>"
}
params = {
    "human_reference": ref,
    chromosome: chr,
    start: start,
    operator="AND"
}

response = requests.post(url, params=params, headers=headers)

Update an Existing Variant

To modify a variant, use the PATCH method with the variant ID and interpretation ID retrieved from the creation response.

Request Example (Python):

import requests

variant_id = <variant-id>  # Retrieved from the initial API response
interpretation_id = <interpretation-id>  # Retrieved from the initial API response

url = f"https://<hostname>.emg.illumina.com/api/kms/variants/v2/variants/{variant_id}/interpretations/{interpretation_id}"
headers = {
    "Authorization": "Bearer <your-auth-token>"
}
data = {
    "id": variant_id,
    "interpretationId": interpretation_id,
    "transcript": "NM_XXXXXX"  # The updated transcript value
}

response = requests.patch(url, json=data, headers=headers)

Delete a Variant

To delete a variant, use the DELETE method with the variant ID from the response of the create, update, or search API responses.

import requests

variant_id = <variant-id>  # Retrieved from the initial API response

url = f"https://<hostname>.emg.illumina.com/api/kms/variants/v2/variants/{variant_id}"
headers = {
    "Authorization": "Bearer <your-auth-token>"
}

response = requests.delete(url, headers=headers)

Gene

Create a New Gene

New genes can only be created using a valid HGNC ID.

Request Example (Python):

import requests

url = "https://<hostname>.emg.illumina.com/api/kms/genes/v1/genes"
headers = {
    "Authorization": "Bearer <your-auth-token>"
}
data = {"id": "EMG_GENE_HGNC:XXXXX"}  # Replace with the relevant HGNC ID

response = requests.post(url, json=data, headers=headers)

Response Fields:

The API response contains multiple fields, but the key ones required for future updates are:

• id: The unique identifier of the gene.

• gene_interpretations: A list of interpretation IDs associated with the gene.

Search for a Gene by HGNC ID

To retrieve gene details by HGNC ID, send a GET request.

Request Example (Python):

import requests

hgnc_id = <hgnc-id> 

url = f"https://<hostname>.emg.illumina.com/api/kms/genes/v1/genes/search"
headers = {
    "Authorization": "Bearer <your-auth-token>"
}
params = {"q": hgnc_id}    # q is the key name for HGNC ID

response = requests.post(url, params=params, headers=headers)

It is also possible to search by NCBI ID in the same way as searching by HGNC ID.

Update an Existing Gene

To modify a gene, use the PATCH method with the gene ID and interpretation ID retrieved from the creation or search response.

Request Example (Python):

import requests

gene_id = <gene-id>  # Retrieved from the initial API response
interpretation_id = <interpretation-id>  # Retrieved from the initial API response

url = f"https://<hostname>.emg.illumina.com/api/kms/genes/v1/genes/{gene_id}/interpretations/{interpretation_id}"
headers = {
    "Authorization": "Bearer <your-auth-token>"
}
data = {
    "gene_id": gene_id,
    "id": interpretation_id,
    "transcript_ref_sequence": "NM_XXXXXX"  # The updated transcript value
}

response = requests.patch(url, json=data, headers=headers)

Export

In order to export all curated variants or genes as a CSV file, use the following API endpoints:

• Variants Export: /api/kms/export/v1/export/variants

• Genes Export: /api/kms/export/v1/export/genes

Each request returns a pre-signed URL, which can be used to download the exported file directly from a browser. Since its generation, the URL is valid for 12 hours.

Note: The export is updated every 24 hours, so any changes made in Curate will be reflected in the following day's export.

Request Example (Python):

import requests

url = f"https://<hostname>.emg.illumina.com/api/kms/export/v1/export/variants"
headers = {
    "Authorization": "Bearer <your-auth-token>"
}

response = requests.get(url, headers=headers)

Response Structure:

{"url":"https://s3.amazonaws.com/..........."}

It's possible to download the file by pasting the response URL in the browser.

The variant CSV will provide the following fields:

1. Variant Type

2. Pathogenicity

3. Chromosome

4. Position

5. End

6. REF

7. ALT

8. Interpretation

9. Notes

10. Diseases (OMIM ID)

11. Overlap %

The gene CSV will provide the following fields:

1. Gene Name

2. Group Type

3. Chromosome (37)

4. Start (37)

5. End (37)

6. Chromosome (38)

7. Start (38)

8. End (38)

9. NCBI ID

10. HGNC ID

11. Strand

12. Locus type

13. Interpretation

14. Note

15. Transcript reference sequence

16. Created epoch

The CSV format limits the number of characters per cell. Interpretations and notes exceeding 32,750 characters will be truncated.

Notes

• Replace <hostname> with the correct API server hostname.

• Replace <your-auth-token> with a valid authentication token.

• Ensure IDs used in update requests match those received from the initial response.