Overview

Use APIs to perform the following tasks in Connected Insights:

• Retrieve, edit, and delete case information including disease and case metadata. For more information, refer to Case APIs.

• For Connected Insights - Cloud, ingest cloud analysis data. For more information, refer to Ingest Cloud Analysis Data API (ConnectedInsights - Cloud Only).

• Pull report information, including PDF report drafts and case data. For more information, refer to Report APIs.

Prerequisites

Before using the APIs, make sure that the following prerequisites are met:

• Access to the Swagger site. Access this site by appending /api-docs to the Connected Insights host URL using one of following URL formats:

  • For Connected Insights - Cloud, use the URL format https://<domain>.connectedinsights.illumina.com/api-docs

  • For Connected Insights - Local, use one of the following URL formats depending on whether a fully-qualified domain name is configured:

    • If fully-qualified domain name is configured, use the URL format https://<DRAGEN server hostname>.<domain name>/api-docs

    • If fully-qualified domain name is not configured, use the URL format https://<DRAGEN server IP address>/api-docs

    For Connected Insights - Local, the URL will follow the same format as the URL used to login to Connected Insights (for example, if the login URL includes an IP address, the API URL will also include an IP address).

• Know the following authorization values. Instructions for finding all 3 of these values are below:

  • Authorization (apiKey or psToken/iasPsToken)

  • X-ILMN-Domain

  • X-ILMN-Workgroup

Authorization (apiKey or psToken/iasPsToken)

An API key or psToken/iasPsToken may be used. Consider the following before proceeding:

❗ Note the limitations below for API keys for Connected Insights - Cloud only:

• Regenerating an API key will break Data Uploaders using it until API key in the uploader config file is updated.

• If using the maximum number of API keys, consider using the psToken instead of regenerating an API key or deleting then creating a new API key.

• If using a global API key, API actions will be limited to the workgroup used for the X-ILMN-Workgroup authorization.

If using an API key, it is retrieved from the Manage API Keys section of Connected Insights. Retrieve the API key as follows.

1. From anywhere in Connected Insights, click your username in the top-right, then select Manage API Keys.

2. Click Generate, enter an API key name, then select workgroups and application roles.

   Selecting All current and future workgroups and roles (Global API Key) will still cause API actions to only occur in the workgroup for the X-ILMN-Workgroup authorization you provide later in Swagger. Selecting this option does not mean all API actions will occur in all workgroups.

   You may use an existing API Key if you recorded it and it pertains to the desired workgroup(s) and application role(s). For Connected Insights - Cloud users, consider the limitations above before regenerating an existing API Key.

3. Click Generate and copy the API key.

   This is the one time this value can be viewed. If you will use it again in the future, record and store the API key securely and do not share it with others. You cannot recover it later.

4. In another tab or window, go to the Swagger site. Select Authorize, then in the Available authorizations window, type ApiKey (including one space after) as a prefix followed by the API key value (for example, ApiKey <API key value>)

5. Select Authorize.

If using a psToken, it is retrieved from browser metadata where Connected Insights is being accessed:

1. In Connected Insights browser window, right-click and select Inspect.

2. From the Inspect pane, navigate to the top toolbar and select Application.

3. In the Storage section, select Cookies, then select the menu option with the same name as the Connected Insights URL.

4. In the Name column, copy one of the following values depending on whether you are using Connected Insights - Cloud or Local:

   • For Connected Insights - Cloud, select psToken and copy the psToken value that displays at the bottom of the pane.

   • For Connected Insights - Local, select iasPsToken and copy the iasPsToken value that displays at the bottom of the pane.

5. In another tab or window, go to the Swagger site. Select Authorize, then in the Available authorizations window, paste the psToken or iasPsToken value in the Authorization (apiKey) section Value field. No prefix is required before the psToken or iasPsToken value.

6. Select Authorize.

X-ILMN-Domain

The domain name is retrieved from the URL.

For Connected Insights - Cloud, retrieve the domain name as follows:

1. Copy the domain name from the URL for Connected Insights. For example, <domain> from https://<domain>.connectedinsights.illumina.com. Note that only the domain name is needed, not the entire URL.

2. In the Swagger Available authorizations window, enter the domain name into the X-ILMN-Domain (apiKey) section Value field.

3. Select Authorize.

For Connected Insights - Local, retrieve the domain name as follows:

1. From the Connected Insights URL, the following information from one of the Connected Insights URLs depending on whether a fully-qualified domain name is cofigured or not:

   • Copy the DRAGEN server v4 hostname if fully qualified Domain Name is configured. For example, <DRAGEN server v4 hostanme> from https://<DRAGEN server v4 hostname>.<domain name>/. Note that only the hostname is needed, not the entire URL

   • Copy the IP address of the DRAGEN server v4 if the fully-qualified Domain name is not configured. For example, <DRAGEN server v4 IP address> from https://<DRAGEN server v4 IP address>/.

2. In the Swagger Available authorizations window, paste the copied hostname or IP into the X-ILMN-Domain (apiKey) section Value field.

3. Select Authorize.

X-ILMN-Workgroup

The workgroup ID is found in the metadata of the Connected Insights browser. Retrieve the workgroup ID as follows.

1. In Connected Insights, right-click and select Inspect

2. On the Inspect pane at the right of the screen, navigate to the top ribbon and select Application. A pane opens to the left of the Inspect pane.

3. Navigate to the Storage section and select Cookies.

4. From the Name column, select olympia-current-workgroup and copy the Cookie Value that displays at the bottom of the pane (for example, a1bc2efg-h3i4-567j-8901-k23l45mno6p7).

5. In the Swagger Available authorizations window, paste the copied workgroup ID into the X-ILMN-Workgroup (apiKey) section Value field.

6. Select Authorize.