---
title: "Using JavaScript Direct API Endpoints with the Lab Client"
slug: "using-javascript-direct-api-endpoints-with-the-lab-client"
updated: 2025-08-28T21:38:34Z
published: 2025-08-28T21:38:34Z
canonical: "docs.skillable.com/using-javascript-direct-api-endpoints-with-the-lab-client"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skillable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```javascript
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

```javascript
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.

> [!NOTE]
> 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

```javascript
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

```javascript
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

```javascript
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.

> [!NOTE]
> 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

```javascript
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.

> [!NOTE]
> 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

```javascript
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

```javascript
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

```javascript
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.

> [!NOTE]
> 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

```javascript
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

```javascript
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.

> [!NOTE]
> 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

```javascript
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.

> [!NOTE]
> 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

```javascript
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.

> [!NOTE]
> 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

```javascript
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.

> [!NOTE]
> 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

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

Variables store information and then that information can be recalled or used in the lab. Variables can be used in Life Cycle Actions, Automated Activities, and in lab instructions.