Skip to Content
Information
Documentation update The service name is changed from BMC Helix Vulnerability Management to BMC Helix Automation Console. You can find the latest documentation at BMC Helix Automation Console..

Using REST API

This topic provides instructions to access the Swagger host and a list of API endpoints. BMC Helix Automation Consoleprovides REST API endpoints to perform all tasks currently supported by the application. These REST API endpoints are documented in the Swagger UI. 

The API follows the REST architectural style and uses resources, HTTP verbs, and status codes. JavaScript Object Notation (JSON) is used to represent data structures in request and response bodies. All endpoints (except the Login API) use the OAuth 2.0 protocol for authentication.

Accessing the Swagger host for APIs

  1. From a supported browser, enter the following URL to access the API documentation in Swagger:

    https://<customerprefix>-xxx.onbmc.com/automation-console/apidocs

    On the Swagger UI, you can see the APIs supported by the application. 

  2. To obtain a refresh token, based on your user profile, run the following API:

    API calls based on the user

    API for a Cloud Native User: /api/v3/users/login
    API for a Server Automation user: /api/v3/users/tssa/login

  3. Provide the following credentials and click Execute:

    1. Username to log in to Automation Console
    2. Password

    A refresh token is generated, which is valid for 24 hours only.

  4. To obtain an access token to try the APIs, run the /api/v3/auth/tokens API call by using the refresh token.

  5. Copy the token returned by the API call.

    An access token is valid for 15 minutes only.

    Warning

    Note

    If you intend to use a REST API client, such as Postman, you must pass the authorization token in the request header for any REST API call.

  6. On the Login and Administration Service APIs page, click Authorize and provide the token in the authorizations window.

You can now access, try out, and execute any API calls using the Swagger UI. 


Login and Administration Service APIs

Contains APIs that support functions related to session management, Service Level Agreements, security groups, and service accounts.

Login

API call

Description

POST/api/v3/users/tssa/login

Generates a refresh token to log on to TrueSight Server Automation.

post/api/v3/auth/tokens

Generates an access token using the refresh token.

SLAs

API call

Description

get/api/v1/config/slas

Retrieves the service level agreements defined in Automation Console

PUT/api/v1/config/slas

Updates the deadline and warning threshold for SLA severity levels.

Security Groups

API call

Description

post/api/v1/config/securitygroups

Creates a new security group.

get/api/v1/config/securitygroups

Retrieves a list of security groups with details such as the group ID, role, name, description, creation date, and default job path, default depot path, and site details.

get/api/v1/config/securitygroups/{id}

Retrieves details about a security group as per the specified group ID.

PUT/api/v1/config/securitygroups/{id}

Updates a specified security group by using the group ID.

get/api/v1/config/tssa/roles

Retrieves all roles created in TrueSight Server Automation.

get/api/v1/config/tssa/groups/{type}

Gets security group profile by group type.

Connectors

API call

Description

post/api/v1/connectordefinitions/search

Searches for a connector definition.

get/api/v1/connectors/{id}/getConfigurations

Gets configurations for a connector instance.

post/api/v1/connectors/{id}/updateConfigurations

Updates configurations for a connector.

post/api/v1/connectors/search

Searches for a connector.

post/api/v1/connectorservice/connectors/{ConnectorId}/activate

Activates a connector.

post/api/v1/connectorservice/connectors/{ConnectorId}/deactivate

Deactivates a connector.

Violations and Dashboard Service APIs

Contains APIs for the Dashboard, Missing Patches (referred as Violations in the API) and Assets.

Dashboard

API call

Description

post/api/v1/violations/reports/targets/severity/summary

Generates data for the Impacted Assets by Severity widget on the dashboard.

post/api/v1/violations/reports/targets/severity/detail

Generates asset details by severity levels.

post/api/v1/violations/reports/targets/patch-compliance/summary

Generates data for the Patch Compliance widget on the dashboard.

post/api/v1/violations/reports/targets/patch-compliance/detail

Generates patch compliance details such as the number of installed and missing patches on assets according to the policy on the dashboard.

post/api/v1/violations/reports/{type}/summary

Generates data for the Impacted Assets by SLA and Unique Missing Patches by Age widgets on the dashboard.

post/api/v1/violations/reports/trends/weeks

Generates data for the Remediation Trend graph on the dashboard.

post/api/v1/violations/reports/trends/weeks/detail

Generates details such as the missing and remediated patches in the Remediation Trend graph.

post/api/v1/violations/reports/states/average-days/weeks

Gets the average time for a state change in the current week.

post/api/v1/violations/reports/rank/violations

Generates data for the Top 10 Missing Patches widget.

post/api/v1/violations/reports/states/summary

Generates data for the violations based on stage.

post/api/v1/violations/reports/rank/violations/detail

Generates asset details for the Top 10 Missing Patches widget.

post/api/v1/violations/reports/violations/severity/summary

Fetches violations count by severity.

post/api/v1/violations/reports/violations/sla/summary

Fetches violations count by SLA.

post/api/v1/violations/reports/rank/owner

Fetches data for the Top 10 Missing Patches by Owner widget.

post/api/v1/violations/reports/rank/owner/details/{type}

Fetches asset details for the Top 10 Missing Patches by Owner widget.

Missing patches

post/api/v1/violations

Creates violations for a specified asset.

get/api/v1/violations

Gets details of the missing patches.

patch/api/v1/violations

Updates violation fields like risk score, SLA, risk owner, and risk tags based on the given filter criteria.

post/api/v1/violations/upload-tags

Imports tags in a CSV file.

get/api/v1/violations/{id}

Gets details of the missing patches as per the patch ID.

post/api/v2/violations/search/{type}

Gets all vulnerabilities or missing patches.

post/api/v1/violations/reports/patch

Exports the patch report in .csv format.

post/api/v1/violations/search

Searches for missing patches based on the provided filters and updates details for the Unique Missing Patches by Age widget on the dashboard.

get/api/v1/violations/metadata/cveid

Gets all distinct CVE IDs identified against the missing patches.

post/api/v1/violations/riskscore

Gets all distinct risks score.

post/api/v1/violations/owner

Gets all distinct risks owner.

Assets

post/api/v1/violations/reports/targets/{type}

Gets all assets in the endpoint manager.

PUT/api/v1/violations/asset/manual-map/{resourceId}

Maps scanner asset to endpoint targets manually.

PUT/api/v1/violations/asset/unmap

Unmaps scanner asset to endpoint targets.

Vulnerabilities

post/api/v1/violations/reports/vulnerability

Exports the vulnerability report in .csv format.

post/api/v2/violations/search/{type}

Gets all vulnerabilities or missing patches

post/api/v1/violations/search/vulnerabilities

Gets all assets.

post/api/v1/violations/search/vats

Gets all VATs.

PUT/api/v1/violations/manual-map/{id}

Maps remediation content to the given vulnerability manually.

delete/api/v1/violations/unmap/{id}

Removes mapped remediation contents for the vulnerability.

post/api/v1/violations/auto-map

Maps vulnerabilities with remediation content for all the given CVE IDs.

Tagging

post/api/v1/assets/scanned/tags

Imports tags in a CSV file.

Activities

get/api/v1/activities/{id}

Gets an activity by ID.

PUT/api/v1/activities/cancel

Cancels an activity based on filter criteria.

Risk Tags

post/api/v1/violations/tags/search

Searches for unique risk tags.

post/api/v1/violations/tags

Creates a risk tag. (Admin only)

get/api/v1/violations/tags

Gets all risk tags.

PUT/api/v1/violations/tags/{id}

Updates a tag for a given tag ID. (Admin only)

delete/api/v1/violations/tags/{id}

Deletes a tag for a given tag ID. (Admin only)

Summary

get/api/v1/services/summary

Gets top business services.

post/api/v1/violations/reports/targets/sources/summary

Gets summary of sources.

post/api/v1/violations/reports/services/summary/{types}

Gets details of assets or violations.

Business Services

get/api/v1/assets/metadata/business-services

Gets list of unique business services.

Patch Catalog Service APIs

Contains APIs for catalogs in the Automation Console.

Catalog-controller

get/api/v1/catalogs

Gets catalogs imported in the Automation Console.

post/api/v1/catalogs

Imports a new catalog from Server Automation.

get/api/v1/catalogs/tssa

Gets all catalogs available in Server Automation.

get/api/v1/catalogs/tssa/{catalogId}

Gets details for the catalog created in Server Automation based on the catalog ID.

get/api/v1/catalogs/{catalogId}

Gets details for the catalog imported in the Automation Console based on the catalog ID.

PUT/api/v1/catalogs/{catalogId}

Updates schedule for a specified catalog ID.

delete/api/v1/catalogs/{catalogId}

Deletes the specified catalog.

PUT/api/v2/catalogs/{catalogId}/enable

Enables catalog for a specific catalog ID.

PUT/api/v2/catalogs/{catalogId}/disable

Disables catalog for a specific catalog ID.

Patch-controller

PUT/api/v1/catalogs/patch

Retrieves all the patches based on the patch ID's (part of the input payload).

PUT/api/v1/catalogs/{catalogId}/patch/search

Retrieves all patches from Automation Console based on the filter properties.

PUT/api/v1/catalogs/patch/search

Gets patches based on CVE IDs.

PUT/api/v2/catalogs/patch/search

Gets patches based on CVE IDs.

Patch Policy and Operations APIs

Contains the APIs for creating, updating, running, and deleting patch policies. 

Job-run

getautomation-console/api/v1/policies/job/{jobRunId}/summary

Retrieves summary for the specified job run ID.

getautomation-console/api/v1/policies/job/{jobRunId}/target

Retrieves summary for the specified job run ID and target.

getautomation-console/api/v1/policies/job/{jobRunId}/target/{targetId}

Retrieves summary for the specified job run ID and target ID.

getautomation-console/api/v1/policies/policy/{policyId}/jobRuns

Retrieves job runs for the specified policy ID.

getautomation-console/api/v1/policies/{policyId}/runs/{runId}/logs

Retrieves event logs for a specified policy scan run.

Policy

postautomation-console/api/v1/policies

Creates a new patch policy.

getautomation-console/api/v1/policies/bsa/groups/{type}

Gets all static groups created in Server Automation.

postautomation-console/api/v1/policies/bsa/groups/{type}

Creates a static group in Server Automation.

getautomation-console/api/v1/policies/bsa/smart-groups/{type}

Gets all dynamic groups created in Server Automation.

postautomation-console/api/v1/policies/policy/{policyId}/jobRuns

Immediately executes the scan policy associated with specified policy ID.

getautomation-console/api/v1/policies/search

Gets a list of policies created in the Automation Console.

getautomation-console/api/v2/policies

Gets a list of policies created in the Automation Console.

deleteautomation-console/api/v2/policies

Deletes a patch policy.

postautomation-console/api/v1/policies/reports/patch-compliance

Gets patch compliance details.

postautomation-console/api/v1/policies/reports/patch-compliance/detail

Gets patch compliance details as per the policies.

getautomation-console/api/v1/policies/{policy_id}

Gets policy details for the specified ID.

PUTautomation-console/api/v1/policies/{policy_id}

Updates a policy that matches the specified ID.

Vulnerability scan

postautomation-console/api/v1/policies/import-scan

Imports vulnerability scan.

TSSA

getautomation-console/api/v1/policies/tssa/nshscripts

Retrieves all NSH-Scripts defined in Server Automation.

getautomation-console/api/v1/policies/tssa/bl-packages

Retrieves all BLPackages defined in Server Automation.

getautomation-console/api/v1/policies/tssa/nshscripts/{scriptId}

Retrieves NSH Script details from Server Automation.

postautomation-console/api/v1/policies/tssa/depots/search

Search depot object based on given condition.

Operations

postautomation-console/api/v1/policies/operations

Creates Remediation Operation.

postautomation-console/api/v1/policies/operations/search

Retrieves all operations.

postautomation-console/api/v1/policies/operations/prepare-list

Prepares an operation list.

patchautomation-console/api/v1/policies/operations/execute/{operationId}

Executes an operation.

getautomation-console/api/v1/policies/operations/<operationId>/suboperations

Retrieves child operations under a parent draft operation.

deleteautomation-console/api/v1/policies/operations/{operation_id}

Deletes an operation.

ITIL

getautomation-console/api/v1/policies/itil/configurations

Gets ITSM Configuration.

getautomation-console/api/v1/policies/itil/status/{changeId}

Gets change in status from ITSM.

Status count

getautomation-console/api/v1/policies/operations/status/summary

Retrieves operations count by status.

Exceptions Service APIs

Contains APIs for creating, updating, deleting, and searching exceptions in the Automation Console.

POSTautomation-console/api/v1/exceptions

Creates a new exception.

PATCHautomation-console/api/v1/exceptions/{exceptionId}/status

Updates the status of an exception. (Enable or Disable)

DELETEautomation-console/api/v1/exceptions/{exceptionId}

Deletes an exception.

POSTautomation-console/api/v1/exceptions/search

Searches for an exception.


Vulnerability-Asset tagging APIs

Contains the API for importing a tag in the Automation Console.

postautomation-console/vulnerability-asset/importTags

Imports a tag through the CSV file.


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

BMC Helix Vulnerability Management