404: Resource not found.

Please return and try again

Rev 1.9.4

Black Box Corporation: Copyright © 2023

15

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

The associated definition of each API is listed as follows:

2.5.1 API for Editing REST Username

2.5.1.1 Request – Uri

Uri

bxa-api/users/rest/username

Method

PUT

2.5.1.2 Request – Params Requirement Name

Mandatory

username new_username

Type
String String

Description
Current username credential of the REST API user. Maximum length 64. New username credential of the REST API user to change to. Maximum length 64.

2.5.1.3 Request Body JSON Format
{ “username”: “[username]”, “new_username”: “[new_username]” }

2.5.1.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Successfully updated REST username.” }
2.5.1.5 Response ­ Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:

· Parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· The username credential provided in the parameters does not match the existing valid credential. The associated error message in the response body is as follows: “message”: “REST username [username] does not exist.”

Rev 1.9.4

Black Box Corporation: Copyright © 2023

16

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.5.1.6 Response ­ Error: REST Username Credential already Exists This error indicates that the new REST username credential to be updated to (specified by the “new_username” parameter) already exists.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Cannot update REST username to [new_username], [new_username] already exists.” }

2.5.1.7 Response ­ Error: Northbound REST API is not enabled for the REST User This error indicates that northbound REST API is disabled for the specified REST user specified by the “username” parameter.

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Editing REST authentication credentials is forbidden for user [username]. REST API is not accessible for this user.” }

2.5.2 API for Editing REST Password

2.5.2.1 Request – Uri

Uri

bxa-api/users/rest/password

Method

PUT

2.5.2.2 Request – Params Requirement Name

Mandatory

username new_password

Type
String String

Description
Current username credential of the REST API user. Maximum length 64. New password credential of the REST API user to change to. Maximum length 32.

Rev 1.9.4

Black Box Corporation: Copyright © 2023

17

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
2.5.2.3 Request Body JSON Format { “username”: “[username]”, “new_password”: “[new_password]” }
2.5.2.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Successfully updated REST user password.” }
2.5.2.5 Response ­ Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:
· Parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· The username credential provided in the parameters does not match the existing valid credential. The associated error message in the response body is as follows: “message”: “REST username [username] does not exist.”
2.5.2.6 Response ­ Error: Northbound REST API is not enabled for the REST User This error indicates that northbound REST API is disabled for the specified REST user specified by the “username” parameter.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Editing REST authentication credentials is forbidden for user [username]. REST API is not accessible for this user.” }

Rev 1.9.4

Black Box Corporation: Copyright © 2023

18

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.6 APIs for Versioning

This API is to get versioning information related to Boxilla components, including information of the following items each with fixed format:

· Boxilla software version o Format is [major_version].[minor_version].[patch].[build_number], e.g. 3.4.1.5120
· Northbound REST API version: fixed as “v1” for API version 1 · Boxilla model number: fixed as “BXAMGR” · Boxilla serial number: e.g. AEBB19B00022

2.6.1 Request – Uri

Uri

bxa-api/version

Method

GET

2.6.2 Request ­ Params This API does not require any parameters within the request body.

2.6.3 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: { “software-version”: “[boxilla software version]”, “api_version”: “v1”, “model_number”: “BXAMGR”, “serial_number”: “[boxilla serial number]” } }

2.7 APIs for Time-oriented Operations

This API is to retrieve current Boxilla time, including UTC time and Local time. All values are returned in epoch format.

· local_time ­ Boxilla local time (timezone aware) · utc_time ­ Boxilla UTC time

2.7.1 Request – Uri

Uri

bxa-api/time

Rev 1.9.4

Black Box Corporation: Copyright © 2023

19

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Method

GET

2.7.2 Request ­ Params This API does not require any parameters within the request body.

2.7.3 Response – Success
HTTP/1.1 200 OK
Content-Type: application/json;
Accept-version: v1.1
Body:
{ “code”: “200”, “message”: { “local_time”: “1648628865”, “utc_time”: “1648628865” }
}

2.8 APIs for User-oriented Operations
The APIs for Boxilla user operations include functionalities as follows:
· Creating new KVM users · Editing existing KVM user profiles · Deleting existing KVM users · Getting KVM users (individual/all) · Editing associations between KVM users and connections · Logging users in to KVM receivers · Logging users out from KVM receivers
The associated definition of each API is listed as follows:
2.8.1 API for Creating KVM Users
This API is to create a new KVM user in Boxilla using a valid credential set (username + password) from the API input parameters, together with the property set associated to the user. For each API request, one of the following categories of user property sets is defined with the relevant parameters passed in apart from the user credential (username/password):
· Unique property: user is created with a unique set of properties defined with the API request parameters. In this case the request of the API should contain the following parameters for the user property:

Rev 1.9.4

Black Box Corporation: Copyright © 2023

20

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

o privilege: identifying the privilege of the user, valid values including “Administrator”, “PowerUser” or “GeneralUser”.
o auto_connect: identifying whether the auto-connection option of the user property is enabled, valid values including “Yes” or “No”.
o auto_connect_name: identifying the name of the auto-connection if the property is enabled.
o remote_access: identifying whether access of the user profile via the remote windows application is enabled, valid values include “Yes” or “No”.
Version 1 of northbound REST API does not support user-related operations with non-unique properties, including template-based and system properties.

The “Requirement” column in the parameter table represents whether each parameter is mandatory, conditional-mandatory or optional, depending on specific values of some parameters as follows:

· Mandatory: the parameter is required · Conditionally Optional: the parameter is optional depending on values of one or more other
parameters.

2.8.1.1 Request – Uri

Uri

bxa-api/users/kvm

Method

POST

2.8.1.2 Request – Params

Requirement

Name

Type Description

Mandatory
Conditionally Optional

username password privilege remote_access auto_connect auto_connect_name

String String String String String String

Username credential of KVM user. Maximum length 64.
Password credential of KVM user. Maximum length 32.
User privilege. Valid values are: “Administrator” | “PowerUser” | “User”. (Case sensitive) Enabled/disabled option for remote app access. Valid values are “Yes” or “No”. (Case sensitive) Enabled/disabled option for auto- connection. Valid values are “Yes” or “No”. (Case sensitive) Name of the auto- connection if enabled. Maximum length 64. Applicable when “auto_connect” is “Yes”.

2.8.1.3 Request Body JSON Format
{ “username”: “[username]”, “password”: “[password]”, “privilege”: “Administrator” | “PowerUser” | “User”, “remote_access”: “Yes” | “No”,

Rev 1.9.4

Black Box Corporation: Copyright © 2023

21

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“auto_connect”: “Yes” | “No”, “auto_connect_name”: “[auto_connect_name]”, // only add it when “auto_connect” is “Yes” }
2.8.1.4 Response – Success
HTTP/1.1 201 Created
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “201”, “message”: “Created user [username].” }
2.8.1.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:
· Username/password or other required property parameters are passed in as empty or invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· When “auto_connect” is enabled, the provided “auto_connect_name” parameter value is not the name of any existing KVM connections. The associated error message in the response body is as follows: “message”: “Invalid parameter: auto_connect_name [auto_connect_name] does not point to any existing KVM connections.”
· “auto_connect_name” parameter is provided when “auto_connect” is disabled. The associated error message in the response body is as follows: “message”: “Invalid parameter: auto_connect_name [auto_connect_name] cannot be set when auto_connect is disabled. ”
2.8.1.6 Response – Error: License-related Failure This error response indicates that the Boxilla license installed on the server is invalid, expired or limitation of the maximum number of users is reached.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”,

Rev 1.9.4

Black Box Corporation: Copyright © 2023

22

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“message”: “License limit reached.” }

2.8.1.7 Response – Error: User Already Exists This error response indicates that a KVM user record with the specified username already exists and
the API request is attempting to create a duplicate record.

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Duplicate name received.” }

2.8.2 API for Editing KVM Users This API is to edit the profile/properties of an existing KVM user. The request of the API should contain the user profile/property parameters to be updated.

2.8.2.1 Request – Uri

Uri

bxa-api/users/kvm

Method

PUT

2.8.2.2 Request – Params

Requirement

Name

Type Description

Mandatory
Optional Conditionally Optional

username password privilege remote_access auto_connect new_username auto_connect_name

String String String String String String String

Username credential of KVM user. Maximum length 64. Password credential of KVM user. Maximum length 32. User privilege. Valid values are: “Administrator” | “PowerUser” | “User”. (Case sensitive) Enabled/disabled option for remote app access. Valid values are “Yes” or “No”. (Case sensitive) Enabled/disabled option for auto-connection. Valid values are “Yes” or “No”. (Case sensitive) New username to be edited. Maximum length 64. Username is updated if provided. Name of the auto-connection if enabled. Maximum length 64.

2.8.2.3 Request Body JSON Format {

Rev 1.9.4

Black Box Corporation: Copyright © 2023

23

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
“username”: “[username]”, “password”: “[password]”, “privilege”: “Administrator” | “PowerUser” | “User”, “remote_access”: “Yes” | “No”, “auto_connect”: “Yes” | “No”, “auto_connect_name”: “[auto_connect_name]” // only add it when “auto_connect” is “Yes” “new_username”: “[new_username]” // Optional, username is updated if provided }
2.8.2.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Updated profile/properties for user [username].” }
2.8.2.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:
· Required parameters are passed in as empty or invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· One or more KVM users within the username list parameter do not exist. The associated error message in the response body is as follows: “message”: “User [username] does not exist.”
· When “auto_connect” is enabled, the provided “auto_connect_name” parameter value is not the name of any existing KVM connections. The associated error message in the response body is as follows: “message”: “Invalid parameter: auto_connect_name [auto_connect_name] does not point to any existing KVM connections.”
· “auto_connect_name” parameter is provided when “auto_connect” is disabled. The associated error message in the response body is as follows: “message”: “Invalid parameter: auto_connect_name [auto_connect_name] cannot be set when auto_connect is disabled. ”
2.8.2.6 Response ­ Error: Changing Username to Name of Existing User This error response indicates that the new username to be changed to belongs to an existing user. The associated error message in the response body is as follows:

Rev 1.9.4

Black Box Corporation: Copyright © 2023

24

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Cannot update username to [new_username]. User [new_username] already exists.” }
2.8.2.7 Response ­ Error: Attempting to Edit Properties of non-Unique Users This error response indicates that the specified user is with non-unique properties. Editing properties of the user would be prohibited by the northbound REST API and a HTTP 403 error response is returned. The associated error message in the response body is as follows:
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: ” Editing properties for non-unique user [username] is not supported.” }

2.8.3 API for Deleting All KVM Users

This API is to delete all the existing KVM users with unique properties in Boxilla.

2.8.3.1 Request – Uri

Uri

bxa-api/users/kvm/all

Method

DELETE

2.8.3.2 Request ­ Params This API does not require any parameters within the request body. The version of API is included in the request header, as described in section 2.3.3.

2.8.3.3 Response – Success
HTTP/1.1 200 OK Accept: application/json; Content-Type: application/json; Accept-version: v1

Rev 1.9.4

Black Box Corporation: Copyright © 2023

25

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Body:
{ “code”: “200”, “message”: “Successfully deleted all users.” }
2.8.3.4 Response ­ Error: User Logged on Receivers or in Active Connection This error response indicates that one or more users are actively logged in receivers or are in active connections. The associated error message in the response body is as follows:
HTTP/1.1 409 Conflict
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “409”, “message”: “Fail to delete user(s) [list of active users] because one or more users are logged on receivers or in active connections.” }

2.8.4 API for Deleting Specific KVM Users This API is to delete one or more KVM users with unique properties in Boxilla, specified by the request parameter which contains a list of existing usernames to be deleted.

2.8.4.1 Request – Uri

Uri

bxa-api/users/kvm

Method

DELETE

2.8.4.2 Request – Params Requirement Name

Mandatory

usernames

Type
String array

Description
List of names of the KVM users to be deleted. If array is empty with no usernames inside, the API request is successful but no user would be deleted.

2.8.4.3 Request Body JSON Format
{ “usernames”: [“[username_1]”, “[username_2]”, …] }

2.8.4.4 Response – Success
HTTP/1.1 200 OK Accept: application/json; Content-Type: application/json;

Rev 1.9.4

Black Box Corporation: Copyright © 2023

26

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
Accept-version: v1 Body:
{ “code”: “200”, “message”: “Successfully deleted user(s) [usernames].” }
2.8.4.5 Response ­ Success with Empty Usernames Parameter
HTTP/1.1 204 No Content Accept: application/json; Content-Type: application/json; Accept-version: v1
2.8.4.6 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:
· Required parameters are passed in as empty (null parameter, not parameter as an empty array) or invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· “usernames” parameter is not an array (for example, an integer is given instead) or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter usernames: [usernames], expecting a String array.”
· One or more KVM users within the username list parameter do not exist. The associated error message in the response body is as follows: “message”: “The following user(s) do(es) not exist: [List of usernames do not exist]”
2.8.4.7 Response ­ Error: Attempting to Delete Users with non-Unique Properties This error response indicates that one or more KVM users specified in the parameters are with nonunique properties. Deleting these users would be prohibited by the northbound REST API and a HTTP 403 error response is returned. Meanwhile all the other valid users specified in the parameters would still be successfully deleted.
The associated error message in the response body is as follows:
HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1
Body:
{

Rev 1.9.4

Black Box Corporation: Copyright © 2023

27

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“code”: “403”, “message”: “The following users are with non-unique properties: [List of usernames].” }
2.8.4.8 Response ­ Error: User Logged on Receivers or in Active Connection This error response indicates that one or more users are actively logged in receivers or are in active connections. The associated error message in the response body is as follows:
HTTP/1.1 409 Conflict
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “409”, “message”: “Fail to delete user(s) [list of active users] because one or more users are logged on receivers or in active connections.” }

2.8.5 API for Getting KVM Users This API is to obtain one or more KVM users on Boxilla, specified by the request parameter.

2.8.5.1 Request – Uri

Uri

bxa-api/users/kvm

Method

GET

2.8.5.2 Request ­ Params

Requirement

Name

Optional
Note:

usernames

Type
String array

Description
List of names of the KVM users to get. If array is empty with no usernames inside, the API request is successful but no user would be returned in response body.

If no parameter is provided by the API request (parameter is null, not an empty array), the operation would be considered as getting all KVM users and the response is returned accordingly.

If the “usernames” parameter is an empty array, the API request is successful but no user is returned in the response (the “users” JSON array in response body is empty).

2.8.5.3 Request Body JSON Format
{ “usernames”: [“[username_1]”, “[username_2]”, …] // Optional, can be null or empty array }

Rev 1.9.4

Black Box Corporation: Copyright © 2023

28

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
2.8.5.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: { “users”: [
{ “username”: “[username]”, “privilege”: “Administrator” | “PowerUser” | “User”, “auto_connect”: “Yes” | “No”, “auto_connect_name”: “[auto_connect_name]”, // available if “auto_connect” is “Yes” “remote_access”: “Yes” | “No”, “connections”: [ {
“connection_name”: “[connection_name]” }, {….}, …. // if there are more connections ] }, {….}, // if there are more users …. ] } } In the “message”->”users” JSON array field in the response body, the following keys are mandatory (always be present) in each JSON element of the array:
· username · privilege · remote_access · auto_connect
The “auto_connection_name” key is conditionally optional based on the value of the “auto_connect” parameter. Meanwhile the value “connections” key depends on the associated connection list of the specified user.
2.8.5.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:

Rev 1.9.4

Black Box Corporation: Copyright © 2023

29

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”
· “usernames” parameter is not an array (for example, an integer is given instead) or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter usernames: [usernames], expecting a String array.”
· One or more KVM users within the username list parameter do not exist. The associated error message in the response body is as follows: “message”: “The following user(s) do(es) not exist: [List of usernames do not exist]”

2.8.6 API for Editing Associations between KVM Users and Connections This API is to edit the association between a KVM user and a list of KVM connections, each of which is either attached to or detached from the KVM user.

2.8.6.1 Request – Uri

Uri

bxa-api/users/kvm/connections

Method

PUT

2.8.6.2 Request – Params

Requirement Name

Type Description

username

String

Name of the KVM user that owns the list of KVM connections.

Mandatory

connection_names

String array

List of names of the KVM connections to be associated to the KVM user. Can be an empty array.

The operation of this API depends on the value of the connection_names parameter as follows:

· If the parameter includes one or more valid connection names, all existing associations of KVM connections to the specified KVM user are removed and a new user-connection association is created for each KVM connection included in the parameter to the KVM user.
· If the parameter is an empty array, all existing associations of KVM connections to the specified KVM user are removed.

2.8.6.3 Request Body JSON Format
{ “username”: “[username]”, “connection_names”: [“[connection_1]”, “[connection_2]”, …] //Mandatory, can be empty array }

2.8.6.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;

Rev 1.9.4

Black Box Corporation: Copyright © 2023

30

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Accept-version: v1
Body:
{ “code”: “200”, “message”: “Successfully updated connection associations for user [username].” }
2.8.6.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:

· Parameters are passed in as invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· “connection_names” parameter value is not an array or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter connection_names: [connection_names], expecting a String array.”
· No KVM user exists with the specified username parameter in the request body. The associated error message in the response body is as follows: “message”: “User [username] does not exist.”
· No KVM connections exist with the specified connection name parameters in the request body. The associated error message in the response body is as follows: “message”: “The following connection(s) do(es) not exist: [connection_names].”
· The maximum limit of connections (22500) can be associated to a user has been reached. The associated error message in the response body is as follows: “message”: “User connection limit reached.”

2.8.7 API for KVM User Login to Receivers This API is to login a KVM user to a specific receiver or group of receivers, with a force-login option enabled or disabled. Enabling force-login would log out the alternative KVM user logged in currently, while disabling force-login results in a failure of the API request when another KVM user is logged in. The KVM user can be an active directory user whose record is not managed on Boxilla.

The force-login option is set as a parameter within the request body. Valid parameters are listed in the parameter table below.

2.8.7.1 Request – Uri

Uri

bxa-api/users/kvm/login

Method

POST

2.8.7.2 Request – Params Requirement Name Type

Description

Rev 1.9.4

Black Box Corporation: Copyright © 2023

31

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Mandatory

username password
rx_list

String
String String array

forced String

Username of the KVM user for logging in. Password of the KVM user for logging in.
The list of receiver names that the user logs in.
String parameter indicates login operation is a force-login or not. Valid values are “Yes” or “No”. Note: force-login would break existing active connections

2.8.7.3 Request Body JSON Format
{
“username”: “[username]”, “password”: “[password]”, “rx_list”: [“[receiver_1]”, “[receiver_2]”, ….], // Mandatory, API does nothing if empty array is given “forced”: “Yes” | “No” }

2.8.7.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “User [username] has successfully logged in to the target receivers.” }

2.8.7.5 Response – Error: Bad Request This error response may be caused by:

· Parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· One or more receivers included in the rx-list parameter are offline. The associated error message in the response body is as follows: “message”: “The following receiver(s) to log in is(are) offline: [List of offline receiver names]”
· The login functions on one or more receivers included in the rx-list parameter are malfunctional. The associated error message in the response body is as follows: “message”: ” “User login failed on the following receiver(s): [List of malfunctional receiver names]”
· The KVM user specified by the username parameter does not exist. This happens when the provided user is neither managed by Boxilla, nor active directory option is enabled. The associated error message in the response body is as follows:

Rev 1.9.4

Black Box Corporation: Copyright © 2023

32

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“message”: “User [username] does not exist. ”

2.8.7.6 Response – Error: UnAuthorized This error response may be caused by:

· The REST user credentials included in the request header are invalid, as described in section 2.4.2.
· The user is a local user created on Boxilla and the login password provided in request parameters is incorrect. The associated error message in the response body is as follows: “message”: “Operation is not authorized due to invalid login credentials.”
· The user is an active directory user managed by active directory server and the login credentials for it are incorrect. The associated error message in the response body is as follows: “message”: ” Operation is not authorized. Active directory user authentication failed on one or more target receivers. Please check the active directory server configuration on your Boxilla and make sure the credentials are correct.”

2.8.7.7 Response – Error: Logging in with Force-Login Disabled while Alternative User is Logged in
This error response indicates that another user is logged in to one or more receivers listed in the rxlist parameter, with the force-login option disabled. In this case the non-force-login operation from the API request would be rejected.

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Another user is logged in target receiver(s) [rx_list with user logged in].” }

2.8.8 API for KVM User Logout from Specific Receivers This API is to log out a KVM user from a specific receiver or group of receivers. Valid parameters are listed in the parameter table below.

2.8.8.1 Request – Uri

Uri

bxa-api/users/kvm/logout

Method

POST

2.8.8.2 Request – Params

Requirement Name

Type

Description

Rev 1.9.4

Black Box Corporation: Copyright © 2023

33

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Mandatory Optional

username rx_list

String String array

forced

String

splash_screen String

Username of the KVM user for logging out.
List of receiver names that the user logs out.
An Integer number indicating that the login operation is a force-logout or not. Valid values are “Yes” or “No”. Note: force-logout would break existing active connections String indicating if the splash screen should be displayed following User Logout. Valid values are “Yes” or “No”.

2.8.8.3 Request Body JSON Format
{ “username”: “[username]”, “rx_list”: [“[receiver_1]”, “[receiver-2]”, ….], // Mandatory, API does nothing if empty array is given “forced”: “Yes” | “No”, “splash_screen”: “Yes” | “No” }

2.8.8.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “User [username] has successfully logged out to the target receivers.” }

2.8.8.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API)
returned, which might include:

· Parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· One or more receivers included in the rx-list parameter do not exist. The associated error message in the response body is as follows: “message”: “The following receiver(s) do(es) not exist: [List of non-exist receiver names].”
· One or more receivers included in the rx-list parameter are offline. The associated error message in the response body is as follows: “message”: “The following receiver(s) to log out from is(are) offline: [List of offline receiver names]”

Rev 1.9.4

Black Box Corporation: Copyright © 2023

34

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
· The KVM user specified by the username parameter does not exist. This happens when the provided user is neither managed by Boxilla, nor active directory option is enabled. The associated error message in the response body is as follows: “message”: “User [username] does not exist. ”
· User logout operation fails on one or more receivers due to internal issues. The associated error message in the response body is as follows: “message”: “User logout failed on the following receiver(s): [List of receiver names where logout failed]. Other users are successfully logged out.”
2.8.8.6 Response – Error: Logging out not Supported by Receiver Firmware This error response indicates that the firmwares on one or more receivers do not support the associated user-logoff functionality required by this API.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Logout via northbound REST API is not supported by the following receiver(s): [List of receivers not supporting user logout].” }
2.8.8.7 Response – Error: Logging out with Force-Logout Disabled while Connections associated to User are Active
This error response indicates that there are active connections associated to the user exist on one or more receivers the user attempts to log out from, when force-logout is disabled.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Active connections associated to user [username] exist in one or more target receivers.” }
2.8.8.8 Response – Error: User not Logged in Receivers This error response indicates that the KVM user specified by the username parameter is not logged in to one or more target receivers.

Rev 1.9.4

Black Box Corporation: Copyright © 2023

35

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “User [username] is not logged in to one or more of the following receivers: [List of receiver names the user is not logged in].” }

2.8.9 API for Editing User Favorites as Global or to Zones This API is to edit the favorite settings for an existing KVM user in Boxilla, whose scope can be global or within a specific zone.

2.8.9.1 Request – Uri

Uri

bxa-api/users/kvm/favs

Method

POST

2.8.9.2 Request – Params Requirement Name
username
scope
Mandatory
settings

Type
String String
JSON object

Description
Name of the KVM user with the favorite settings to be edited. Scope of the favorite settings for the KVM user. Valid values include: “” (empty string value) or a valid name of an existing zone in Boxilla. If scope is set as “”, the user favorite is configured as global in Boxilla and not assigned to any individual zone. Details of favorite settings for this user, containing a list of key/value pairs:
· key: the index number of the favorite hotkey where the connection is allocated in the favorite, string format with valid numeric values from “0” ­ “9”
· value: name of connection allocated to the related hotkey number, string format, can be empty value indicating that the connection is unallocated

2.8.9.3 Request Body JSON Format
{ “username”: “[username]”, “scope”: “” | “[zone_1]” | “[zone_2]” …., “settings”: { “[favorite/hotkey_number]”: [name of the connection allocated to hotkey], … // Potentially multiple settings key/value pairs, up to 10 with key ranging from “0” ­ “9” }

Rev 1.9.4

Black Box Corporation: Copyright © 2023

36

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
}

The following example of the request body shows how the favorite numbers and connection names are matched with each other in the “settings” parameter:
{ “username”: “user1”, “scope”: “zone1”, “settings”: { “0”: “connection1”, “3”: “connection4” }
}
The example request above allocates connection “connection1” to hotkey 0 and connection “connection4” to hotkey 3, and assigns the user favorite to zone “zone1” for user “user1”.
2.8.9.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1.1
Body:
{ “code”: “200”, “message”: “Successfully updated favorite settings for user [username] to [scope].” }
2.8.9.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:
· Parameters are passed in as invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· No KVM user exists with the specified username parameter in the request body. The associated error message in the response body is as follows: “message”: “User [username] does not exist.”
· No zone exists with the specified scope parameter in the request body, if the value is not global. The associated error message in the response body is as follows: “message”: “Zone [scope] does not exist for favorite settings for user [username].”
· One or more connections in the favorite settings JSON object do not exist. The associated error message in the response body is as follows:

Rev 1.9.4

Black Box Corporation: Copyright © 2023

37

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
“message”: “One or more connections do not exist.” · One or more connections in the favorite settings do not belong to the specified user. The
associated error message in the response body is as follows: “message”: “One or more connections in favorite settings do not belong to user [username].”
2.8.9.6 Response – Error: Connection not Assigned to Zone This error response indicates that one or more connections specified in the settings parameter are not assigned to the specified zone.
HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1.1
Body:
{ “code”: “403”, “message”: “Connection [connection_name] is not in zone [zone_name].” }
2.8.9.7 Response – Error: Favorite Settings Exceeding Limit This error response indicates that the number of favorite settings exceeds limit of 10, as favorite number is limited to 0-9.
HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1.1
Body:
{ “code”: “403”, “message”: “Favorite settings exceeding limit.” }
2.8.9.8 Response – Error: Duplicate Favorite Number for Multiple Connections This error response indicates that within the settings JSON object array parameter, multiple different connections are allocated to duplicate favorite number.
HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1.1
Body:

Rev 1.9.4

Black Box Corporation: Copyright © 2023

38

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

{ “code”: “403”, “message”: “Duplicate favorite number detected in request with multiple connection allocated.” }
2.8.9.9 Response – Error: Duplicate Connections for Multiple Favorite Numbers This error response indicates that within the settings JSON object array parameter, duplicate connections are allocated to multiple different favorite numbers.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1.1
Body:
{ “code”: “403”, “message”: “Duplicate connection detected in request allocated to multiple favorite numbers.” }
2.9 APIs for Device-oriented Operations

The APIs for device operations include functionalities as follows:

· Get KVM receivers/transmitters · Get all properties set on each KVM appliance · Get KVM appliance status and information · Set properties of KVM appliances · Reboot specific/all KVM appliances

The associated design of each API is listed as follows:

2.9.1 API for Getting KVM Appliances This API is to obtain the list of all the receivers/transmitters managed on the host Boxilla. Valid property parameters are listed in the parameter table below.

2.9.1.1 Request – Uri

Uri

bxa-api/devices/kvm

Method

GET

2.9.1.2 Request ­ Params

Requirement Name

Type

Optional

device_type String

Description
Type of device. Valid values are “transmitter” or “receiver”.

Rev 1.9.4

Black Box Corporation: Copyright © 2023

39

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Note:

device_names String array

List of names of KVM appliances to be obtained.

· If device_names parameter is null, the operation would be considered as getting all KVM appliances and the response is returned accordingly.
· If device_names parameter is an empty array, the API request is successful but the “devices” JSON array in the response body would be empty.
· If device_names is not null and contains valid device names, the value of device_type parameter would be ignored.
· If device_names is null and device_type is “transmitter” or “receiver”, the response would only contain the list of all the transmitters/receivers, respectively.

2.9.1.3 Request Body JSON Format
{ “device_type”: “receiver” | “transmitter”, “device_names”: [“[device_1]”, “[device_2]”, ….] }

// Optional, can be null // Optional, can be null or empty array

2.9.1.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: { “devices”: [
{ “name”: “[device_name]”, “ip”: “[ip]”, “mac”: “[MAC address]”, “model”: “[sales part number]”, “swversion”: “[firmware version]”, “serialno”: “[serial number]” }, …. // Multiple appliances ] } }

2.9.1.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API)
returned, which might include:

Rev 1.9.4

Black Box Corporation: Copyright © 2023

40

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”
· “device_names” parameter value is not an array or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter device_names: [device_names], expecting a String array.”
· One or more KVM appliances specified in the device_names parameter do not exist. The associated error message in the response body is as follows: “message”: “The following device(s) do(es) not exist: [List of device_names do not exist].”

2.9.2 API for Getting KVM Appliance Properties

This API is to obtain the property settings of each KVM appliance managed by the host Boxilla. Valid property parameters are listed in the parameter table below.

2.9.2.1 Request – Uri

Uri

bxa-api/devices/kvm/properties

Method

GET

2.9.2.2 Request ­ Params

Requirement Name

Optional
Note:

device_names

Type
String array

Description
List of names of the KVM devices managed in Boxilla.

· If device_names parameter is null, the operation would be considered as getting all KVM appliance properties and the response is returned accordingly.
· If device_names parameter is an empty array, the API request is successful but the “properties” JSON array in the response body would be empty.

2.9.2.3 Request Body JSON Format { “device_names”: [“[device-1]”, “[device-2]”, ….] }
2.9.2.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: {

// Optional, can be null or empty array

Rev 1.9.4

Black Box Corporation: Copyright © 2023

41

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“properties”: [ { “device_name”: “[device_name]”, “property_state”: “Configured” | “Waiting” | “Configuring”, “model”: “[sales part number]”, “swversion”: “[firmware version]”, “zone”: “[name of the zone to which the receiver is assigned]” // If device is receiver, available from API version 1.1 [List of supported properties] }, {….}, // If multiple properties …. ] } } Note:
In the response body, the “list of supported properties” tag composes of the properties supported by the requested KVM device, which may be different based on the manufactory brand/class and the firmware version of the KVM device. The full supported list of properties for various types of KVM devices is listed in table 2 in the appendix section 4.1.
The following three examples show cases of the JSON element in “properties” JSON array in the response body, with various values of keys determining the type of device.
Example 1:
{ “device_name”: “transmitter-A”, “property_state”: “Configured”, “model”: “EMD2002SE-T”, “swversion”: “V5.3.1_r5666”, “video_quality”: “Default”, “video_source_optimization”: “Off”, “hid_configurations”: “3”, “mouse_keyboard_timeout”: “0”, “edid_settings_dvi1”: “1920×1080”, “edid_settings_dvi2”: “1920×1200”
}

Example 2:

{
“device_name”: “transmitter-B”, “property_state”: “Configured”, “model”: “EMD4000T”, “swversion”: “V1.3.1_r5639”,

Rev 1.9.4

Black Box Corporation: Copyright © 2023

42

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“hid_configurations”: “3”, “mouse_keyboard_timeout”: “0” }
Example 3:
{ “device_name”: “receiver-A”, “property_state”: “Configured”, “model”: “EMD2000SE-R”, “swversion”: “V5.4.0_r6438”, “zone”: “zone 1”, // available from API version 1.1 “config”: “Unique”, “http_enabled”: “Enabled”
}
2.9.2.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:
· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”
· “device_names” parameter value is not an array or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter device_names: [device_names], expecting a String array.”
· One or more KVM appliances specified in the device_names parameter has corrupted typerelated properties. The associated error message in the response body is as follows: “message”: “Invalid property configuration for device [name of the device]: property conflict or missing.”
· One or more KVM appliances specified in the device_names parameter do not exist. The associated error message in the response body is as follows: “message”: “The following device(s) do(es) not exist: [List of device_names do not exist].”

2.9.3 API for Setting KVM Receiver Properties

This API is to update the unique property settings of individual KVM receiver managed by the host Boxilla. Valid property parameters are listed in the parameter table below.

2.9.3.1 Request – Uri

Uri

bxa-api/devices/kvm/properties/rx

Method

PUT

Rev 1.9.4

Black Box Corporation: Copyright © 2023

43

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.9.3.2 Request ­ Params Requirement Name
device_name http_enabled Mandatory zone

Type
String String
String

Description
Name of the KVM receiver managed in Boxilla. Maximum length 255. HTTP-enabled property to set. Valid values are “Enabled” or “Disabled”. Name of the zone this receiver is assigned to. Maximum length 32. This parameter is only applicable from API version 1.1 or newer. If parameter value is empty string, receiver would be unassigned from the zone it is currently assigined to (if any).

2.9.3.3 Request Body JSON Format
{ “device_name”: “[device_name]”, “http_enabled”: “Enabled” | “Disabled”, “zone”: “[name of the zone to which the receiver is assigned]” // can be empty string value }

2.9.3.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Receiver settings have been updated successfully.” }
2.9.3.5 Response ­ Error: bad request This error response may be caused by:

· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”
· The specified device has corrupted type-related properties. The associated error message in the response body is as follows: “message”: “Unknown type of device [device_name]. Device properties might be missing or corrupted.”
· Receiver is not found on Boxilla. The associated error message in the response body is as follows: “message”: “Device [device_name] does not exist.”

Rev 1.9.4

Black Box Corporation: Copyright © 2023

44

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· The property parameter values in the API request body are invalid or incompatible. The associated error message in the response body is as follows: “message”: “Parameters [list of params] are invalid or incompatible with firmware of receiver [device_name].”
· Receiver is offline. The associated error message in the response body is as follows: “message”: “Device [device_name] is offline. ”
· Operation fails on the receiver due to internal issues of the device firmware. The associated error message in the response body is as follows: “message”: “Device [device_name] is currently not functional.”
· The zone to be assigned does not exist on Boxilla. The associated error message in the response body is as follows: “message”: “Zone [zone] does not exist.”
2.9.3.6 Response ­ Error: attempting to set unique properties for receiver configured with non-unique properties
This error response indicates that the specified receiver in request parameters is configured with template or system properties at the moment. As northbound REST API version 1 supports unique device property configuration only, in this case the operation would be forbidden.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Receiver [device_name] is with template/system properties. Editing is enabled for unique properties only.” }
2.9.3.7 Response ­ Error: receiver firmware not supporting editing properties This error response indicates that the version of firmware deployed on the specified receiver in request parameters does not support editing properties. Usually this is caused by older versions of firmware without the associated appliance API.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”,

Rev 1.9.4

Black Box Corporation: Copyright © 2023

45

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“message”: “Firmware [firmware version] of [receiver model] receiver [device_name] does not support editing settings.” }

2.9.4 API for Setting KVM Transmitter Properties

This API is to set the property settings of individual KVM transmitter managed by the host Boxilla. Valid property parameters are listed in the parameter table below.

2.9.4.1 Request – Uri

Uri

bxa-api/devices/kvm/properties/tx

Method

PUT

2.9.4.2 Request ­ Params

Requirement Name

Type Description

Mandatory Conditional

device_name video_quality video_source_optimization
hid_configurations
mouse_keyboard_timeout

String String String
String
String

Name of the KVM transmitter managed in Boxilla. Maximum length 255.
Video quality property to set. Valid values are “Best Quality”, “2”, “Default”, “4” or “Best Compression”. (Case sensitive) Supported by single /dual-head Emerald-SE/EmeraldPE transmitters and ZeroU transmitters.
Video source optimization property to set. Valid values are “Off”, “DVI/DP Optimised”, “VGA High Performance”, “VGA – Optimised” or “VGA – Low Bandwidth”. (Case sensitive) Supported by single-head Emerald-SE/Emerald-PE and ZeroU transmitters.
HID property to set. Valid values are integer formatted strings from 0-5, which represents: 0 ­ Default; 1 ­ Basic; 2 ­ MAC; 3 ­ Absolute; 4 ­ Absolute MAC; 5 ­ Dual Mouse 0-3 are supported by all types of transmitters. 4 is supported by single/dual-head EmeraldSE/Emerald-PE and ZeroU with firmware version no older than 5.3.0, and Emerald-4K with firmware version no older than 1.3.1. 5 is supported by single/dual-head EmeraldSE/Emerald-PE and ZeroU with firmware version no older than 5.4.1, and Emerald-4K with firmware version no older than 1.3.1.
Mouse-keyboard timeout property to set. Valid values are integer formatted strings from 0-5, representing timeout in seconds. Supported by all single /dual-head EmeraldSE/Emerald-PE and ZeroU transmitters, and Emerald-4K transmitters with firmware version no older than 1.4.0.

Rev 1.9.4

Black Box Corporation: Copyright © 2023

46

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

edid_settings_dvi1 edid_settings_dvi2

String String

EDID DVI property to set for head 1 on transmitter.

Valid values are “1920×1080”, “1920×1200”,

“1680×1050”, “1280×1024” and “1024×768” for

Emerald-SE/PE/ZeroU transmitters, and “Default”,

“3840x2160p-60Hz”,

“3840x2160p-30Hz”,

“2560x1440p-60Hz”, “1920x1080p-60Hz” for

Emerald-4K transmitters. (Case sensitive)

Supported by all single/dual-head Emerald-

SE/Emerald-PE and ZeroU transmitters, and

Emerald-4K transmitters with firmware version no

older than 1.4.0.

EDID DVI property to set for head 2 on transmitter

(Dual-head only).

Valid values are the same with edid_settings_dvi1.

Supported by dual-head Emerald-SE and Emerald-PE

transmitters.

Note: for EDID DVI properties, this API does not support “Clone” as a valid value, which is different from the API to get transmitter properties.

2.9.4.3 Request Body JSON Format
// Only “device_name” is mandatory, the rest parameters are conditionally applicable as described above

{
“device_name”: “[device_name]”, “video_quality”: “Best Quality” | “2” | “Default” | “4” | “Best Compression”, “video_source_optimization”: “Off” | “DVI/DP Optimised” | “VGA – High Performance” | “VGA Optimised” | “VGA – Low Bandwidth”, “hid_configurations”: “0” | “1” | “2” | “3” | “4” | “5”, “mouse_keyboard_timeout”: “0” | “1” | “2” | “3” | “4” | “5”, “edid_settings_dvi1”: “1920×1080” | “1920×1200” | “1680×1050” | “1280×1024” | “1024×768” (5 possible values for Emerald-SE/PE/ZeroU) | “Default” | “3840x2160p-60Hz” | “3840x2160p-30Hz” | “2560x1440p-60Hz” | “1920x1080p-60Hz” (5 possible values for Emerald-4K), “edid_settings_dvi2”: “1920×1080” | “1920×1200” | “1680×1050” | “1280×1024” | “1024×768” }

2.9.4.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Transmitter settings have been updated successfully.” }

Rev 1.9.4

Black Box Corporation: Copyright © 2023

47

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.9.4.5 Response ­ Error: bad request This error response may be caused by:

· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”
· The specified device has corrupted type-related propeties. The associated error message in the response body is as follows: “message”: ” Unknown type of device [device_name]. Device properties might be missing or corrupted.”
· Transmitter is not found on Boxilla. The associated error message in the response body is as follows: “message”: “Device [device_name] does not exist. ”
· The property parameter values in the API request body are invalid or incompatible. The associated error message in the response body is as follows: “message”: “Parameters [list of params] are invalid or incompatible with firmware of transmitter [device_name].”

The following response shows an example of incompatible parameters:

HTTP/1.1 400 Bad Request
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “400”, “message”: “Parameters video_quality’ andvideo_source’ are invalid or incompatible with firmware of transmitter `Emerald4K-TX-1′.” }
2.9.4.6 Response ­ Error: attempting to set unique properties for transmitter configured with non-unique properties
This error response indicates that the specified transmitter in request parameters is configured with template or system properties at the moment. As northbound REST API version 1 supports unique device property configuration only, in this case the operation would be forbidden.

HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1
Body:
{

Rev 1.9.4

Black Box Corporation: Copyright © 2023

48

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“code”: “403”, “message”: “Transmitter [device_name] is with template/system properties. Editing is enabled for unique properties only.” }
2.9.4.7 Response ­ Error: transmitter firmware not supporting editing properties This error response indicates that the version of firmware deployed on the specified transmitter in request parameters does not support editing properties. Usually this is caused by older versions of firmware without the associated appliance southbound REST API.

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Firmware [firmware version] of [transmitter model] transmitter [device_name] does not support editing settings.” }

2.9.5 API for Setting KVM Receiver Zone assignment This API is to update the zone the specified receiver is assigned to.

2.9.5.1 Request – Uri

Uri

bxa-api/devices/kvm/rx/zones

Method

POST

2.9.5.2 Request ­ Params Requirement Name

Type

device_name String

Mandatory zone

String

Description
Name of the KVM receiver managed in Boxilla. Maximum length 255. Name of the zone this receiver is assigned to. Maximum length 32. If provided with an empty string value, receiver would be unassigned from the zone currently assigined to (if any).

2.9.5.3 Request Body JSON Format
{ “device_name”: “[device_name]”, “zone”: “[name of the zone to which the receiver is assigned]” }

Rev 1.9.4

Black Box Corporation: Copyright © 2023

49

Boxilla Northbound REST API V1.9.4 Release for External Manager
ENG-007-100100
2.9.5.4 Response ­ Success Reassignment to New Specified Zone
HTTP/1.1 200 OK Accept: application/json; Content-Type: application/json; Accept-version: v1.1 Body:
{ “code”: “200”, “message”: “Receiver [device_name] has been successfully reassigned to zone [zone].” }
2.9.5.5 Response ­ Success Unassignment to Original Zone (if any)
HTTP/1.1 200 OK Accept: application/json; Content-Type: application/json; Accept-version: v1.1 Body:
{ “code”: “200”, “message”: “Receiver [device_name] has been successfully unassigned from zone [original_zone].” }
2.9.5.6 Response ­ Error: bad request This error response may be caused by:
· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”
· Receiver is not found on Boxilla. The associated error message in the response body is as follows: “message”: “Receiver [device_name] does not exist.”
· The zone to be assigned does not exist on Boxilla. The associated error message in the response body is as follows: “message”: “Zone [zone] does not exist.”
· Receiver is offline. The associated error message in the response body is as follows: “message”: “Receiver [device_name] is offline.”
· Reassignment of receiver to zone fail due to the embedded software issue. The associated error message in the response body is as follows: “message”: “Receiver [device_name] is currently not functinoal.”

Rev 1.9.4

Black Box Corporation: Copyright © 2023

50

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.9.6 API for Getting KVM Appliance Status This API is to obtain the real-time status of one or more KVM appliances managed by the host Boxilla, including the following contents:

· Information of logged-in users (receiver-only) · Information of the zone it is assigned to. This is only applicable if the device is a receiver and
assigned to a zone, for API version >= 1.1. · Information of active connections · Physical online/offline status · Appliance setting update status:
o Waiting: setting update is initializing. o Configuring: setting update is processing. o Configured: setting update is complete. o Note: as editing appliance settings using APIs in section 2.8.3 and 2.8.4 involve
communications with appliances and may take extra time, this GET API should be used to monitor the configuration state of appliance settings as needed. · Appliance details: o Basic: name; model number; serial number; firmware version o A unique identifier generated internally by individual Boxilla instance at the initialization state of managing the device o Operational details: total/free memory/storage; uptime; load average in 1/5/15 minutes o Network details: mac; ip; netmask; gateway; broadcast; primary/secondary DNS; multicast-ip and master port

Valid property parameters are listed in the parameter table below.

2.9.6.1 Request – Uri

Uri

bxa-api/devices/kvm/status

Method

GET

2.9.6.2 Request ­ Params

Requirement Name

Optional

device_names

Type
String array

Description
List of names of the KVM devices managed in Boxilla.

2.9.6.3 Request Body JSON Format
{ “device_names”: [“[device-1]”, “[device-2]”, ….] }

// Optional, can be null or empty array

2.9.6.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;

Rev 1.9.4

Black Box Corporation: Copyright © 2023

51

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: { “devices”: [
{ “uid”: “[Unique identifier generated internally by Boxilla for each device]”, “device_type”: “receiver” | “transmitter”, “zone”: “[Name of the zone it is assigned to]”, // This is applicable only if device is receiver “logged_in user”: { // Available for request to receivers only, empty if no user logged in “username”: “[logged-in username]”, “type”: “active directory user” | “common user” }, “active_connections”: [ {
“active_connection_name”: “[active_connection_name]”, “active_connection_type”: “Private” | “Shared”, “active_connection_group”: “ConnectViaTx” | “VM” | “VMPool” | “VMHorizon” | “TXPair”, }, {….}, // if there are more active connections …. ], “state”: “Online” | “Offline”, “status”: “Waiting” | “Configuring” | “Configured”, “device_name”: “[appliance-name]”, “mac”: “[MAC address]”, “ip”: “[ip]” }, {….}, // if there are more appliances …. ] } }
2.9.6.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API)
returned, which might include:

· Parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.) The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· One or more KVM devices specified by the device_names parameter do not exist on Boxilla. The associated error message in the response body is as follows: “message”: “The following device(s)do(es) not exist: [non_exist_device_names]. ”

Rev 1.9.4

Black Box Corporation: Copyright © 2023

52

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· One or more KVM devices specified by the parameter are currently offline. The associated error message in the response body is as follows: “message”: “[offline_device_names] currently offline. ”

2.9.7 API for Rebooting all KVM Appliances

This API is to send reboot command to all KVM appliances managed by the host Boxilla.

2.9.7.1 Request – Uri

Uri

bxa-api/devices/kvm/reboot-all

Method

POST

2.9.7.2 Request ­ Params This API does not require any parameters within the request body. The version of API is required to be included in the request header.

2.9.7.3 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “All KVM devices are successfully rebooted.” }

2.9.7.4 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API)
returned, which might include:

· One or more KVM devices to be rebooted are currently offline. The associated error message in the response body is as follows: “message”: “The following device(s) to reboot is(are) offline: [offline_device_names]. ”
· Rebooting operation fails on one or more devices due to internal issues. The associated error message in the response body is as follows: “message”: “Fail to reboot the following device(s): [List of device names where rebooting failed].”

2.9.7.5 Response – Error: Rebooting via API not Supported by Device Firmware This error response indicates that the firmwares on one or more devices specified in the parameters
do not support the associated device rebooting functionality required by this API.

HTTP/1.1 403 Forbidden

Rev 1.9.4

Black Box Corporation: Copyright © 2023

53

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Rebooting via northbound REST API is not supported by the following device(s): [List of devices not supporting rebooting].” }

2.9.8 API for Rebooting selected KVM Appliances

This API is to send reboot command to individual KVM appliance managed by the host Boxilla. Valid parameters are listed in the parameter table below.

2.9.8.1 Request – Uri

Uri

bxa-api/devices/kvm/reboot

Method

POST

2.9.8.2 Request ­ Params

Requirement Name

Type

Optional

device_names

String array

Description
List of names of KVM devices managed in Boxilla to be rebooted.

2.9.8.3 Request Body JSON Format
{ “device_names”: [“[device-1]”, “[device-2]”, ….], }

// Optional, can be null or empty array

2.9.8.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “The selected KVM device(s) is(are) successfully rebooted.” }

2.9.8.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API)
returned, which might include:

Rev 1.9.4

Black Box Corporation: Copyright © 2023

54

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
· Parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· “device_names” parameter value is not an array or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter device_names: [device_names], expecting a String array.”
· One or more KVM appliances specified in the device_names parameter do not exist. The associated error message in the response body is as follows: “message”: “The following device(s) do(es) not exist: [List of device_names do not exist].”
· One or more KVM devices to be rebooted are offline. The associated error message in the response body is as follows: “message”: “The following device(s) to reboot is(are) offline: [offline_device_names]. ”
· Rebooting operation fails on one or more devices due to internal issues. The associated error message in the response body is as follows: “message”: “Fail to reboot the following device(s): [List of device names where rebooting failed].”
2.9.8.6 Response – Error: Rebooting via API not Supported by Device Firmware This error response indicates that the firmwares on one or more devices specified in the parameters do not support the associated device rebooting functionality required by this API.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Rebooting via northbound REST API is not supported by the following device(s): [List of devices not supporting rebooting].” }

2.10 APIs for Connection-oriented Operations
The APIs for connection-related operations include the following functionalities:
· Create new KVM connections between multiple BlackBox entities (transmitters/receivers, VMs, etc. that exchange traffic)
· Edit existing KVM connection properties · Deleting existing KVM connection records · Make/break KVM active connections

Rev 1.9.4

Black Box Corporation: Copyright © 2023

55

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

In Boxilla, each KVM connection active record is categorized into the following list of groups, based on the type of traffic source in the connection:

· ConnectViaTx: the traffic source is a transmitter device · VM: the traffic source is a VM · VMPool: the traffic source is a group of VMs · VMHorizon: the traffic source is a VM with horizontal view · TXPair: dual traffic sources exist from multiple transmitters
Creating/editing of each group of KVM connection is designed with the specific set of properties for as input parameters, whose associated requirements are defined as follows:

· Mandatory: the parameter is required · Unique Params: the parameter is required when creating/editing unique connections, including
the following categories: o ConnectViaTx Params: the parameter is optionally applicable for viaTx connections o VM Params: the parameter is optionally applicable for VM connections o VMPool Params: the parameter is optionally appliable for VM pool connections o VMHorizon Params: the parameter is optionally applicable for VM horizontal connections o TXPair Params: the parameter is optionally applicable for TXPair connections
The following table defines the conditional parameters for each category of unique connection:

Requirement viaTx Params VM Params

Name extended_desktop usb_redirection audio persistent
cmode
username password extended_desktop usb_redirection

Type String String String String
String
String String String String

Description
Enabled/disabled option for extended desktop configuration. Valid values are “Yes” or “No”. (Case sensitive) Enabled/disabled option for USB redirection. Valid values are “Yes” or “No”. (Case sensitive) Enabled/disabled option for audio. Valid values are “Yes” or “No”. (Case sensitive) Enabled/disabled option for connection persistency. Valid values are “Yes” or “No”. (Case sensitive) Compression mode supported for 2K-4K compatibility feature. Valid values are “0” or “10”. “0” represents lossless mode and “10” represents optimized mode. Lossless mode 0 is valid only when the host of the connection is an Emerald-4K transmitter. Username credential used for BlackBox VM login. Optional. Valid value needs to be the username of an existing user. Password credential used for BlackBox VM login. Optional unless “username” is provided. Valid value needs to be in pair with a valid username. Enabled/disabled option for extended desktop configuration. Valid values are “Yes” or “No”. (Case sensitive)
Enabled/disabled option for USB redirection.

Rev 1.9.4

Black Box Corporation: Copyright © 2023

56

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Valid values are “Yes” or “No”. (Case sensitive)

audio

String

Enabled/disabled option for audio. Valid values are “Yes” or “No”. (Case sensitive)

Port number (in numeric format) of the VM connected to (if

port

String applicable).

Maximum length 5.

domain

String

Domain name of the VM connected to (if applicable). Maximum length 255.

nla

String

Enabled/disabled option for NLA. Valid values are “Yes” or “No”. (Case sensitive)

extended_desktop

String

Enabled/disabled option for extended desktop configuration. Valid values are “Yes” or “No”. (Case sensitive)

VM-Pool Params

usb_redirection

String

Enabled/disabled option for USB redirection. Valid values are “Yes” or “No”. (Case sensitive)

audio

String

Enabled/disabled option for audio. Valid values are “Yes” or “No”. (Case sensitive)

Username credential used for BlackBox VM login.

username

String Optional.

Valid value needs to be the username of an existing user.

VM-Horizon

Password credential used for BlackBox VM login.

Params

password

String Optional unless “username” is provided.

Valid value needs to be in pair with a valid username.

protocol

String

Protocol used for VM Horizon view connections. Valid value is “PCoIP” only. (Case sensitive)

host_2

String

IP/DNS address of the secondary traffic source of the KVM connection.

audio

String

Enabled/disabled option for audio. Valid values are “Yes” or “No”. (Case sensitive)

persistent

String

Enabled/disabled option for connection persistency. Valid values are “Yes” or “No”. (Case sensitive)

pairing_type

String

Pairing type specified for TxPair connection. Valid values are “1” or “2”.

TxPair Params

Orientation of dual paired views of TxPair connections. Required only when “pairing_type” is set to “2”.

orientation

String

Valid values are “H12”, “H21”, “V12” or “V21” (Case sensitive), where “H/V” stands for Horizontal/Vertical and

“12/21” represents destination from view 1 to view 2 or

reverse.

Address of the audio source.

audio_source

String

Required only when “audio” is set as “Yes”. Valid values are “1” or “2”, representing whether the audio

source is specified as the value of host or host_2.

Table 1. KVM Connection Property Dependency based on Group of Connection (viaTx/VM/VMPool/VMHorizon/TxPair)

The details of the API for each group of KVM connection are introduced in the sections below, respectively.

2.10.1 API for Creating KVM Connections

Rev 1.9.4

Black Box Corporation: Copyright © 2023

57

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

This API is to create a new KVM connection with type, group and properties specified within the parameters in request body.

2.10.1.1 Request – Uri

Uri

bxa-api/connections/kvm

Method

POST

2.10.1.2 Request – Params

Requirement Name

Type Description

name host group

Mandatory

connection_type

view_only

zone

viaTx Params
VM Params VM-Pool Params VM-Horizon Params TxPair Params

String String String
String String String

Name of the KVM connection. Maximum length 64. IP/DNS address of the primary traffic source of the connection. Value cannot be set if “group” is “VMPool”. Connection group category. Valid values are: “ConnectViaTx” | “VM” | “VMPool” | “VMHorizon” | “TXPair”. (Case sensitive) Connection type. Valid values are “Private” or “Shared”. (Case sensitive) Value is fixed to be “Private” when “group” is set as “VM”, “VMPool” or “VMHorizon”. Enabled/disabled view-only option. Valid values are “Yes” or “No”. (Case sensitive) Name of the zone this connection is assigned to. Maximum length 32. If provided with empty string value, connection is not assigned to any zone.
Required when “group” is “ConnectViaTx”. “usb_redirection” parameter value cannot be “Yes” if “connection_type” is “Shared”. “cmode” parameter value can be “0” only when the host of the connection is an Emerald-4K transmitter.
Required when “group” is “VM”.
Required when “group” is “VMPool”.
Required when “group” is “VMHorizon”.
Required when “group” is “TXPair”.

2.10.1.3 Request Body JSON Format ­ viaTx Connections
{
“name”: “[connection_name]”, “host”: “[host]”, “group”: “ConnectViaTx”, “connection_type”: “Private” | “Shared”, “extended_desktop”: “Yes” | “No”, “usb_redirection”: “Yes” | “No”, “audio”: “Yes” | “No”, “persistent”: “Yes” | “No”, “view_only”: “Yes” | “No”,

Rev 1.9.4

Black Box Corporation: Copyright © 2023

58

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“cmode”: “0” | “10”, “zone”: “Zone 1” // Can be empty string }

2.10.1.4 Request Body JSON Format ­ VM Connections
{
“name”: “[connection_name]”, “host”: “[host]”, “group”: “VM”, “connection_type”: “Private”, “username”: “[VM-login username]”, “password”: “[VM-login password]”, “extended_desktop”: “Yes” | “No”, “usb_redirection”: “Yes” | “No”, “audio”: “Yes” | “No”, “port”: “[port]”, “domain”: “[domain]”, “nla”: “Yes” | “No”, “view_only”: “Yes” | “No” }

2.10.1.5 Request Body JSON Format ­ VM-Pool Connections
{
“name”: “[connection_name]”, “host”: “[host]”, “group”: “VMPool”, “connection_type”: “Private”, “extended_desktop”: “Yes” | “No”, “usb_redirection”: “Yes” | “No”, “audio”: “Yes” | “No”, “view_only”: “Yes” | “No” }

2.10.1.6 Request Body JSON Format ­ VM-Horizon Connections
{
“name”: “[connection_name]”, “host”: “[host]”, “group”: “VMHorizon”, “connection_type”: “Private”, “username”: “[VM-login username]”, “password”: “[VM-login password]”, “protocol”: “PCoIP”, “view_only”: “Yes” | “No” }

2.10.1.7 Request Body JSON Format ­ TxPair Connections { “name”: “[connection_name]”,

Rev 1.9.4

Black Box Corporation: Copyright © 2023

59

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“host”: “[host]”, “host_2”: “[host_2]”, // Optional “group”: “TXPair”, “connection_type”: “Private” | “Shared”, “audio”: “Yes” | “No”, “persistent”: “Yes” | “No”, “view_only”: “Yes” | “No”, “pairing_type”: “1” | “2”, “orientation”: “H12” | “H21” | “V12” | “V21”, // applicable only when “pairing_type” is “2” “audio_source”: “1” | “2” // applicable only when “audio” is “Yes” }
2.10.1.8 Response – Success
HTTP/1.1 201 Created
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “201”, “message”: “Created [group] connection [name].” }
2.10.1.9 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:
· Property-related parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· The zone to be assigned does not exist on Boxilla. The associated error message in the response body is as follows: “message”: “Zone [zone] does not exist.”
· Multiple property-related parameters are not compatible with each other, e.g. passing the connection_type parameter as “shared” together with the group parameter as “VM, “VMPool” or “VMHorizon”. (Check the parameter table for this API for details). The associated error message in the response body is as follows: “message”: “Parameters [List of incompatible parameters] are incompatible with [group] connection [name].” The following response shows an example of incompatible parameters:
HTTP/1.1 400 Bad Request
Accept: application/json;
Content-Type: application/json;

Rev 1.9.4

Black Box Corporation: Copyright © 2023

60

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Accept-version: v1
Body:
{ “code”: “400”, “message”: “Parameters connection_type’:Shared’ are incompatible with VM connection `connection-1′.” }
2.10.1.10 Response – Error: License-related Failure This error response indicates that the Boxilla license installed on the server is invalid, expired or limitation of the maximum number of users is reached.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “License limit reached.” }

2.10.1.11 Response – Error: Connection Already Exists This error response indicates that a KVM connection with the name specified in request body already exists and the API is attempting to create a duplicate record.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Duplicate name received.” }

2.10.2 API for Editing KVM Connection Profiles/Properties

This API is to edit the profile/properties of an existing KVM connection whose type, group and properties are specified within the parameters in request body.

2.10.2.1 Request – Uri

Uri

bxa-api/connections/kvm

Method

PUT

Rev 1.9.4

Black Box Corporation: Copyright © 2023

61

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.10.2.2 Request – Params

Requirement Name

Type Description

name host group

Mandatory

connection_type view_only

zone

Optional

new_name

viaTx Params
VM Params VM-Pool Params VM-Horizon Params TxPair Params

String String String String String
String
String

Name of the KVM connection. Maximum length 64. IP/DNS address of the primary traffic source of the connection. Value cannot be set if “group” is “VMPool”. Connection group category. Valid values are: “ConnectViaTx” | “VM” | “VMPool” | “VMHorizon” | “TXPair”. (Case sensitive) Connection type. Valid values are “Private” or “Shared”. (Case sensitive) Value is fixed to be “Private” when “group” is set as “VM”, “VMPool” or “VMHorizon”. Enabled/disabled view-only option. Valid values are “Yes” or “No”. (Case sensitive) Name of the zone this connection is assigned to. Maximum length 32. This parameter is only applicable from API version 1.1 or newer. If parameter is provided with empty string, connection would be unassigned from the zone it is currently assigined to (if any). New name of the KVM connection to be edited. Maximum length 64. Connection name is updated if provided. Required when “group” is “ConnectViaTx”. “usb_redirection” parameter value cannot be “Yes” if “connection_type” is “Shared”. “cmode” parameter value can be “0” only when the host of the connection is an Emerald-4K transmitter.
Required when “group” is “VM”.
Required when “group” is “VMPool”.
Required when “group” is “VMHorizon”.
Required when “group” is “TXPair”.

2.10.2.3 Request Body JSON Format For each group of connection (viaTx, VM, VM- Pool, VM-Horizon or TxPair), the request is individually defined in the same JSON format specified in section 2.9.1.3 – 2.9.1.7, respectively, with the additional “new_name” parameter available. If the “new_name” parameter is specified with a valid value (nameformat string; max-length 64; obeying the naming rules defined in section 4.3.1), the name of the connection would be updated with the value.

2.10.2.4 Response – Success
HTTP/1.1 200 OK Accept: application/json; Content-Type: application/json;

Rev 1.9.4

Black Box Corporation: Copyright © 2023

62

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Updated properties for connection [name].” }
2.10.2.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:
· Property-related parameters are passed in as empty or invalid (contain invalid characters; length exceeding limit; etc.). The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]. ”
· Multiple property-related parameters are not compatible with each other, e.g. passing the connection_type parameter as “shared” together with the group parameter as “VM, “VMPool” or “VMHorizon”. (Check the parameter table for this API for details). The associated error message in the response body is as follows: “message”: “Parameters [List of incompatible parameters] are incompatible with [group] connection [name].”
· The associated KVM connection record does not exist. The associated error message in the response body is as follows: “message”: “Connection [name] does not exist.”
· The zone to be assigned does not exist on Boxilla. The associated error message in the response body is as follows: “message”: “Zone [zone] does not exist.”
2.10.2.6 Response ­ Error: Attempting to Edit Properties of non-Unique Connections This error response indicates that the specified connection is with non-unique properties. Editing properties of the connection would be prohibited by the northbound REST API and a HTTP 403 error response is returned. The associated error message in the response body is as follows:
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: ” Editing properties for non-unique connection [name] is not supported.” }

Rev 1.9.4

Black Box Corporation: Copyright © 2023

63

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.10.2.7 Response ­ Error: Changing Connection Name to Name of Existing Connection This error response indicates that the new connection name to be changed to belongs to an existing connection. The associated error message in the response body is as follows:

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Cannot update connection name to [new_name]. Connection [new_name] already exists.” }

2.10.3 API for Deleting all KVM Connections This API is to delete all the existing KVM connections with unique properties in Boxilla.

2.10.3.1 Request – Uri

Uri

bxa-api/connections/kvm/all

Method

DELETE

2.10.3.2 Request ­ Params This API does not require any parameters within the request body. The version of API is included in the request header.

2.10.3.3 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Successfully deleted all connections.” }

2.10.3.4 Response – Error: Connection is Active This error response indicates that one or more KVM connections to be deleted are active with traffic
delivery when the request is being operated.

HTTP/1.1 409 Conflict Accept: application/json;

Rev 1.9.4

Black Box Corporation: Copyright © 2023

64

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “409”, “message”: ” Fail to delete connection(s) [connection_names] because one or more connections are active.” }

2.10.4 API for Deleting Specific KVM Connections This API is to delete one or more existing KVM connections with unique properties in Boxilla, specified by the request parameter which contains a list of existing connection names to be deleted.

2.10.4.1 Request – Uri

Uri

bxa-api/connections/kvm

Method

DELETE

2.10.4.2 Request – Params

Requirement Name

Type Description

Mandatory

connection_names

String array

List of names of the KVM connections to be deleted. If array is empty with no connection names inside, the API request is successful but no connection would be deleted.

2.10.4.3 Request Body JSON Format
{ “connection_names”: [“[connection_1]”, “[connection_2]”, …] // Mandatory, can be empty array }

2.10.4.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Successfully deleted connection(s) [connection_names].” }
2.10.4.5 Response ­ Success with Empty Connection_names Parameter
HTTP/1.1 204 No Content
Accept: application/json;
Content-Type: application/json;

Rev 1.9.4

Black Box Corporation: Copyright © 2023

65

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100
Accept-version: v1
2.10.4.6 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:
· Required parameters are passed in as empty (null parameter, not parameter as an empty array) or invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as empty or invalid]”
· “connection_names” parameter is not an array (for example, an integer is given instead) or any elements within are not String type. The associated error message in the response body is as follows:
· “message”: “Invalid parameter connection_names: [connection_names], expecting a String array.”
· One or more KVM connections specified in the connection_names parameter do not exist. The associated error message in the response body is as follows: “message”: “The following connection(s) [connection_names] do(es) not exist.”
2.10.4.7 Response ­ Error: Attempting to Delete Connections with non-Unique Properties This error response indicates that one or more KVM connections specified in the parameters are with non-unique properties. Deleting these connections would be prohibited by the northbound REST API and a HTTP 403 error response is returned. Meanwhile all the other valid connections specified in the parameters would still be successfully deleted.
The associated error message in the response body is as follows:
HTTP/1.1 403 Forbidden Accept: application/json; Content-Type: application/json; Accept-version: v1
Body:
{ “code”: “403”, “message”: “The following connections are with non-unique properties: [List of connection names].” }
2.10.4.8 Response – Error: Connection is Active This error response indicates that one or more KVM connections to be deleted are active with traffic delivery when the request is being operated.
HTTP/1.1 409 Conflict Accept: application/json;

Rev 1.9.4

Black Box Corporation: Copyright © 2023

66

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “409”, “message”: ” Fail to delete connection(s) [connection_names] because one or more connections are active.” }

2.10.5 API for Getting KVM Connection Status This API is for obtaining status and related information of one or more KVM connections in Boxilla, including the following contents:

· Name of user that logs into the KVM appliance of the connection · Connection type: Private or Shared · Connection group: ConnectViaTx, VM, VM-pool, VM- horizon or TXPair · A unique identifier generated internally by individual Boxilla instance at the initialization state
of creating the connection

Valid property parameters are listed in the parameter table below.

2.10.5.1 Request – Uri

Uri

bxa-api/connections/kvm

Method

GET

2.10.5.2 Request ­ Params

Requirement Name

Type

Description

Optional
Note:

connection_names String array List of names of the queried KVM connections

If no parameter is provided by the API request (parameter is null, not an empty array), the operation would be considered as getting status of all KVM connections and the response is returned accordingly.

If the “connection_names” parameter is an empty array, the API request is successful but no connection status is returned in the response (the “connections” JSON array in response body is empty).

2.10.5.3 Request Body JSON Format
{ “connection_names”: [“[connection_1]”, “[connection_2]”, …] empty array }

// Optional, can be null or

Rev 1.9.4

Black Box Corporation: Copyright © 2023

67

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.10.5.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: { “connections”: [
{ “uid”: “[Unique identifier generated internally by Boxilla for each connection]”, “name”: “[connection_name]”, “host”: “[IP/DNS of primary connection source]”, “connection_type”: “Private” | “Shared”, “group”: “ConnectViaTx” | “VM” | “VMPool” | “VMHorizon” | “TXPair”, “zone”: “[name of the zone to which the connection is assigned]”, “view_only”: “Yes” | “No”, [List of supported properties] }, {….}, // if there are more connections …. ] } } Note:

In the response body, the “list of supported properties” tag composes of the properties of the requested KVM connection, which may be different based on the group of connection. The full supported list of properties for each group of connection is listed in table 1 at the beginning of section 2.9.

“Password” property for VM/VMHorizon connection would NOT be returned.
The following three examples show cases of the JSON element in “connections” JSON array in response body for various groups of KVM connections.

Example 1:

{
“name”: “tx-connection-1”, “host”: “10.0.2.20”, “connection_type”: “Shared”, “group”: “ConnectViaTx”, “zone”: “zone 1”,
“extended_desktop”: “Yes”,

Rev 1.9.4

Black Box Corporation: Copyright © 2023

68

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

“usb_redirection”: “No”, “audio”: “Yes”, “persistent”: “Yes”, “view_only”: “No”, “cmode”: “10”
}

Example 2:
{ “name”: “vm-connection-2”, “host”: “10.0.2.21”, “connection_type”: “Private”, “group”: “VM”, “username”: “James”, “extended_desktop”: “Yes”, “usb_redirection”: “No”, “audio”: “Yes”, “port”: “3389”, “domain”: “test.com”, “nla”: “Yes”, “view_only”: “No”
}
Example 3:
{ “name”: “txpair-connection-3”, “host”: “10.0.2.22”, “connection_type”: “Private”, “group”: “TXPair”, “host_2”: “10.0.2.23”, “audio”: “Yes”, “persistent”: “Yes”, “view_only”: “No”, “pairing_type”: “2”, “orientation”: “H12”, “audio-source”: 1
}
2.10.5.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:
· Required property parameters are passed in as invalid. The associated error message in the response body is as follows: “message”: “Invalid parameter(s): [List of parameters detected as invalid].”

Rev 1.9.4

Black Box Corporation: Copyright © 2023

69

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· “connection_names” parameter is not an array (for example, an integer is given instead) or any elements within are not String type. The associated error message in the response body is as follows: “message”: “Invalid parameter connection_names: [connection_names], expecting a String array.”
· One or more KVM connections within the connection_name parameter do not exist. The associated error message in the response body is as follows: “message”: “The following connection(s) do(es) not exist: [List of connections do not exist]”

2.10.6 API for Launching KVM Active Connections This API is for launching a KVM active connection based on an existing KVM connection record. Requests of this API require authentication using the credentials of the REST API user described in section 2.3.2.

Before the operation of launching the connection, the user specified in the request is logged on to the target receiver forcefully by this API.

2.10.6.1 Request – Uri

Uri

bxa-api/connections/kvm/active

Method

POST

2.10.6.2 Request – Params Requirement Name

Type Description

username

String Name of the KVM user logged in to the receiver.

Mandatory

password connection_name receiver_name

String String String

Password of the KVM user logged in to the receiver.
Name of KVM connection as the active connection traffic source. Name of the receiver used to launch the active connection.

2.10.6.3 Request Body JSON Format { “username”: “[username]”, “psaaword”: “[password]”, “connection_name”: “[connection_name]”, “receiver_name”: “[receiver_name]” }
2.10.6.4 Response – Success
HTTP/1.1 201 Created
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:

Rev 1.9.4

Black Box Corporation: Copyright © 2023

70

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

{ “code”: “201”, “message”: “Active connection [connection_name] is successfully launched.” }

2.10.6.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API)
returned, which might include:

· The source or destination (the receiver and transmitter/VM) does not exist. The associated error message in the response body is as follows: “message”: “Active connection [connection_name] or receiver [receiver_name] does not exist.”
· The user specified in the username parameter does not exist. The associated error message in the response body is as follows: “message”: “User [username] does not exist.”
· The source or destination (the receiver and transmitter/VM) is offline. The associated error message in the response body is as follows: “message”: “Active connection [connection_name] or receiver [receiver_name] is currently unreachable.”
· The embedded software on the KVM devices is mal-functional. The associated error message in the response body is as follows: “message”: “Active connection [connection_name] or receiver [receiver_name] is currently not functional.”

2.10.6.6 Response – Error: UnAuthorized This error response may be caused by:

· The REST user credentials included in the request header are invalid, as described in section 2.4.2.
· The user is a local user created on Boxilla and the login password provided in request parameters is incorrect. The associated error message in the response body is as follows: “message”: “Operation is not authorized due to invalid login credentials.”
· The user is an active directory user managed by active directory server and the login credentials for it are incorrect. The associated error message in the response body is as follows: “message”: ” Operation is not authorized. Active directory user authentication failed on one or more target receivers. Please check the active directory server configuration on your Boxilla and make sure the credentials are correct.”

2.10.6.7 Response – Error: Launching Active Connection not Supported by Device Firmware This error response indicates that the version of firmware deployed on the specified receiver in request parameters does not support launching active connections. Usually this is caused by older versions of firmware without the associated appliance southbound REST API.

Rev 1.9.4

Black Box Corporation: Copyright © 2023

71

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: ” Launching active connection is not supported by firmware type [receiver model] version [firmware version] of receiver [receiver_name].” }

2.10.6.8 Response – Error: Connection not Assigned to Logged-in User This error response indicates that the source KVM connection to be launched is not assigned to the logged-in KVM user on the receiver.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “Connection [connection_name] not assigned to user [username].” }

2.10.6.9 Response – Error: User Login Timeout on Receiver This error response indicates that a timeout has occurred during the specified user login on the receiver.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: “User [username] login timeout on receiver [receiver_name].” }

2.10.7 API for Terminating KVM Active Connections This API is to break an existing KVM active connection between a source/destination pair. Requests of this API require authentication using the credentials of the REST API user described in section 2.3.2.

Rev 1.9.4

Black Box Corporation: Copyright © 2023

72

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

2.10.7.1 Request – Uri

Uri

bxa-api/connections/kvm/active

Method

DELETE

2.10.7.2 Request – Params

Requirement Name

Type Description

Mandatory Optional

username connection_name receiver_name
splash_screen

String String String
String

Name of the KVM user logged in to the receiver.
Name of KVM connection as the active connection traffic source. Name of the receiver used to terminate the active connection
String indicating if the splash screen should be displayed following Connection Termination. Valid values are “Yes” or “No”.

2.10.7.3 Request Body JSON Format
{
“username”: “[username]”, “connection_name”: “[connection_name]”, “receiver_name”: “[receiver_name]”, “splash_screen”: “Yes” | “No” }

2.10.7.4 Response – Success
HTTP/1.1 200 OK
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “200”, “message”: “Active connection [connection_name] is successfully terminated.” }
2.10.7.5 Response – Error: Bad Request This error response indicates any non- specific error (may be caused by internal errors within the API) returned, which might include:

· The source or destination (the receiver and transmitter/VM) does not exist. The associated error message in the response body is as follows: “message”: “Active connection [connection_name] or receiver [receiver_name] does not exist.”
· The user specified in the username parameter does not exist. The associated error message in the response body is as follows: “message”: “User [username] does not exist.”

Rev 1.9.4

Black Box Corporation: Copyright © 2023

73

Boxilla Northbound REST API V1.9.4 Release for External Manager

ENG-007-100100

· Receiver is offline. The associated error message in the response body is as follows: “message”: “Receiver [receiver_name] is unreachable.”
· The embedded software on the KVM device is mal-functional. The associated error message in the response body is as follows: “message”: “Active connection [connection_name] or receiver [receiver_name] is currently not functional.”
2.10.7.6 Response – Error: Terminating Active Connection not Supported by Device Firmware This error response indicates that the version of firmware deployed on the specified receiver in request parameters does not support terminating active connections. Usually this is caused by older versions of firmware without the associated appliance API.
HTTP/1.1 403 Forbidden
Accept: application/json;
Content-Type: application/json;
Accept-version: v1
Body:
{ “code”: “403”, “message”: ” Terminating active connection is not supported by firmware type [receiver model] version [firmware version] of receiver [receiver_name].” }

2.10.7.7 Response – Error: Connection not Active This error response indicates that the specified connection in the parameter to be terminated is not active at the mome

References

• Test.com is for sale

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>