Documentation update To provide a better user experience, we have now created a separate documentation space for Helix Vulnerability Management. Users of Helix Vulnerability Management (includes BMC Helix Automation Console) can find the latest documentation at BMC Helix Vulnerability Management.

Using REST API

This topic provides instructions to access the Swagger host and a list of API endpoints. 

BMC Helix Automation Console (SaaS) or TrueSight Automation Console (on-premises) provides 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:

    TrueSight Automation Console: https://<FullyQualifiedDomainHostName>:<port>/apidocs/

    BMC Helix Automation Console: 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 (for SaaS only): /api/v3/users/login
    API for a Server Automation user (for SaaS and on-premises): /api/v3/users/tssa/login

  3. Provide the following credentials and click Execute:

    1. Username to log in to Automation Console
    2. Password, encoded in the Base64 format

    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.

    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 and Administrative Services APIs

API call (on-premises)

API call (SaaS)

Description

Login API

NA

post cloudops/api/v3/users/login

Generates refresh token for a Cloud Native User.

post/api/v3/users/tssa/login

postcloudops/api/v3/users/tssa/login

Generates refresh token to login TrueSight Server Automation.

post/api/v3/auth/tokens

postcloudops/api/v3/auth/tokens

Generates access token using the refresh token.

SLAs API

get/api/v1/config/slas

getautomation-console/api/v1/config/slas

Retrieves the service level agreements defined in the Automation Console.

PUT/api/v1/config/slas

PUTautomation-console/api/v1/config/slas

Updates the deadline and warning threshold for SLA severity levels.

Security Groups API

post/api/v1/config/securitygroups

postautomation-console/api/v1/config/securitygroups

Creates a new security group.

get/api/v1/config/securitygroups

getautomation-console/api/v1/config/securitygroups

Gets 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}

getautomation-console/api/v1/config/securitygroups/{id}

Gets details of a security group as per the specified group ID.

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

PUTautomation-console/api/v1/config/securitygroups/{id}

Updates a specified security group by using the group ID.

get/api/v1/config/tssa/roles

getautomation-console/api/v1/config/tssa/roles

Gets all roles created in TrueSight Server Automation.

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

getautomation-console/api/v1/config/tssa/groups/{type}

Gets security group profile by group type.

Connectors API

post/api/v1/connectordefinitions/search

postautomation-console/api/v1/connectordefinitions/search

Searches for a connector definition.

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

getautomation-console/api/v1/connectors/{id}/getConfigurations

Gets configurations for a connector instance.

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

postautomation-console/api/v1/connectors/{id}/updateConfigurations

Updates configurations for a connector.

post/api/v1/connectors/search

postautomation-console/api/v1/connectors/search

Searches for a connector.

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

postautomation-console/api/v1/connectorservice/connectors/{ConnectorId}/activate

Activates a connector.

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

postautomation-console/api/v1/connectorservice/connectors/{ConnectorId}/deactivate

Deactivates a connector.

BMC Remedy Single Sign-On API



POST/api/v1/config/rsso

NA

Configures Remedy SSO for Automation Console.

Only administrators can use this API call.

Violations and Dashboard Service APIs

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

Click here to expand...

API call (on-premises)

API call (SaaS)

Description

Dashboard API

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

postautomation-console/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

postautomation-console/api/v1/violations/reports/targets/severity/detail

Generates asset details by severity levels.

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

postautomation-console/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

postautomation-console/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

postautomation-console/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/sla/detail

postautomation-console/api/v1/violations/reports/sla/detail

Generates details for the assets and missing patches based on their SLA levels.

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

postautomation-console/api/v1/violations/reports/trends/weeks

Generates data for the Remediation Trend graph on the dashboard.

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

postautomation-console/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

postautomation-console/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

postautomation-console/api/v1/violations/reports/rank/violations

Generates data for the Top 10 Missing Patches widget.

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

postautomation-console/api/v1/violations/reports/states/summary

Generates data for the violations based on stage.

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

postautomation-console/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

postautomation-console/api/v1/violations/reports/violations/severity/summary

Fetches violations count by severity.

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

postautomation-console/api/v1/violations/reports/violations/sla/summary

Fetches violations count by SLA.

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

postautomation-console/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}

postautomation-console/api/v1/violations/reports/rank/owner/details/{type}

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

Missing Patches API

post/api/v1/violations

postautomation-console/api/v1/violations

Creates violations for a specified asset.

get/api/v1/violations

getautomation-console/api/v1/violations

Gets details of the missing patches.

patch/api/v1/violations

patchautomation-console/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

postautomation-console/api/v1/violations/upload-tags

Imports tags in a CSV file.

get/api/v1/violations/{id}

getautomation-console/api/v1/violations/{id}

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

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

postautomation-console/api/v2/violations/search/{type}

Gets all vulnerabilities or missing patches.

post/api/v1/violations/reports/patch

postautomation-console/api/v1/violations/reports/patch

Exports the patch report in .csv format.

post/api/v1/violations/search

postautomation-console/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

getautomation-console/api/v1/violations/metadata/cveid

Gets all distinct CVE IDs identified against the missing patches.

post/api/v1/violations/riskscore

postautomation-console/api/v1/violations/riskscore

Gets all distinct risks score.

post/api/v1/violations/owner

postautomation-console/api/v1/violations/owner

Gets all distinct risks owner.

Assets API

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

postautomation-console/api/v1/violations/reports/targets/{type}

Gets all assets in the endpoint manager.

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

PUTautomation-console/api/v1/violations/asset/manual-map/{resourceId}

Maps scanner asset to endpoint targets manually.

PUT/api/v1/violations/asset/unmap

PUTautomation-console/api/v1/violations/asset/unmap

Unmaps scanner asset to endpoint targets.

Vulnerabilities API

post/api/v1/violations/reports/vulnerability

postautomation-console/api/v1/violations/reports/vulnerability

Exports the vulnerability report in .csv format.

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

postautomation-console/api/v2/violations/search/{type}

Gets all vulnerabilities or missing patches

post/api/v1/violations/search/vulnerabilities

postautomation-console/api/v1/violations/search/vulnerabilities

Gets all assets.

post/api/v1/violations/search/vats

postautomation-console/api/v1/violations/search/vats

Gets all VATs.

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

PUTautomation-console/api/v1/violations/manual-map/{id}

Maps remediation content to the given vulnerability manually.

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

deleteautomation-console/api/v1/violations/unmap/{id}

Removes mapped remediation contents for the vulnerability.

post/api/v1/violations/auto-map

postautomation-console/api/v1/violations/auto-map

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

Tagging API

post/api/v1/assets/scanned/tags

postautomation-console/api/v1/assets/scanned/tags

Imports tags in a CSV file.

Activities API

get/api/v1/activities/{id}

getautomation-console/api/v1/activities/{id}

Gets an activity by ID.

PUT/api/v1/activities/cancel

PUTautomation-console/api/v1/activities/cancel

Cancels an activity based on filter criteria.

Risk Tags API

post/api/v1/violations/tags/search

postautomation-console/api/v1/violations/tags/search

Searches for unique risk tags.

post/api/v1/violations/tags

postautomation-console/api/v1/violations/tags

Creates a risk tag. (Admin only)

get/api/v1/violations/tags

getautomation-console/api/v1/violations/tags

Gets all risk tags.

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

PUTautomation-console/api/v1/violations/tags/{id}

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

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

deleteautomation-console/api/v1/violations/tags/{id}

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

Summary API

get/api/v1/services/summary

getautomation-console/api/v1/services/summary

Gets top business services.

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

postautomation-console/api/v1/violations/reports/targets/sources/summary

Gets summary of sources.

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

postautomation-console/api/v1/violations/reports/services/summary/{types}

Gets details of assets or violations.

Business Service API

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

getautomation-console/api/v1/assets/metadata/business-services

Gets list of unique business services.

Patch Catalog Service APIs

Contains APIs for catalogs in the Automation Console. 

Click here to expand...

API call (on-premises)

API call (SaaS)

Description

Catalog-controller API

get/api/v1/catalogs

getautomation-console/api/v1/catalogs

Gets catalogs imported in the Automation Console.

post/api/v1/catalogs

postautomation-console/api/v1/catalogs

Imports a new catalog from Server Automation.

get/api/v1/catalogs/tssa

getautomation-console/api/v1/catalogs/tssa

Gets all catalogs available in Server Automation.

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

getautomation-console/api/v1/catalogs/tssa/{catalogId}

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

get/api/v1/catalogs/{catalogId}

getautomation-console/api/v1/catalogs/{catalogId}

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

PUT/api/v1/catalogs/{catalogId}

PUTautomation-console/api/v1/catalogs/{catalogId}

Updates schedule for a specified catalog ID.

delete/api/v1/catalogs/{catalogId}

deleteautomation-console/api/v1/catalogs/{catalogId}

Deletes the specified catalog.

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

PUTautomation-console/api/v2/catalogs/{catalogId}/enable

Enables catalog for a specific catalog ID.

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

PUTautomation-console/api/v2/catalogs/{catalogId}/disable

Disables catalog for a specific catalog ID.

Patch-controller API

PUT/api/v1/catalogs/patch

PUTautomation-console/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

PUTautomation-console/api/v1/catalogs/{catalogId}/patch/search

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

PUT/api/v1/catalogs/patch/search

PUTautomation-console/api/v1/catalogs/patch/search

Gets patches based on CVE IDs.

PUT/api/v2/catalogs/patch/search

PUTautomation-console/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. 

Patch Policy and Operations API

API call (on-premises)

API call (SaaS)

Description

Job-run API



get/api/v1/policies/job/{jobRunId}/summary

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

Retrieves summary for the specified job run ID.

get/api/v1/policies/job/{jobRunId}/target

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

Retrieves summary for the specified job run ID and target.

get/api/v1/policies/job/{jobRunId}/target/{targetId}

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

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

get/api/v1/policies/policy/{policyId}/jobRuns

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

Retrieves job runs for the specified policy ID.

get/api/v1/policies/{policyId}/runs/{runId}/logs

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

Retrieves event logs for a specified policy scan run.

Policy API


Description

post/api/v1/policies

postautomation-console/api/v1/policies

Creates a new patch policy.

get/api/v1/policies/bsa/groups/{type}

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

Gets all static groups created in Server Automation.

post/api/v1/policies/bsa/groups/{type}

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

Creates a static group in Server Automation.

get/api/v1/policies/bsa/smart-groups/{type}

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

Gets all dynamic groups created in Server Automation.

post/api/v1/policies/policy/{policyId}/jobRuns

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

Immediately executes the scan policy associated with specified policy ID.

get/api/v1/policies/search

getautomation-console/api/v1/policies/search

Gets a list of policies created in the Automation Console.

get/api/v2/policies

getautomation-console/api/v2/policies

Gets a list of policies created in the Automation Console.

delete/api/v2/policies

deleteautomation-console/api/v2/policies

Deletes a patch policy.

post/api/v1/policies/reports/patch-compliance

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

Gets patch compliance details.

post/api/v1/policies/reports/patch-compliance/detail

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

Gets patch compliance details as per the policies.

get/api/v1/policies/{policy_id}

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

Gets policy details for the specified ID.

PUT/api/v1/policies/{policy_id}

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

Updates a policy that matches the specified ID.

Vulnerability scan API

post/api/v1/policies/import-scan

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

Imports vulnerability scan.

TSSA API

get/api/v1/policies/tssa/nshscripts

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

Retrieves all NSH-Scripts defined in Server Automation.

get/api/v1/policies/tssa/bl-packages

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

Retrieves all BLPackages defined in Server Automation.

get/api/v1/policies/tssa/nshscripts/{scriptId}

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

Retrieves NSH Script details from Server Automation.

post/api/v1/policies/tssa/depots/search

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

Search depot object based on given condition.

Operations API

post/api/v1/policies/operations

postautomation-console/api/v1/policies/operations

Creates Remediation Operation.

post/api/v1/policies/operations/search

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

Retrieves all operations.

post/api/v1/policies/operations/prepare-list

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

Prepares an operation list.

patch/api/v1/policies/operations/execute/{operationId}

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

Executes an operation.

get/api/v1/policies/operations/<operationId>/suboperations

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

Retrieves child operations under a parent draft operation.

delete/api/v1/policies/operations/{operation_id}

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

Deletes an operation.

ITIL API

get/api/v1/policies/itil/configurations

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

Gets ITSM Configuration.

get/api/v1/policies/itil/status/{changeId}

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

Gets change in status from ITSM.

Status count

get/api/v1/policies/operations/status/summary

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.

Exceptions Service APIs


Vulnerability-Asset tagging APIs

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

API call (on-premises)

API call (SaaS)

Description

post/vulnerability-asset/importTags

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*