Command API - JSON

Overview

The Command API is designed to send commands to your Remote Support site from an outside application. Commands can start or transfer a session, get a list of logged-in Representatives, or obtain a list of teams and issues. You can also check the health of your appliance, change an appliance's failover role, or get information about the permissions of the current API Account.

Authentication

The Remote Support Command APIs require OAuth 2 credentials for authentication. To authenticate to the API, you must create an API account on the /login > Management > API Configuration page. The account must have permission to access the Command APIs. Copy the OAuth Client ID and OAuth Client Secret values before saving the API Account. API requests require a token to be generated using this client id and secret and then submitted with each API request.

ℹ️

The OAuth Client Secret cannot be viewed again after the API Account has been saved, but it can be regenerated when you edit the API Account. Regenerating a client secret and then saving the account immediately invalidates any OAuth tokens associated with the account. Any API calls using those tokens are unable to access the API. A new token must be generated using the new client secret.

The command API URL is https://support.example.com/api/command/v2.

Create a token

Create a token by sending an HTTP POST request to the URL of your BeyondTrust Remote Support site followed by /oauth2/token:

https://support.example.com/oauth2/token

The OAuth client ID and client secret associated with the API account should be Base64 encoded and included in an HTTP basic authorization header:

Authorization: Basic <base64-encoded "client_id:secret">

Include the following POST body in the request:

grant_type=client_credentials

If the request is processed without error, you receive an access token JSON response:

{
    "access_token": "<token>",
    "token_type": "Bearer",
    "expires_in": 3600
}

ℹ️

This token expires after one hour. Any calls to the API past that point must have a new token. Each API account can have a maximum of 30 valid tokens. If an API account attempts to generate more than 30 tokens, then the oldest token is invalidated before a new one is generated.

Request an API resource

Now that you have an access token, you can make HTTPS requests to the Command APIs. The token obtained above must be included in an Authorization HTTP header with each request:

Authorization: Bearer <token>

If the token is valid, you gain access to the requested URL.

Authentication errors

Requests made to the web API with expired or invalid tokens result in a JSON error response:

{
    "error": "access_denied",
    "message": "The resource owner or authorization server denied the request."
}

🚧

When making consecutive API calls, you must close the connection after each API call.

Request rate limits

Requests are limited to 20 per second and 15,000 per hour. This limit applies to all API endpoints and is per API account. Responses include headers with the rate limit information: Example:

X-RateLimit-Limit: 15000
X-RateLimit-Remaining: 14996

Required Request Headers

In addition to the Authorization header mentioned above for OAuth 2 authentication:

• for GET and DELETE requests, you must include an Accept header with the value application/json.
• for all other requests where you are sending a JSON request body, you must include a Content-Type header with a value of application/json.

HTTP Request Methods

The documentation below lists the allowed HTTP request methods for each API. Not all methods are allowed for all APIs.

All APIs that document GET requests also accept HEAD requests. Responses to HEAD requests never include a body. This might be useful if you only wish to use the HTTP status code to determine the existence of a resource or resources identified by the URI, and you do not need the response body.

In addition to the human-readable documentation for each API below, the OPTIONS method may be used with any URI to obtain the list of allowed HTTP methods for a given URI.

For example, the request

OPTIONS https://support.example.com/api/command/v2/user

responds with an Allow header containing a comma-separated list of the HTTP methods that can be used with that URI:

Allow: GET,HEAD

If you attempt to use an HTTP method with an API that does not support that method, you receive an HTTP 405 "Method Not Allowed" response.

Common HTTP Status Codes

Individual APIs may provide specific documentation for certain status codes, but not all possible status codes are documented on every API. The following is a list of the HTTP status codes commonly returned by these APIs and what they usually mean.

Date-Time Formatting and Time Zones

All date-time values should be in RFC3339 Internet Date-Time Format in UTC unless otherwise noted. When submitting date-time values to these APIs, milliseconds are optional and are ignored. A UTC timezone must be included to avoid ambiguity, represented with either the "Z" suffix or a "+00:00" offset suffix.

Valid Examples

• 2025-10-16T14:46:25.930+00:00
• 2026-10-16T14:46:23+00:00
• 2025-10-16T14:46:25.930Z
• 2026-10-16T14:46:23Z

Invalid Examples

• INVALID 2025-10-16T14:46:25.930: Missing timezone; not a valid RFC3339 string.
• INVALID 2026-10-16T14:46:23: Missing timezone; not a valid RFC3339 string.
• INVALID 2025-10-16T14:46:25.930-08:00: Non-UTC timezone; valid RFC3339 string but not allowed by these APIs.
• INVALID 2026-10-16T14:46:23+04:00: Non-UTC timezone; valid RFC3339 string but not allowed by these APIs.

Date-time strings in responses always include a "+00:00" timezone offset suffix - never a "Z" suffix.

Integers

Request body parameters that are marked as type "integer" must be supplied as actual JSON numbers, not strings containing a number. For example, if the documentation indicates a request body field named team_id is an integer, then the object {team_id: 42} is valid, but the object {team_id: "42"} is invalid.

Changes

From time to time, new fields may be added to existing API responses to support new features, without changing any existing fields. Ensure that your client code is written in such a way it can handle or ignore these minor additions to existing API responses.

Base Path

The base path on all API call URLs must be /api/command/v2. In the documentation below, the base path is omitted for brevity. When constructing the URL for a particular API, combine your hostname, the base path, and then the documented path of the API you wish to call. For example, the full URL for the API to get a user with a specific id is:

"https://" + "support.example.com" (hostname) + "/api/command/v2" (base path) + "/user/{id}" (API path)

If you wanted to get the user with id 5, your final URL would be

<https://support.example.com/api/command/v2/user/5>

Miscellaneous

GET /openapi.yaml

Returns a YAML document containing an OpenAPI specification for all available BeyondTrust Remote Support Command APIs. Many tools exist that can read this document and generate useful resources, such as:

• Client code for interacting with the API
• Various forms of API documentation

ℹ️

If you're reading this on a web page, the page was likely generated from a response to this API.

Responses

API Info

GET /info

Returns general information about the Command APIs, such as version, as well as the permissions of the API Account whose credentials were used to authenticate the request.

Responses

Schema

permissions object - The current API Account's permissions.

Top-level fields

Health

GET /health

Returns appliance health and status information needed for failover purposes.

ℹ️

If this request is sent more than once per minute, a cached response may be returned.

Responses

Appliances

GET /appliance

Returns information about all configured appliances, including their failover role and cluster role.

Responses

GET /appliance/client-count

Get a list of appliances along with counts for each type of client connected to that appliance.

Query Parameters

Responses

Clients

GET /client

Get details of all connected BeyondTrust Remote Support clients, optionally filtered by client type.

Query Parameters

Responses

GET /client/{id}

Get details of a connected client identified by {id}.

ℹ️

The id is only valid while the client is connected. Requests for a client that has since disconnected return 404.

Path Parameters

Responses

GET /client/{id}/connections

Get a list of connections and an event log about those connections for the client with the given {id}.

ℹ️

The id is only valid while the client is connected. Requests for a client that has since disconnected return 404.

Path Parameters

Responses

Sessions

POST /session-key

Creates a new session key to be used in starting a support session.

ℹ️

Multiple Public Sites

If your appliance has multiple public sites, the session key may be associated with different sites depending on how the customer downloads the client:

• If the customer uses the generated URL, the session is associated with the site designated by the url_hostname parameter.
• If the customer submits the key code on a public site manually, the session is associated with whichever site they used to submit it.

Request Body - application/json

Routing

Routing the session to a queue is optional. If used, only one of queue_type/queue_id, issue_code_name, or rep_username may be specified. They are mutually exclusive.

Session Options

Customer (optional)

Responses

200 OK - application/json

422 Unprocessable Entity - One or more request parameters are invalid. See 422UnprocessableEntity.

GET /session/{lsid}

Returns attributes for an active support session identified by {lsid}.

Path Parameters

Responses

PATCH /session/{lsid}

Set the external key or other custom attributes for an active support session identified by {lsid}. Each field is identified by its code name as configured in /login > Configuration > Custom Fields.

Path Parameters

Request Body - application/json

A key/value object of custom field code names and their values.

ℹ️

Custom Fields

• Fields must be configured in /login > Configuration > Custom Fields before use
• Maximum of 30 fields per request
• Maximum of 1024 characters per value

Responses

DELETE /session/{lsid}

Terminates an active support session identified by {lsid}.

🚧

This action immediately terminates the session for all participants. It cannot be undone.

Path Parameters

Responses

POST /session/{lsid}/transfer/team/{id}

Transfer an active session from its current rep or team queue to the team queue identified by {id}.

Path Parameters

Responses

POST /session/{lsid}/transfer/user/{id}

Transfer an active session from its current rep or team queue to the Representative identified by {id}.

Path Parameters

Responses

POST /session/{lsid}/add/user/{id}

Add a logged-in Representative to an ongoing support session.

Path Parameters

Responses

DELETE /session/{lsid}/user/{id}

Remove a Representative from an ongoing support session.

Path Parameters

Responses

DELETE /session/{lsid}/customer

Remove the customer from the session identified by {lsid}.

🚧

Removing the customer ends their participation in the session. This action cannot be undone.

Path Parameters

Responses

Users

GET /user

Get a list of all logged-in Representatives, both normal and invited.

Responses

PUT /user/{id}/status

Set the status for a Representative logged into the Representative Console.

ℹ️

Rep statuses and their code names are defined in /login > Configuration > Support Teams > Rep Status.

Path Parameters

Request Body - application/json

Example Request

json
{
  "code_name": "away"
}

Responses

POST /user/{id}/logout

Force a logged-in Representative to log out.

🚧

This immediately terminates the Representative's console session. Any sessions they are participating in may be affected.

Path Parameters

Responses

Chat Bots

POST /chat-message/session/{lsid}

Send a chat message to all members of an existing session. Messages can be sent on behalf of a session participant, such as a customer or representative, or as a system message. This endpoint is commonly used by chat bots to forward end user messages to the representative.

ℹ️

Logging

Messages sent via this API include a special attribute in reports indicating which API Account sent them. Session participants are unaware the message came from an API Account unless they see it sent on their own behalf.

🚧

Real-Time Chat Translations

Messages sent via this API are not affected by the Real-Time Chat Translations feature. All messages are rendered exactly as specified in the request — no translation is performed.

Path Parameters

Request Body - application/json

BBCode Formatting

Impersonation Values

Pattern: ^(customer|rep:\d+|rep_username:\S+)$

Responses

POST /chat-message/team/{id}

Send a chat message to a logged-in member or all members of a support team. Messages can be sent on behalf of a team member or as a system message.

Path Parameters

Request Body - application/json

ℹ️

to_rep and impersonate are interdependent — if to_rep is provided, impersonate must also be provided.

BBCode Formatting

Responses

POST /virtual-customer

Creates a virtual customer in BeyondTrust Remote Support and places them in a new session. This is required for chat bot integrations so that BeyondTrust Remote Support can accurately display and log chat messages forwarded by the bot on behalf of the end user.

ℹ️

Before You Begin

You must call POST /session-key first to obtain a short_key before calling this endpoint.

Request Body - application/json

Optional Fields

Responses

Response status 200 OK

Teams

GET /team

Get a list of all configured support teams.

Responses

GET /team/{id}/issue

Get a list of all issues configured for the team identified by {id}.

Path Parameters

Responses

GET /team/{id}/member

List all Representatives who are members of the team identified by {id}.

Path Parameters

Responses

Failover

POST /failover-role

Set the failover role of an appliance to either primary or backup.

🚧

This is a disruptive operation. Setting data_sync_first to true disconnects all users on the existing primary appliance and blocks all other operations until the swap is complete.

Request Body - application/json

Responses

Schemas

ObjectId

A numeric identifier used throughout the API to reference resources such as Representatives, teams, and queues.

ApplianceId

A GUID that uniquely identifies an appliance.

Username

The username of a Representative.

LSID

A string that uniquely identifies a session.

CodeName

The code name of a resource. Must be unique.

MessageResponse

A general success or failure message returned by many endpoints.

ErrorBagResponse

Key/value pairs returned for input validation errors. Keys are request field names; values are arrays of error messages for that field.

IPv4Address

IPv6Address

Client

Base schema shared by RepConsole, AssetClient, and Gateway.

RepConsole

Extends Client. Represents a Representative logged into the Representative Console.

ℹ️

The private_display_name and public_display_name field descriptions appear transposed in the source. Verify the correct mapping in your environment.

AssetClient

Extends Client. Represents a non-interactive client connection.

Gateway

Extends Client. No additional fields beyond the base Client schema.

HealthBase

Returned by GET /health. Contains appliance health and failover status information.

Parameters

IdParam

A reusable path parameter used across endpoints to identify a specific resource by its numeric ID.

Responses

404NotFound

422UnprocessableEntity

Example Response

json
{
  "message": "Validation failed.",
  "errors": {
    "queue_id": ["The queue_id field must be an integer."],
    "priority": ["The priority field must be between 1 and 3."]
  }
}