API Reference

Here you get comprehensive API reference documentation for working with Unity API services and actions. You will find detailed syntax, data samples, and parameter descriptions whether you desire to create new or update existing product licenses, to request order information, or to query endpoint status data.


Get the OpenAPI Definition for Webroot Unity API


The OpenAPI Specification (OAS) is a community-driven open specification within the OpenAPI Initiative. It defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.

Preview Release


The Unity API OpenAPI definition is provided as a preview version and can be used with various tools that are available on the Internet to display and transform the definition to a variety of different formats and code languages.

We are aware of a number of limitations in the current representation of the OpenAPI definition that affect the visualization of APIs in individual tools. API descriptions and texts may not be formatted as nicely as in our online documentation and may contain superfluous line breaks. The sort order of APIs is different to the order in the API Reference online documentation and can vary depending on the tools you use. Also, some additional parameter and value remarks are still missing in the OpenAPI definition. In case of uncertainty of value restrictions and the general use of an API it is recommended to consult the API's specification in the API Reference online documentation on this page.

You can download the full OpenAPI version 3 definition for Unity API services either in YAML format here or in JSON format here.

The definition can be imported and processed by tools that are capable of processing version 3 of the OpenAPI specification. Webroot does not endorse or otherwise promote the use of specific tools, but applications like Postman, ReDoc, SwaggerViewer/-Editor, and much more, have a variety of capabilities to work with OpenAPI definitions. We encourage experimenting with the toolsets of your choice and share your experiences in the Webroot Unity API community forum.


Request Authorization

This page lists groups of API methods that are provided by the Unity API. For most groups of API methods access permissions to a specific scope is required. Users need to provide an access token with applicable access rights as part of these API requests. An access token is acquired during user authentication, where desired permissions to scopes is requested. The token is passed in the Authorization header of API requests in the following format:

Authorization: Bearer {access token}
See Authentication and Service Extensions and Scopes for more information about the authentication process and available scopes.


IMPORTANT - Identifying your Application


When using the Unity API you need to specify a valid user agent string for all requests in the corresponding User-Agent request header. The string needs to be made up of one or more name and version pairs separated by a whitespace character (e.g. "MyCustomApplication/1.2.759 ThirdpartyPlatform/1.0.r3"), according to the HTTP/1.1 standard.

Please be aware that Webroot reserves the right to reject Unity API requests that do not follow above requirement anytime in the future. Identifying your application is important and enables Webroot to provide a more targeted and streamlined API experience.


Authentication

Unity API implements the OAuth 2.0 protocol for user authentication and authorization. In OAuth 2.0 a client requests an access token on behalf of a user. The access token is short-lived and is used for accessing Unity API operations. Once expired, a new access token can be requested through the refresh_token grant request. Look into below actions for further details, or review the Authentication chapter in the Guide section here for more information about the authentication process.

Method API Grant Type Description
POST
password
Uses client as well as user credentials to obtain an access and refresh token.
POST
refresh_token
Uses client credentials and a refresh token to obtain a new access and refresh token.

ECom

Provides a set of API calls for creating and modifying licenses, as well as retrieving license and license order information.

Note:

ECom scopes are not accessible by Console API users and only available to distribution partners, via a separate contract agreement.

Shop

Provides a set of API calls for purchasing and cancelling products.

Required Scope: ECom.Shop

Method API Description
POST
Creates a new shopping cart. Carts act as a container for pending orders.
GET
Gets a cart by its vendorOrderCode. The response will also include the cart’s items and customers, if present.
POST
Creates end customer (shipping) and/or reseller customer records to associate to a given cart. Note that a billing customer is associated when the cart is created and cannot be modified.
GET
Gets the customers associated to a cart.
POST
Creates an order by processing a cart.
GET
Gets information about the order status for a keycode.
DELETE
Creates a request to cancel a particular product.
GET
Gets a license by its keycode.
GET
Gets all child licenses of a parent license, but without billing information which is maintained by the parent license.
POST
Creates a trial license for a given product.
POST
Creates trial modules for a given parent keycode.

SkyStatus

Provides a set of API calls for retrieving agent and license status information from specific endpoints.

Endpoint Status GSM

Provides a set of API calls for retrieving agent status information from specific endpoints. Endpoints can be queried by GSM master key, filtered by machineID and by last modification date.

Required Scope: SkyStatus.GSM

Method API Description
GET
Returns agent status information for all endpoints matching the specified criteria.
GET
Returns DNS protection (DNSP) status information for all endpoints matching the specified criteria.

Endpoint Status Site

Provides a set of API calls for retrieving agent status information from specific endpoints. Endpoints can be queried by site key, filtered by machineID and by last modification date.

Required Scope: SkyStatus.Site

Method API Description
GET
Returns agent status information for all endpoints matching the specified criteria.
GET
Returns DNS protection (DNSP) status information for all endpoints matching the specified criteria.

Usage Reporting

Provides a set of API calls for retrieving usage reports on a specific GSM master key.

Note: Report data is generally available for the last 40 days for which you can query usage reports. It is not guaranteed that later historical data can be accessed through these API methods.

Required Scope: SkyStatus.Reporting

Endpoint usage reports - Endpoint usage information can be requested for a desired day in the past and for different report types. Available report types are:
  • "ActiveEndpoints": Includes all active devices on the effective report date. Note: If hidden data filter is set within the Webroot console, and if some devices have moved to hidden, the “ActiveEndpoints” will show all hidden as well as non-hidden devices in the total.
  • "ActiveEndpointsWithoutHidden": Includes active devices on the effective report date except for those that were hidden. Note: Reflects the Active Devices total seen within the Webroot console under sites, which filters out any hidden devices. Therefore if hidden devices exist, this device total will be less than “ActiveEndpoints” total.
  • "EndpointsSeenInLast30Days": Includes all devices seen in the last 30 days (between the effective report date and 30 days earlier).
Method API Description
GET
Returns a GSM-level summary report of endpoint usage for a GSM master keycode. Besides general information like the console name and type of GSM license the report includes the total number of sites and endpoints.
GET
Returns a site-level summary report of endpoint usage for a GSM master keycode. For each site the report includes information like the site name and license type as well as the total number of endpoints.
GET
Returns a site-level summary report of endpoint usage for a GSM master keycode by a site keycode. The report includes information like the site name and license type as well as the total number of endpoints.
GET
Returns an endpoint-level summary report of endpoint usage for a GSM master keycode. For each endpoint the report includes information like the endpoint's hostname, machine identifier, and its activation state

GET
Returns an endpoint-level summary report of endpoint usage for a GSM master keycode by a site keycode. For each endpoint the report includes information like the endpoint's hostname, machine identifier, and its activation state.

DNS Protection usage reports - DNS Protection (DNSP) usage information can be requested for a desired day in the past and for different report types. Available report types are:
  • "DevicesSeen": Provides DNSP statistics for all devices seen on the effective report date.
  • "DevicesSeenInLast30Days": Provides DNSP statistics for all devices seen in the last 30 days (between the effective report date and 30 days earlier).
Method API Description
GET
Returns a GSM-level summary report of DNSP usage for a GSM master keycode. Besides general information like the console name and type of GSM license the report includes the total number of sites and devices.
GET
Returns a site-level summary report of DNSP usage for a GSM master keycode. For each site the report includes information like the site name and license type as well as the total number of devices.
GET
Returns a site-level summary report of DNSP usage for a GSM master keycode by a site keycode. The report includes information like the site name and license type as well as the total number of devices.
WSAT usage reports - WSAT usage information can be requested for a desired day in the past and for different report types. Available report types are:
  • "UsersSeen": Provides WSAT statistics for all users seen on the effective report date.
  • "UsersSeenInLast30Days": Provides WSAT statistics for all users seen in the last 30 days (between the effective report date and 30 days earlier).
Method API Description
GET
Returns a GSM-level summary report of WSAT usage for a GSM master keycode. Besides general information like the console name and type of GSM license the report includes the total number of sites and users.
GET
Returns a site-level summary report of WSAT usage for a GSM master keycode. For each site the report includes information like the site name and license type as well as the total number of users.
GET
Returns a site-level summary report of WSAT usage for a GSM master keycode by a site keycode. The report includes information like the site name and license type as well as the total number of users.

Console

Provides a set of API calls for console site management.

Console Access

Provides a set of API calls for acquiring access to GSM console environments. For more information about how to request access and about related prerequisites, please see the description of the individual API endpoints.

Note:

The Console.Access scope is not accessible by Console API users and only available to distribution partners, via a separate contract agreement.

Required Scope: Console.Access

Method API Description
POST
Initiates the process for requesting admin access to a GSM console.

IMPORTANT: Before initiating an access request it is the responsibility of the requestor to inform the owner of the target GSM console that a designated person (whose e-mail address has to be specified in the request) will receive a confirmation message from Webroot. The e-mail message will include further information about the steps how to approve the request which need to be carried out in order to advance the access request process. The status of an initiated access request can be queried by using the addadminstatus API method.

GET
Retrieves the status of a GSM add admin access request.

Console GSM

Provides a set of API calls for creating endpoint protection sites and listing policies and admins for a given GSM keycode, as well as for managing endpoint protection sites given a specified GSM keycode and a site identifier.

Required Scope: Console.GSM

Method API Description
GET
Gets information about a given GSM console.
GET
Looks up information about a specific GSM site which is associated with a given site keycode. You can use this method to query site details using a site keycode and to retrieve the site's identifier for follow-up calls.
Single Sign-On - Provides API calls for obtaining short-lived Single Sign-On (SSO) links for the authenticated user in order to access the GSM console website or Endpoint Protection Console website in the web browser.

IMPORTANT: Due to 2-factor authentication requirements for the Webroot Console, as of Dec 2019 the Unity API SSO feature will be temporarily changed, where users will be directed to the usual Webroot Console Username/Password screen to re-authenticate. We will issue further notices when the SSO feature is redesigned.

Method API Description
GET
Gets a URL to the Webroot web console that, when used in a browser, automatically logs the authenticated user in to the corresponding GSM Console.
GET
Gets a URL to the Webroot web console that, when used in a browser, automatically logs the authenticated user in to the corresponding Endpoint Protection Console.
Site management - Provides API calls for listing, creating, deactivating, suspending, and resuming sites
Method API Description
GET
Gets the list of sites associated with a given GSM console.
GET
Gets information about a GSM site.
POST
Creates a new site under a given GSM console.
PUT
Edits information for a site under a given GSM console.
POST
Deactivates a site under a given GSM console.
POST
Suspends a site under a given GSM console.
POST
Resumes a site under a given GSM console.
POST
Converts a trial site under a given GSM console into a full license.
User management - Provides API calls for listing users, adding users to a site, and modifying access permissions
Method API Description
GET
Gets the list of admins on a given GSM console.
GET
Gets information about a GSM admin.
POST
Adds a new user as an admin to a GSM console with the desired access level.
PUT
Edits certain user account attributes of a GSM admin.
DELETE
Removes a GSM admin from a GSM console and all its sites.
GET
Gets the list of admins on a given GSM site.
GET
Gets information about a site admin.
POST
Adds a new user as a site admin to a site with the desired access level.
PUT
Edits certain user account attributes of a site admin.
DELETE
Removes an admin from a site.
PUT
Adds admins to a site or modifies access permissions of site admins.
Policy management - Provides API calls for listing global and site policies
Method API Description
GET
Gets the list of global policies on a given GSM console.
GET
Gets information about a GSM policy.
GET
Gets the list of policies on a given GSM site.
GET
Gets information about a site policy.
Endpoint management - Provides API calls for listing endpoints, moving endpoints to a new group, applying a new policy to endpoints, and re- or deactivating endpoints
Method API Description
GET
Gets the list of endpoints on a given GSM site.
GET
Gets information about an endpoint.
GET
Gets the list of endpoints on a given group.
PUT
Moves endpoints to a different group.
PUT
Applies a new policy to the specified endpoints.
PUT
Applies a new policy to a group of endpoints.
POST
Reactivates a list of endpoints, or all endpoints on a site.
POST
Deactivates a list of endpoints, or all endpoints on a site.
POST
Deactivates all endpoints in a group.
Endpoint group management - Provides API calls for listing, creating, editing, and deleting groups
Method API Description
GET
Gets the list of groups on a given GSM site.
GET
Gets information about a group.
POST
Creates a group under a given GSM site.
PUT
Edits a group under a given GSM site.
DELETE
Deletes a group under a given GSM site.
Web Threat Shield Blocked URLs - Provides information about actions taken by Web Threat Shield on web sites and URLs accessed on endpoints
Method API Description
GET
Retrieves per-day summary counts of the number of recorded URL actions on endpoints in the given site.
GET
Retrieves a list of recorded URL actions on endpoints in the given site.
DNS Protection policy mapping - Provides API calls for listing DNS Protection categories and DNS Protection policies, and for listing, creating, editing, and deleting DNS Protection policy mappings
Method API Description
GET
Returns a list of available DNS Protection categories and their respective identifier.
GET
Returns a list of available DNS Protection policies and their respective identifier for a GSM parent keycode.
GET
Returns detailed information for one specified DNS Protection policy.
GET
Returns the defined mappings of DNS Protection Policies for a GSM parent keycode, filtered by the given site.
GET
Returns detailed information for a specified mapping of a DNS Protection policy.
POST
Creates a mapping for a DNS Protection policy for a GSM site.
PUT
Edits a specified mapping of a DNS Protection policy.
DELETE
Deletes a specified mapping of a DNS Protection policy.
DNS Protection traffic information - Provides DNS request summary information for all sites of a GSM console or for a single site, as well as site-level information about blocked DNS requests.
Method API Description
GET
Returns a list of available DNS Protection block reasons and their respective identifiers.
GET
Returns information about DNS requests that were blocked by the DNS Protection service.
GET
Returns information about DNS requests that were seen by the DNS Protection service for one or more specified categories.
GET
Returns a traffic summary (e.g. the number of total DNS requests, blocked DNS requests, and risky DNS requests) for each site under a given GSM.
GET
Returns a traffic summary (e.g. the number of total DNS requests, blocked DNS requests, and risky DNS requests) for a specific site under a given GSM.
WSAT reporting - Provides Webroot Security Awareness Training (WSAT) basic reports for training and phishing campaigns.
Method API Description
GET
Returns information on activity seen for Webroot Security Awareness Training (WSAT) phishing campaigns associated to a given site.
GET
Returns information on activity seen for Webroot Security Awareness Training (WSAT) training campaigns associated to a given site.

Notifications

Provides a set of API calls for Notifications.

Subscriptions

Provides a set of API calls for subscribing to event notifications and managing subscriptions.

For more information about how to subscribe to certain events and how to retrieve event notifications please refer to the Event Notifications Guide section here.

Required Scope: Notifications.Subscriptions

Method API Description
GET
Gets a list of available event types that can be subscribed to, with information on required scope permissions and subscription domains for each event type.
GET
Gets information about the active subscriptions associated with the authenticated caller.
GET
Gets information about a specific subscription.
GET
Retrieves the latest notifications for a specific subscription.
POST
Generates a position token which can be used to start fetching notifications.
POST
Creates a new subscription.
PUT
Edits the information of a specific subscription.
DELETE
Unsubscribes from a specific subscription.
POST
Suspends calls to the subscription's webhook DeliveryUrl for informing about new notifications.
POST
Resumes calls to the subscription's webhook DeliveryUrl for informing about new notifications.

HealthCheck

Provides a set of API calls for verifying the general health of a Unity API service instance as well as for retrieving service version information.

Health Check

Provides a set of API calls for determining the general availability of the service and for retrieving version information.

Method API Description
GET
Empty action that can be used to ping for the availability of the service.
GET
Retrieves version information of the running service environment.