You can generate an API Key from your account console and use it with the API and command-line interface. Each user can create up to 10 API Keys. These keys are managed through the product dashboard, which you can access by logging into the Platform Dashboard (https://<domain>.login.illumina.com), navigating to the profile dropdown, and selecting "Manage API Keys."
To generate a new API Key, click Generate. You will need to name the API Key and decide whether to include all workgroups or select specific workgroups. The chosen workgroups will be accessible using this API Key.
After generating the API Key, it will be displayed (initially hidden). You can reveal the key to copy or download it to a file for secure storage. Remember, once you close the window, the key will no longer be accessible through the domain login page, so ensure it is stored securely for future use.
Store your API Key securely and refer to it when using the command-line interface or APIs.
For more information on how to use your API Key with Emedgene's API, check out the API Beginner Guide.
Emedgene allows seamless integration with other platforms via webhooks. By configuring webhooks, you can receive real-time updates on genomic data analyses. When an event occurs, Emedgene pushes relevant data to your specified URL, enabling automated workflows and immediate data synchronization with your systems. This integration simplifies data sharing and enhances the efficiency of your operations by keeping your platforms in sync with Emedgene’s insights.
Emedgene only supports webhooks for case status change, However there are plans to support any event in the platform. Please reachout to tech-support@illumina.com for additional support of other events.
When a confirmation test is required between analyst reviews, a webhook can notify the lab instantly. Here’s a sample workflow:
Initial Analysis: An analyst completes the primary genomic data analysis.
Webhook Trigger: Upon saving the analysis, a webhook is triggered, sending data to the lab’s system.
Notification: The lab receives a notification prompting them to perform a confirmation test.
Confirmation Test: The lab conducts the confirmation test and updates their system.
Webhook Response: A webhook sends the test results back to Emedgene for further analysis and final review by another analyst.
This ensures prompt action and efficient data flow between the lab and analysts.
When a case is finalized in Emedgene, you can use webhooks to pull reports through the API. Here’s an example workflow:
Webhook Configuration: Set up a webhook to trigger when a case status changes to "finalized."
Webhook Payload: The webhook sends a payload to your specified URL with details of the finalized case.
API Request: Your server intercepts the webhook and makes an API request to Emedgene to pull the final report.
Save Report: The server processes the API response and saves the report in your desired format and location.
By automating this process, you ensure timely and consistent retrieval of finalized reports.
Navigate to Settings: Go to the Settings section in Emedgene.
Navigate to Management: Under the Settings menu, select Management.
Scrool to Webhooks: Click on Webhooks within the Management page.
Add Webhook: Press the "Add webhook" button.
Configure Webhook Details: Enter the required webhook details such as URL, and secrets in the headers.
Save and Test: Save the webhook configuration and run a test to ensure it is working correctly.
This configuration enables efficient communication and data integration through webhooks.
View Webhook Logs: After configuring the webhook, press the "Manage" button to see the log of all sent events.
Inspect and Re-deliver: Click on an event to view its details, and use the "Re-deliver" button to resend the webhook event if necessary.
If there are no events you will have to change a case to the right status in order to create a test event.
Please contact Tech Support with the subject "BaseSpace Emedgene Connect app" for assistance.
Have a BaseSpace account
Have an Emedgene account
Add this BaseSpace as a Storage Provider in Emedgene - instructions
Add your BaseSpace user to the Emedgene Connect App whitelist
Go to
https://<domain>.api.basespace.illumina.com/v1pre3/users/current
Send the Href value to Tech Support with the subject "BaseSpace Emedgene Connect app"
"Href": "v1pre3/users/00000000"
On BaseSpace, go to Apps and search for Emedgene Connect Beta under All Categories
Click on the app and press Launch Application
Fill out the application setup
Choose an Analysis Name - this will be used for the setup analysis run
Choose a Biosample and Project for the setup - other projects and biosamples can be used later on
Enter the Emedgene URL in which to create cases
Enter your API key
Enable Setup Mode
Choose a Workflow name - this will be used in the BioSample Workflow sheet
Press Launch Application
When the app launches, an additional URL will be printed to the logs. Copy this URL to another tab and give the requested access to the app. The access granted will created the workflows used later in the BioSample Workflow Sheet.
Once the app setup analysis is completed successfully, press View Files next to the Logs window.
Go to Files and find the BioSample Workflow CSV template in the outputs directory.
Columns A-J hold the data to queue the Emedgene Connect Beta app launch.
BioSample Name
Default Project - the BaseSpace project to save the outputs to. Can be different than the project used for setting up the app.
Analysis Group - used for pedigree grouping, define a group id and set it for all pedigree samples.
Analysis Workflow - in the proband row only set the workflow name define in the app setup and the size of the pedigree.
emedgene-create-case_1
- singleton
emedgene-create-case_3
- trio
From column K onwards holds the data for the Emedgene Batch Upload. This data should follow the Batch Upload CSV requirements.
Upload the BioSample Workflow Sheet on BaseSpace under Biosamples.
Sample_ID needs to match the BioSampleName in the BioSample Workflow Sheet
ProjectName needs to match the Default Project in the BioSample Workflow Sheet
Upload the run with the Sample Sheet to BaseSpace via CLI (Command Line interface).
To set up the BaseSpace CLI see here.
<bs-path> upload run -n '<RunName>' -t <Instrument> . --concurrency=high
<RunName> should be set to the RunName from the Sample Sheet Headers
<Instrument> should be set to the InstrumentPlatform from the Sample Sheet Headers
<bs-path> should be set to the output of the command which bs
Once BCL Convert is completed for a BioSample from the BioSample Workflow sheet, the selected Analysis Workflow from the BioSample Workflow sheet will launch the Emedgene Connect Beta.
Please contact support.
Any operation from the Emedgene's graphical user interface (GUI) can also be performed by using the Emedgene's API.
Following are some basic examples of how to use Emedgene's API with Python.
For instructions on using the API with other programming languages, please refer to their respective documentation.
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
)
In order to perform a secure session with Emedgene's API servers you should first accomplish the authentication phase and retrieve the bearer token. The bearer token is further required to perform API requests on associated resources without extra identification. The token is valid for a predefined time. Once the bearer token is not valid, you will need to revalidate the token and accomplish the authentication phase again.
There are two ways to get your authentication token for your user before executing API calls:
To generate the authorization token, use your username and password as follows:
This is your Bearer token that will be used for the following API requests.
For Illumina domain users there are two options to authenticate your user and retrieve the Bearer token.
Illumina credentials - use your username and password
Using your API Key to generate the authentication token. To generate an API Key take a look API Key Generating. Copy your API Key to the code below instead of 'my-api-key'.
Either of these options will produce your Bearer token that will be used for the following API requests.
The different API commands can be found at https://<hostname>.emedgene.com/api/apidoc/swagger or https://<hostname>.emg.illumina.com/api/apidoc/swagger
It is useful to explore possible APIs and get an overview of the available parameters.
The examples in the API Reference page use curl (Client URL), while Python uses requests.
In order to get the curl command:
Find the endpoint you want to use on the API Reference page.
Select Try it out
.
Enter the necessary parameters.
Select Execute
.
Copy the resulting curl command.
Let's break down the parts of a curl command:
-X
specifies the request method to use when communicating with the HTTP server. By default, curl
performs a GET
request, but you can use the -X
option to set a different method, such as POST
, PUT
, DELETE
, etc.
-H
allows you to pass custom headers to the server.
-d
is used to send data in a POST
request to the server. This option implies using the POST
method.
To translate a POST
command to a Python request:
Translating a GET
command would be similar:
In the examples below, <hostname>.emedgene.com and <hostname>.emg.illumina.com are used indifferently.
The following examples will build the requests step-by-step, allowing you to execute them individually to understand their functionality, using the output of one request as the input for the next.
You can also use the GUI to obtain all the parameters or record them after executing the individual API calls in this section. Then, use these values to construct your final API call.
This example can be used as a simple way to verify your connection.
To validate the API request was completed successfully, check the HTTP response code.
HTTP 200 means the API call was successful. Learn more about HTTP response code here.
In order to pretty-print the JSON response and view it in a formatted way:
Tip: when returning lists (like lists of cases) Emedgene API uses pagination. It is possible to get the next items from the list using from and size, shown below.
Now that we are able to retrieve information with the API, let's continue by using it for a more practical request like retrieving the list of storage providers your user can access files from.
Your storage provider holds the sample files accessible for creating samples in a case.
To create a new case, multiple parameters need to be defined such as samples, the relationship between samples, phenotypes, genes and more. All the required details can be found in the API Reference page under /api/cases/v2/cases
.
Once the complete JSON defining the case details is complete, the case can be created as follows:
Once the case was created successfully, the response code expected is HTTP 201.
Use the case name to retrieve information about the case.
In order to know if the case has completed successfully, check the status as follows:
To get more information about a case, use the same API call as above without any test_fields
The response can be used to find which test fields are of interest and use them in the next API calls:
To retrieve the candidate variants of the completed case:
To retrieve candidate variants of the completed case with details such as transcript data, pathogenicity, ACMG tags and more: