This documentation supports the 20.02 (12.0) version of BMC Discovery.

To view an earlier version of the product, select the version from the Product version menu.

Using the REST API

The REST API is intended to be used by a script or program to interact with and control BMC Discovery from a remote machine. You can use the API for a variety of tasks, such as:

  • Submitting discovery runs
  • Managing credentials
  • Querying the data in your system
  • Uploading TKUs

The aim of the API is to enable you to perform most tasks that you can currently do through the BMC Discovery UI or command line utilities. The XML and CSV export APIs are still supported, but the REST API provides more control when retrieving data, and a range of features across its endpoints.

The API follows the REST architectural style, so resources, HTTP verbs, and status codes are used. JSON is used for request and response bodies. The endpoints provided by the API are specified using the Swagger specification language. All endpoints use the OAuth 2.0 protocol for authentication.

This topic explains how to submit your first request to the REST API.

See the following video (06:30) which demonstrates how you can use REST API for discovery tasks, such as submitting discovery runs, managing credentials, or uploading TKUs. You can also use the Swagger UI to test the REST API.


The REST API is only accessible over HTTPS.

Using the Swagger UI

Calls to the REST API can be made from any scripting or programming language that supports HTTP. However, this topic starts with a user interface to the API called Swagger UI. To access the Swagger UI, from any page in the BMC Discovery UI, click the Help  icon and then the REST API link:

This launches the Swagger UI, which enables you to explore and interact with all endpoints in the REST API:


Authenticating with a token

Requests to every endpoint in the REST API must be made on behalf of a BMC Discovery user. The authentication mechanism is token-based, but the Swagger UI lets you generate a token from the credentials of a valid BMC Discovery user. This can be any local or LDAP user, but the user must have the api-access permission. For local users, your administrator can grant this permission on the Users administration page.

For LDAP users, your administrator can use group mapping.

Once your user has the api-access permission, click "Authorize" in the top right of the Swagger UI to display the "Available Authorizations" dialog:

Enter your BMC Discovery username and password in the "OAuth 2.0" section of this dialog. Then click Authorize to return to the main Swagger UI page. A token is now requested in the background and added to each subsequent endpoint request. To find out more about authentication and tokens, see Authentication and permissions in the REST API.

Calling an endpoint

Now you can make your first explicit API request. Expand the "discovery" category and the GET /discovery endpoint. Then click "Try it out!" to call the endpoint. A successful request will return the current status of the discovery system. To understand the results structure, click "Model" in the Response Class section of this endpoint:

If you experience problems calling the endpoint, see the Troubleshooting the REST API topic. Otherwise, you can now experiment with any of the other endpoints.


The Swagger UI allows you to call any endpoint in the REST API, but does not provide a sandbox for this experimentation. Some endpoints make changes to the state of the appliance - for example, creating a new discovery run or deleting a credential. Only call these endpoints from the Swagger UI if you are happy for the changes to be made on the appliance you are connected to.

Calling the API from real clients

The Swagger UI is convenient for experimenting with the REST API. However, for real clients, calls to the API can be made from any scripting or programming language that supports HTTP. An extremely simple example is the command line tool curl. A request to the same /discovery endpoint as above, using curl, looks like:

curl -i -X GET -H 'Authorization: bearer <your_token>' 'https://appliance/api/v1.0/discovery'

HTTP/1.1 200 OK
    "running": false,
    "status": "running"

curl is used for example API requests in other topics in this section.

The Swagger UI also shows the equivalent curl command for requests:

Whatever client language or tool you use to call the REST API, it is recommended you read all related topics first to see how to construct valid requests and handle responses.

Was this page helpful? Yes No Submitting... Thank you