Using REST APIs
TrueSight 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 API documentation
From a supported browser, enter the following URL to access the API documentation in Swagger:
TrueSight Automation Console: https://<FullyQualifiedDomainHostName>:<port>/apidocs/On the Swagger UI, you can see the APIs supported by the application.
To obtain a refresh token, based on your user profile, run the following API:
API calls based on the user
API for a Server Automation user: /api/v3/users/tssa/login- Provide the following credentials and click Execute:
- Username to log in to Automation Console
- Password
A refresh token is generated, which is valid for 24 hours only.
- To obtain an access token to try the APIs, run the /api/v3/auth/tokens API call by using the refresh token.
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.
- 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 BMC Remedy Single Sign-On.
| API call | Description |
|---|---|
| Login API | |
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. |
| SLA API | |
GET/api/v1/config/slas | Retrieves the service level agreements defined in the Automation Console. |
PUT/api/v1/config/slas | Updates the deadline and warning threshold for SLA severity levels. |
| Security Groups API | |
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} | Retrieves security group profile by group type. |
| BMC Remedy Single Sign-On API | |
POST/api/v1/config/rsso | Configures BMC Remedy Single Sign-On. Note You must have administrator permissions to use this API call. |
| Support API | |
DELETE/api/v1/config/securitygroups/{id} | Deletes the specified security group. Note BMC recommends that you do not use this API call. This API call is only made available to the BMC Customer Support team for debugging or recovering from problems. |
Connectors Service APIs
Contains API calls for working with all the connectors in Automation Console.
| API call | Description |
|---|---|
| Connectors API | |
POST/api/v1/connectordefinitions/search | Searches for a connector definition, which includes information about the connector name, type, and so on. |
GET/api/v1/connectors/{id}/getConfigurations | Retrieves configurations for a connector instance. |
POST/api/v1/connectors/{id}/updateConfigurations | Updates a connector configuration. |
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. |
Exceptions Service APIs
Contains APIs for creating, updating, deleting, and searching exceptions in the Automation Console.
API call | Description |
|---|---|
POST/api/v1/exceptions | Creates one or more exceptions. |
PATCH/api/v1/exceptions/{exceptionId}/status | Updates the status of an exception. (Enable or Disable) |
DELETE/api/v1/exceptions/{exceptionId} | Deletes an exception. |
PATCH/api/v1/exceptions/{exceptionId} | Updates the end date of an exception. |
POST/api/v1/exceptions/search | Searches for an exception. |
| Support API | |
POST/api/v1/exceptions/sync | Exceptions that are in an enabled or active state move to an Active or Expired state based on their scheduled date, which runs at 12:00 AM UTC. If the scheduler does not work as expected, this API call forcefully executes active or enabled exceptions. Note BMC recommends that you do not use this API call. This API call is only made available to the BMC Customer Support team for debugging or recovering from problems. |
Patch Catalog Service APIs
Contains APIs for working with catalogs and patches in Automation Console.
API call | Description |
|---|---|
| Catalogs API | |
GET/api/v2/catalogs | Retrieves all catalogs imported inAutomation Console. |
POST/api/v2/catalogs | Imports a new catalog from Server Automation. |
GET/api/v1/catalogs/tssa | Retrieves all Microsoft Windows, Red Hat Linux, SUSE Linux, OEL, and CentOS catalogs available in Server Automation. |
GET/api/v1/catalogs/tssa/{catalogId} | Retrieves details for a catalog created in Server Automation for a specified catalog ID. |
GET/api/v2/catalogs/{catalogId} | Retrieves details for a catalog imported in Automation Console for a specified catalog ID. |
PUT/api/v2/catalogs/{catalogId} | Updates schedule for a specified catalog ID. |
DELETE/api/v2/catalogs/{catalogId} | Deletes the specified catalog from Automation Console. |
PUT/api/v2/catalogs/{catalogId}/enable | Enables automatic synchronization for a catalog. |
PUT/api/v2/catalogs/{catalogId}/disable | Disables automatic synchronization for a catalog. |
| Patches API | |
PUT/api/v1/catalogs/patch | Retrieves all patches based on the patch IDs. |
PUT/api/v1/catalogs/{catalogId}/patch/search | Retrieves all patches of the specified catalog (that match the filters) from Automation Console |
PUT/api/v1/catalogs/patch/search | Retrieves patches based on the specified CVE IDs. |
PUT/api/v2/catalogs/patch/search | Retrieves patches based on CVE IDs. |
| Support API | |
POST/api/v2/catalogs/{catalogId}/sync | Performs a force sync of the catalog details from TrueSight Server Automation. Note BMC recommends that you do not use this API call. This API call is only made available to the BMC Customer Support team for debugging or recovering from problems. |
Patch Policy and Operations APIs
Contains the APIs for working with remediation jobs, patch policies, compliance scan policies, vulnerability scans, and so on.
API call | Description |
|---|---|
| JobRun API | |
GET/api/v1/policies/job/{jobRunId}/summary | Retrieves summary for the specified job run ID. |
GET/api/v1/policies/job/{jobRunId}/target | Retrieves summary for the specified job run ID and target. |
GET/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 | Retrieves job runs for the specified policy ID. |
GET/api/v1/policies/{policyId}/runs/{runId}/logs | Retrieves event logs for a specified policy scan run. |
NEW IN 21.02.01GET/api/v2/policies/operations/{operation_id}/jobs/{job_id}/runs/{job_run_id}/summary | Retrieves the job run summary for the specified operation ID, job ID, job run ID, and sequence ID. |
NEW IN 21.02.01GET /api/v2/policies/operations/{operation_id}/jobs/{job_id}/runs/{job_run_id}/target | Retrieves target wise job runs from TrueSight Server Automation for the specified operation ID, job ID, job run ID, and sequence ID. |
NEW IN 21.02.01GET/api/v2/policies/operations/{operation_id}/jobs/{job_id}/runs | Retrieves all the job runs for the specified policy ID, job ID, and sequence ID. |
| Patch Policy API | Description |
POST/api/v1/policies | Creates a new patch policy. |
GET/api/v1/policies/tssa/groups/{type} | Retrieves all static groups created in Server Automation. |
POST/api/v1/policies/tssa/groups/{type} | Creates a static group in Server Automation. |
GET/api/v1/policies/tssa/smart-groups/{type} | Retrieves all dynamic groups created in Server Automation. |
POST/api/v1/policies/policy/{policyId}/jobruns | Executes a patch policy associated with specified policy ID immediately. |
GET/api/v1/policies/search | Retrieves a list of policies created in the Automation Console. |
GET/api/v2/policies | Retrieves a list of policies created in the Automation Console. |
PATCH/api/v2/policies/{policyId}/bookmark | Bookmarks an existing policy. This API call is applicable for operation templates only. |
POST/api/v1/policies/reports/patch-compliance | Retrieves patch compliance results for a policy. |
POST/api/v1/policies/reports/patch-compliance/detail | Retrieves patch compliance details for a policy. |
GET/api/v1/policies/{policy_id} | Retrieves information for a specified policy ID. |
PUT/api/v1/policies/{policy_id} | Updates an existing policy. |
| Vulnerability scan API | |
POST/api/v1/policies/import-scan | Imports a vulnerability scan. |
TrueSight Server Automation API | |
GET/api/v1/policies/tssa/nshscripts | Retrieves all NSH Scripts defined in Server Automation. |
GET/api/v1/policies/tssa/bl-packages | Retrieves all BLPackages defined in Server Automation. |
GET/api/v1/policies/tssa/nshscripts/{scriptId} | Retrieves NSH Script details from Server Automation. |
POST/api/v1/policies/tssa/depots/search | Search depot object based on given condition. |
GET/api/v1/policies/tssa/jobs/{type} | Retrieves all the jobs defined in Server Automation. |
GET/api/v1/policies/tssa/jobs/{type}/{jobId} | Retrieves information for a specified job ID from Server Automation. |
| Operations API | |
POST/api/v1/policies/operations | Creates a remediation operation in Automation Console. |
POST/api/v1/policies/operations/search | Retrieves all operations in Automation Console. |
POST/api/v1/policies/operations/prepare-list | Prepares an operation list. |
PATCH/api/v1/policies/operations/execute/{operationId} | Executes an operation for a specified ID. |
GET/api/v1/policies/operations/{operationId}/suboperations | Retrieves child operations of a parent operation. |
DELETE/api/v1/policies/operations/{operation_id} | Deletes a specified operation. |
NEW IN 21.02.01GET /api/v2/policies/operations/{operation_id}/jobs | Retrieves the jobs of the specified Batch job operation. |
| Operation Template API | |
POST/api/v2/policies/operation-templates | Creates an operation template in Automation Console. |
POST/api/v2/policies/operation-templates/search | Retrieves an operation template based on the specified search filters. |
GET/api/v2/policies/operation-templates/{operation_template_id} | Retrieves an operation template. |
DELETE/api/v2/policies/operation-templates/{operation_template_id} | Deletes an operation template. |
PATCH/api/v2/policies/operation-templates/{operation_template_id} | Shares an operation template with the specified security groups. |
PUT/api/v2/policies/operation-templates/{operation_template_id} | Updates an operation template. |
| Compliance Policy API | |
POST/api/v2/policies/compliance-scans | Creates a new compliance policy. |
PUT/api/v2/policies/compliance-scans/{policyId}/enable | Enables a compliance scan policy. |
PUT/api/v2/policies/compliance-scans/{policyId}/disable | Disables a compliance scan policy. |
DELETE/api/v2/policies/compliance-scans/{policyId} | Deletes a compliance scan policy. |
POST/api/v2/policies/compliance-scans/{policyId}/jobruns | Executes the compliance scan policy associated with specified policy ID immediately. |
| Compliance Job Run API | |
GET/api/v2/policies/compliance-scans/{complianceScanPolicyId}/runs | Retrieves job runs for the specified compliance scan policy ID. |
GET/api/v2/policies/compliance-scans/runs/{runId}/summary | Retrieves an overall summary for the specified compliance scan policy ID and job run ID. |
GET/api/v2/policies/compliance-scans/runs/{runId}/targets | Retrieves a summary of the job runs for the specified compliance scan policy ID and job run ID. |
GET/api/v2/policies/compliance-scans/runs/{runId}/targets/{targetId} | Retrieves job runs target details for the specified compliance scan policy ID, job run ID, and target ID |
| ITIL API | |
GET/api/v1/policies/itil/configurations | Retrieves IT Service Management configuration. |
GET/api/v1/policies/itil/status/{changeId} | Retrieves the status of the change request created in the ITSM system. |
| Status Count | |
GET/api/v1/policies/operations/status/summary | Retrieves operations count by status. |
| Patch Policy API | |
POST/api/v2/policies/patch-policies | Creates a new patch policy. |
GET/api/v2/policies/patch-policies | Retrieves all patch policies. |
GET/api/v2/policies/patch-policies/{policy_id} | Retrieves information for a specified patch policy ID. |
PUT/api/v2/policies/patch-policies/{policy_id} | Updates an existing patch policy. |
DELETE/api/v2/policies/patch-policies/{policy_id} | Deletes a patch policy. |
PUT/api/v2/policies/patch-policies/{policy_id}/enable | Enables the patch policy for a specified policy ID. |
PUT/api/v2/policies/patch-policies/{policy_id}/disable | Disables the patch policy for a specified policy ID. |
POST/api/v2/policies/patch-policies/{policyId}/jobruns | Immediately executes the scan policy associated with the specified patch policy ID. |
GET/api/v2/policies/patch-policies/summary | Retrieves a count of policies group by operating system and its vendor. |
| Templates API | |
GET/api/v2/policies/tssa/templates | Retrieves all TrueSight Server Automation compliance templates. |
Violations and Dashboard Service APIs
Contains APIs for the Dashboard, Missing Patches (referred as Violations in the API), Activities, Custom tags, and Assets.
API call | Description |
|---|---|
| Activities API | |
GET/api/v1/activities/{id} | Retrieves the details for an activity such as the status. |
PUT/api/v1/activities/cancel | Cancels an activity and marks it as Failed. |
| Assets | |
POST/api/v1/violations/reports/targets/{type} | Retrieves all assets based on the asset type. |
PUT/api/v1/violations/asset/manual-map/{resourceId} | Maps scanner asset to endpoint targets manually. |
PUT/api/v1/violations/asset/unmap | Unmaps scanned assets with the endpoints in the endpoint manager. |
GET/api/v1/assets/metadata/business-services | Retrieves a list of unique business services. |
GET/api/v1/assets/metadata/os/{type} | Retrieves a list of unique operating systems and vendors. |
POST/api/v1/violations/assets | Retrieves details of all the assets for a specified given patch policy. |
| Custom Tags | |
POST/api/v1/violations/tags/search | Retrieves unique custom tags. |
POST/api/v1/violations/tags | Creates custom tags. Note You must have administrator permissions to use this API call. |
GET/api/v1/violations/tags | Retrieves all custom tags. |
PUT/api/v1/violations/tags/{id} | Updates the custom tag for the specified tag ID. Note You must have administrator permissions to use this API call. |
DELETE/api/v1/violations/tags/{id} | Deletes the custom tag for a specified ID. |
| Dashboard API | |
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/sla/detail | Generates details for the assets and missing patches based on their SLA levels. |
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/services/summary | Retrieves the list of objects with details such as business service name, violation and assets count associated with that particular business service. |
GET/api/v1/violations/reports/targets/discovery/mapped/{sourcetype} | Retrieves the count of targets mapped to discovery based on selected source. |
POST/api/v1/violations/reports/services/summary/{types} | Retrieves the list of object having violation name and severity or asset name and operating system platform based on the request type. |
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. |
POST | Retrieves the list of objects with the operating system and its missing count. |
POST/api/v2/violations/reports/policies/summary | Retrieves the list of objects with policy ID and rules and assets associated with that policy ID along with state wise distribution of vulnerability and assets. |
POST/api/v2/violations/reports/policies/details/{policy_id} | Retrieves the details for the given policy ID along with rules and assets associated with that policy id along with state wise distribution of vulnerability and assets. |
POST/api/v2/violations/reports/policies/violations/summary | Retrieves the list of objects with details such as the violation name, assets count, policy details and SLA type. |
POST/api/v2/violations/reports/states/summary | Retrieves the summary for different compliance states for vulnerability and assets. |
| Violations API | |
POST/api/v1/violations | Creates violations for a specified asset. |
GET/api/v1/violations | Retrieves details of the violations. |
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. Tags such as the risk score, owner, SLA deadlines and warnings can be updated. |
GET/api/v1/violations/{id} | Retrieves details of the violations based on the ID. |
POST/api/v2/violations/search/{type} | Retrieves all vulnerabilities or missing patches. |
POST/api/v1/violations/reports/patch | Exports the patch report in .csv format. |
GET/api/v1/violations/metadata/cveid | Retrieves all distinct CVE IDs identified against the violations. |
POST/api/v1/violations/riskscore | Retrieves all risk scores. |
POST/api/v1/violations/owner | Gets all risk owners. |
| Vulnerability API | |
POST/api/v1/violations/reports/vulnerability | Exports the vulnerability report in .csv format. |
POST/api/v2/violations/search/{type} | Retrieves all vulnerabilities or missing patches |
POST/api/v1/violations/search/vulnerabilities | Retrieves all vulnerabilities. |
POST/api/v1/violations/search/vats | Retrieves all actionable VATs. |
POST/api/v2/violations/search/vats | Retrieves all actionable 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 API | |
POST/api/v1/assets/scanned/tags | Imports tags in a CSV file. |
Support API Note BMC recommends that you do not use these API calls. These APIs are only made available to the BMC Customer Support team for debugging or recovering from problems. | |
GET/api/v1/activities/{id} | Retrieves details of an activity. |
PUT/api/v1/activities/cancel | Cancels an activity and marks it as FAILED. |
POST/api/v1/violations/poolsync | Retrieves all the resources from the resource service and sync it to asset state service database. |
Comments
Log in or register to comment.