# API Beginner Guide ## API Introduction It is possible to execute operations available in the Emedgene Curate graphical user interface (GUI) through the Emedgene Curate API as well. Following are some basic examples of how to use Emedgene Curate 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 () * The Python package installer, pip () * The requests library installed (run `pip install requests`) * Each API call requires the user to have the corresponding [role](https://help.connected.illumina.com/emedgene/emedgene-analyze-manual/settings/user_roles). ### Authentication In order to perform a secure session with Emedgene API servers you should first accomplish the authentication phase and retrieve the bearer token. To accomplish this, follow the Authentication steps [here](https://help.connected.illumina.com/emedgene/integrations/broken-reference). ### API Reference The different API commands can be found at https\://\.emedgene.com/api/kms/apidoc/swagger or https\://\.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 conversion steps [here](https://help.connected.illumina.com/emedgene/integrations/broken-reference). ## 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://.emg.illumina.com/api/kms/variants/v2/variants" headers = { "Authorization": "Bearer " } 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 = start = ref = url = f"https://.emg.illumina.com/api/api/kms/variants/v2/variants/search" headers = { "Authorization": "Bearer " } 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 = # Retrieved from the initial API response interpretation_id = # Retrieved from the initial API response url = f"https://.emg.illumina.com/api/kms/variants/v2/variants/{variant_id}/interpretations/{interpretation_id}" headers = { "Authorization": "Bearer " } 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 = # Retrieved from the initial API response url = f"https://.emg.illumina.com/api/kms/variants/v2/variants/{variant_id}" headers = { "Authorization": "Bearer " } 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://.emg.illumina.com/api/kms/genes/v1/genes" headers = { "Authorization": "Bearer " } 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 = url = f"https://.emg.illumina.com/api/kms/genes/v1/genes/search" headers = { "Authorization": "Bearer " } 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 = # Retrieved from the initial API response interpretation_id = # Retrieved from the initial API response url = f"https://.emg.illumina.com/api/kms/genes/v1/genes/{gene_id}/interpretations/{interpretation_id}" headers = { "Authorization": "Bearer " } 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://.emg.illumina.com/api/kms/export/v1/export/variants" headers = { "Authorization": "Bearer " } 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 {% hint style="info" %} The CSV format limits the number of characters per cell. Interpretations and notes exceeding 32,750 characters will be truncated. {% endhint %} ## Notes * Replace `` with the correct API server hostname. * Replace `` with a valid authentication token. * Ensure IDs used in update requests match those received from the initial response. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.connected.illumina.com/emedgene/integrations/api-beginner-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.