logo
API docs by Redocly

Honeycomb API (2.0.0)

Download OpenAPI specification:Download

Terms of Service

The Scoutbees Honeycomb RESTful API lets you programmatically interact with your Scoutbees organization. Most of the features in the web application are also available through the API.

You can use the API to retrieve data such as Scout information, test results, and alerts. You can also create and configure Scouts. Whatever your use-case might be, the API lets you integrate automatic resource testing into your own application.

The API runs adjacent to the web application. Scouts created through the API can be viewed in the web application, and you can use the API to view Scouts created in the web application.

For an overview on how to use the API, visit Using the Scoutbees API.

Scouts

Scouts are the proactive tests that you configure to monitor the availability and health of various resources. There are different types of Scouts, depending on the type of resource you want to test. Within each type, there are sub-types which determine which test is performed and the available test configuration options.

Scouts are initiated from Hives, which are either hosted in the cloud (Cloud Hives), or installed on-premises (Custom Hives).

List all Scouts

Returns a list of your Scouts.

Authorizations:
ApiKeyAuth
query Parameters
hiveId
Array of integers <int32> [ items <int32 > >= 1 ]
Example: hiveId=1,2

Only return Scouts running from the Custom Hives specified by these hive IDs.

cloudHive
Array of integers <int32> [ items <int32 > >= 1 ]
Example: cloudHive=1,2

Only return Scouts running from the Cloud Hives specified by these hive IDs.

type
string
Enum: "euc" "network"

Filter the list based on the Scout type.

subType
string
Enum: "vmware_horizon" "vmware_w1" "vmware_secsrv" "citrix_gateway" "citrix_cloud" "citrix_storefront" "net_ping" "net_dns" "net_traceroute" "net_http"

Filter the list based on the Scout sub-type.

interval
integer

Filter the list based on the interval (in minutes) of how often a Scout runs.

disabled
boolean
Default: 0
Enum: 0 1

Use this parameter to only return disabled Scouts. By default, only enabled Scouts are returned.

username
string

Only return Scouts that use this username to access the resource. This only applies to EUC Scouts.

page
integer

The page of Scouts to be returned. Each page contains up to 100 Scouts. If your request returns more than 100 Scouts, then the response is paginated.

Responses

Request samples 

curl -X GET 'https://api.scoutbees.io/honeycomb/v2/scouts?cloudHive=2&type=euc&username=TestBot1' \
-H 'x-scoutbees-key: API-key-here'

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "total_pages": 1,
  • "success": true,
  • "total": 2,
  • "data": [
    ]
}

Create a Scout

Create a Scout to test EUC or network resources. Creating a Scout uses credits on your account. If you disable or delete the Scout, then the credits are returned to your account. See License Information for more details.

Authorizations:
ApiKeyAuth
Request Body schema: application/json

Select the Scout's type, sub-type, and hive type (if applicable), to see the relevant parameters.

One of
One of
One of
cloudHive
required
integer <int32>

ID of the Cloud Hive from which the Scout will run.

subType
required
string
Value: "citrix_gateway"

The Scout's sub-type. This indicates the EUC platform that the Scout accesses.

(TOTP | OTP (object or null)) or (OTP phone call (object or null)) or (OTP SMS (object or null)) (OTP)

One-time password (OTP) information for the Scout. MFA is supported for all EUC Scout platforms except Citrix Storefront.

Visit Multi-Factor Authentication for more details on how to configure MFA.

address
required
string <url>

The address of the gateway that the Scout accesses.

scoutName
required
string

The Scout's name.

interval
required
integer
Enum: 5 10 15 30 60

The interval (in minutes) of how often the Scout runs.

resource
required
string

The published resource that the Scout accesses and tests.

username
required
string

The username used to access the gateway.

password
required
string

The password used to access the gateway.

object (EucExtras)

Additional options.

Array of objects

Key-value pairs that are associated with the Scout. These can be used to organize your Scouts.

Responses

Request samples

Content type
application/json
Example
{
  • "address": "string",
  • "scoutName": "string",
  • "interval": 5,
  • "resource": "string",
  • "username": "string",
  • "password": "string",
  • "options": {
    },
  • "cloudHive": 0,
  • "subType": "citrix_gateway",
  • "otp": {
    },
  • "labels": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Scout has been created.",
  • "scoutDetails": 1000,
  • "availableCredits": 30000,
  • "totalCredits": 75000
}

Get Scout info

Returns the details of a specific Scout, and a summary of it's test results. By default, the summary uses test results from the last 24 hours.

Authorizations:
ApiKeyAuth
path Parameters
scoutId
required
integer

ID of the Scout.

query Parameters
start
string <date-time>
Example: start=2021-01-01 13:21:55

Start date and time of test results used for the summary.

end
string <date-time>
Example: end=2021-02-01 10:24:55

End date and time of the test results used for the summary.

Responses

Request samples 

curl -X GET 'https://api.scoutbees.io/honeycomb/v2/scouts/10354' \
-H 'x-scoutbees-key: API-key-here'

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "data": {
    },
  • "summary": {
    }
}

Edit Scout

Edits an existing Scout. Any parameters passed in this call will be updated to the new values. Unused parameters will not be changed.

Authorizations:
ApiKeyAuth
path Parameters
scoutId
required
integer

ID of the Scout.

Request Body schema: application/json

Edit scout

One of
One of
cloudHive
integer <int32>

ID of the Cloud Hive from which the Scout will run.

address
string <url>

The address of the gateway that the Scout accesses.

scoutName
string

The Scout's name.

interval
integer
Enum: 5 10 15 30 60

The interval (in minutes) of how often the Scout runs.

resource
string

The published resource that the Scout accesses and tests.

username
string

The username used to access the gateway.

password
string

The password used to access the gateway.

object (EucExtras)

Additional options.

domain
string

The domain used to access the gateway. This is only available for the following sub-types: citrix_cloud, vmware_horizon, vmware_secsrv.

Array of objects

Key-value pairs that are associated with the Scout. These can be used to organize your Scouts.

When you edit labels, all existing labels are deleted and replaced with the ones you provide.

Responses

Request samples

Content type
application/json
Example
{
  • "address": "string",
  • "scoutName": "string",
  • "interval": 5,
  • "resource": "string",
  • "username": "string",
  • "password": "string",
  • "options": {
    },
  • "domain": "string",
  • "cloudHive": 0,
  • "labels": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Delete Scout

Deletes a Scout. This cannot be undone. Historical test result data for the Scout will still be available.

The credits used to create the Scout will be returned to your account.

Authorizations:
ApiKeyAuth
path Parameters
scoutId
required
integer

ID of the Scout.

Responses

Request samples 

curl -X DELETE 'https://api.scoutbees.io/honeycomb/v2/scouts/10354' \
-H 'x-scoutbees-key: API-key-here'

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Enable/disable Scout

Enables or disables an existing Scout. A Scout only performs tests while it is enabled.

Enabling a Scout uses credits on your account. Disabling a Scout returns the credits.

Authorizations:
ApiKeyAuth
path Parameters
scoutId
required
integer

ID of the Scout.

Request Body schema: application/json
disabled
required
boolean

Set to true to disable the Scout. Set to false to enable the Scout.

Responses

Request samples

Content type
application/json
{
  • "disabled": true
}

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Tests

The output of the scout tests

List tests

Returns a list of test, containing the the details and results of each tests. The tests are grouped by their Scouts, with the earliest tests appearing first in each group.

By default, all tests from all Scouts in the last 24 hours are returned.

Authorizations:
ApiKeyAuth
query Parameters
start
string <date-time>
Example: start=2021-01-01 13:21:55

Only return tests initiated after this time.

end
string <date-time>
Example: end=2021-02-01 10:24:55

Only return tests initiated before this time. You must specify a start time to use this parameter.

scoutId
Array of integers
Example: scoutId=1,2

Only return tests from the Scouts specified by these Scout IDs.

status
string
Enum: "success" "failure"

Filter the list based on the status of the tests.

page
integer

The page of tests returned. Each page contains up to 100 tests. If your request returns more than 100 tests, then the response is paginated.

Responses

Request samples 

curl -X GET 'https://api.scoutbees.io/honeycomb/v2/tests?scoutId=24,31&status=failure' \
-H 'x-scoutbees-key: API-key-here'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "current_page": 0,
  • "total_pages": 0,
  • "total_per_page": 100,
  • "success": true,
  • "total": 0
}

Hives

Hives are the locations from which Scouts (tests) are initiated.

Custom Hives allow you to test internal resources from within your network. They must be installed on a computer with access to your network.

Cloud hives allow you to test publicly available resources from locations throughout the world. They are hosted and managed by Scoutbees, and require no configuration.

List all Custom Hives

Returns a list of the Custom Hives in your organization.

Authorizations:
ApiKeyAuth

Responses

Request samples 

curl -X GET 'https://api.scoutbees.io/honeycomb/v2/hives' \
-H 'x-scoutbees-key: API-key-here'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "success": true
}

List all Cloud Hives

Returns a list of Cloud Hives.

Authorizations:
ApiKeyAuth

Responses

Request samples 

curl -X GET 'https://api.scoutbees.io/honeycomb/v2/cloud_hives' \
-H 'x-scoutbees-key: API-key-here'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "success": true
}

Alerts

Scouts can be configured to trigger an alert when certain conditions are met. You can use endpoints to get a list of alerts from all Scouts, a list of Scouts that have triggered an alert, and a list of alerts from a specific Scout.

List all alerts

Returns alerts generated within the specified time frame for all Scouts. The default time frame is the last 24 hours.

Authorizations:
ApiKeyAuth
query Parameters
start
string <date-time>
Example: start=2021-01-01 13:21:55

Start date and time of the search. The start date can be up to 1 year in the past. The total search duration from the start time to the end time can be a maximum of 24 hours.

end
string <date-time>
Example: end=2021-02-01 10:24:55

End date and time of the search.

page
integer

The page of alerts to return. Each page contains up to 100 alerts. If your request returns more than 100 alerts, then the response is paginated.

Responses

Request samples 

curl -X GET 'https://api.scoutbees.io/honeycomb/v2/alerts?start=2023-09-25 02:29:47&end=2023-09-26 02:29:47' \
-H 'x-scoutbees-key: API-key-here'

Response samples

Content type
application/json
Example
{
  • "current_page": 1,
  • "data": {
    },
  • "success": true,
  • "total": 4,
  • "total_pages": 1,
  • "total_per_page": 100
}

List Scout IDs with alerts

Returns a list of Scout IDs that have triggered an alert within the specified time frame. The default time frame is the last 24 hours.

Authorizations:
ApiKeyAuth
query Parameters
start
string <date-time>
Example: start=2021-01-01 13:21:55

Start date and time of the search.

end
string <date-time>
Example: end=2021-02-01 10:24:55

End date and time of the search.

Responses

Request samples 

curl -X GET 'https://api.scoutbees.io/honeycomb/v2/alerts/scouts?start=2023-09-26 08:00:00&end=2023-09-27 01:30:00' \
-H 'x-scoutbees-key: API-key-here'

Response samples

Content type
application/json
{
  • "success": true,
  • "scoutId": [
    ]
}

List alerts for a Scout

Returns alerts generated within the specified time frame for a Scout. The default time frame is the last 24 hours.

Authorizations:
ApiKeyAuth
path Parameters
ScoutID
required
string

ID of the Scout.

query Parameters
start
string <date-time>
Example: start=2023-09-26 08:00:00

Start date and time of the search. The start date can be up to 1 year in the past. The total search duration from the start time to the end time can be a maximum of 24 hours.

end
string <date-time>
Example: end=2023-09-27 01:30:00

End date and time of the search.

page
integer

The page of alerts to return. Each page contains up to 100 alerts. If your request returns more than 100 alerts, then the response is paginated.

Responses

Request samples 

curl -X GET 'https://api.scoutbees.io/honeycomb/v2/alerts/7852?start=2023-09-26 08:00:00&end=2023-09-27 01:30:00' \
-H 'x-scoutbees-key: API-key-here'

Response samples

Content type
application/json
Example
{
  • "current_page": 1,
  • "data": {
    },
  • "success": true,
  • "total": 4,
  • "total_pages": 1,
  • "total_per_page": 100
}

MFAs

Multi-factor authentication (MFA) is supported for gateway access on all EUC platforms except Citrix Storefront. Use this resource to retrieve the sets of usernames and phone numbers that have been configured for phone or SMS verification.You must contact Scoutbees Support to associate a username with a phone number for MFA.

Visit Multi-Factor Authentication for more details on how to configure MFA.

List all MFA users

Returns a list of usernames for EUC gateway access that are associated with a phone number for MFA.

Authorizations:
ApiKeyAuth

Responses

Request samples 

curl -X GET 'https://api.scoutbees.io/honeycomb/v2/mfas' \
-H 'x-scoutbees-key: API-key-here'

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}