Using JavaScript Direct API Endpoints with the Lab Client

Overview

This article documents the Lab Client API (window.api.v1) endpoints used for JavaScript. For each endpoint, you'll find:

Event ID: Identifies the event associated with the message.
Description: Explains the endpoint’s behavior and context.
Request parameters: Lists the required fields to include in the message payload.
Returns: Describes the structure and content of the message returned.
Example: Provides a sample request to demonstrate usage.

General Notes

All methods are available via direct JavaScript (window.api.v1.methodName) and via postMessage for iframe integrations.
For event/callback registration, the callback will be triggered with the relevant data when the event occurs.

Endpoints

getEnvironmentConnectionStatus()

Description: Returns the current connection status of the lab environment (e.g., VM connection state). The response includes the environment type, machine ID, current status, and any error details (if available). Use this method to verify whether automation or user actions can proceed.

Request Parameters

None

Returns

Requests return an object with these properties:

Name	Type	Values	Description
`environment_type`	string	`none` or `machine`	Type of environment
`environment_type_code`	number	`0` or `1`	Numeric code for the environment type
`machine_id`	string or null	—	Unique ID of the machine, if available
`status`	string	`connected` or `disconnected`	Connection state
`status_code`	number	`0` or `1`	Numeric code for the status
`error`	string or null	—	Error message, if applicable

Example

const status = api.v1.getEnvironmentConnectionStatus();

getEnvironmentLatency()

Description: Returns the current latency in milliseconds (ms) between the lab client and the selected VM, allowing you to monitor connection responsiveness and troubleshoot network issues.

Request Parameters

None

Returns

Name	Type	Description
`number`	number	Latency in ms, or `0` if latency is unavailable

Example

const latency = api.v1.getEnvironmentLatency();

sendTextToEnvironment(text)

Description: Sends the provided text into the active VM console, enabling automation of commands, credentials, or guided lab steps. This method has no return value. Ensure the environment is connected before calling this method.

Response
This event does not return a response.

Request Parameters

Name	Type	Required?	Default Value	Description
`text`	string	Yes	—	The text or command to send to the VM console

Returns

None

Example

api.v1.sendTextToEnvironment("ls -la");

getLabToken(name)

Description: Retrieves the runtime value of a named lab token (without the @lab. prefix), which is used as a placeholder for dynamic content in instructions or scripts.

Request Parameters

Name	Type	Required?	Default Value	Description
`name`	string	Yes	—	The name of the lab token to retrieve, without the `@lab.` prefix

Returns

Name	Type	Description
`name`	string or null	The value of the requested lab token, or `null` if the token isn’t found

Example

const userName = api.v1.getLabToken("LabProfile.Name");

getLabVariable(name)

Description: Retrieves the value of a named lab Variable, which stores and shares state across the lab environment.

Request Parameters

Name	Type	Required?	Default Value	Description
`name`	string	Yes	—	The name of the lab variable to retrieve

Returns

Name	Type	Description
`name`	string or null	The value of the requested lab variable, or `null` if the variable isn’t found

Example

const value = api.v1.getLabVariable("myVariable");

setLabVariable(name, value)

Description: Sets or updates a named lab variable, making the specified value available to other scripts or instructions in the lab session.

Response
This event does not return a response.

Request Parameters

Name	Type	Required?	Default Value	Description
`name`	string	Yes	—	The name of the lab variable to set
`value`	string	Yes	—	The value to set on the lab variable

Returns

None

Example

api.v1.setLabVariable("myVariable", "newValue");

sendLabNotification(text)

Description: Displays a message in the lab client UI, typically as a toast popup, for alerts, confirmations, or guidance.

Response
This event does not return a response.

Request Parameters

Name	Type	Required?	Default Value	Description
`text`	string	Yes	—	The notification message to display in the lab client UI

Returns

None

Example

api.v1.sendLabNotification("Lab step completed!");

getInstructionsPageIndex()

Description: Returns the index of the currently displayed instructions page, allowing you to track progress or synchronize the UI.

Request Parameters

None

Returns

Name	Type	Description
`number`	number or null	The index of the current lab instructions page, or `null` if the index isn’t found

Example

const pageIndex = api.v1.getInstructionsPageIndex();

getMinutesRemaining

Description: Returns the number of minutes remaining in the lab session, which you can use to display countdowns or warn learners that time is running out.

Request Parameters

None

Returns

Name	Type	Description
`number`	number or `0`	The number of minutes remaining in the lab session, or `0` if unavailable

Example

const minutes = api.v1.getMinutesRemaining();

gotoInstructionsPage(index)

Description: Programmatically navigates to a specific instructions page by index, which you can use for guided experiences or LMS-driven navigation.

Response
This event does not return a response.

Request Parameters

Name	Type	Required?	Default Value	Description
`index`	number	Yes	—	The index of the instructions page to open

Returns

None

Example

api.v1.gotoInstructionsPage(2);

evaluateActivity(alias, index = 0)

Description: Triggers evaluation of a specific lab activity (e.g., check whether a lab step is complete), which you can use for progress tracking or gamification.

Request Parameters

Name	Type	Required?	Default Value	Description
`alias`	string	Yes	—	The unique identifier of the activity to evaluate, used to check whether the specified activity has been completed
`index`	number	No	`0`	The index of the activity to target when multiple activities share the same alias

Returns

None

Example

api.v1.evaluateActivity("step1");

onEnvironmentConnectionStatusChange(callback)

Description: Registers a callback that listens for changes in the lab environment’s connection status, receiving the updated status object whenever the VM connects or disconnects.

Response
This event does not return a response.

Request Parameters

Name	Type	Required?	Default Value	Description
`callback`	function	Yes	—	The function called with the status object when the connection status changes

Returns

None

Example

api.v1.onEnvironmentConnectionStatusChange((status) => {
  console.log("Connection status:", status);
});

onLabVariableChanged(callback)

Description: Registers a callback that listens for changes to lab variables, providing the variable name and its updated value.

Response
The event doesn’t return a response.

Request Parameters

Name	Type	Required?	Default Value	Description
`callback`	function	Yes	—	The function called with `(name, value)` when a variable changes

Returns

None

Example

api.v1.onLabVariableChanged((name, value) => {
  console.log(`Variable ${name} changed to ${value}`);
});

onInstructionsPageChanged(callback)

Description: Registers a callback that listens for instruction page changes, providing the new page index when the user navigates.

Response
This event doesn’t return a response.

Request Parameters

Name	Type	Required?	Default Value	Description
`callback`	function	Yes	—	The function called with `pageIndex` when the page changes

Returns

None

Example

api.v1.onInstructionsPageChanged((pageIndex) => {
  console.log("Now on page:", pageIndex);
});

onActivityCompleted(callback)

Description: Registers a callback that listens for lab activity completion events, providing an activityInfo object with details about the completed activity.

Response
This event doesn’t return a response.

Request Parameters

Name	Type	Required?	Default Value	Description
`callback`	function	Yes	—	The function called with `activityInfo` when an activity is completed

Returns

None

Example

api.v1.onActivityCompleted((activityInfo) => {
  console.log("Activity completed:", activityInfo);
});