This documentation supports the 21.05 (12.2) version of BMC Discovery.

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

Endpoints in the REST API

This version of BMC Discovery supports versions 1.2 of the REST API and earlier. Higher versions are always backwards compatible with earlier versions.

The base URL for the latest API version is:

https://appliance_name/api/v1.2

discovery

Control scanning and view results

GET /discovery
Description

Get the current status of the discovery process

Responses

Code

Description

Schema

200

successful operation

{
  running: boolean*
  Are there any discovery runs in progress?
 
  status: string*
  Current status of the discovery process
  Enum: [
    "starting",
    "running",
    "stopping",
    "stopped"
  ]
}

PATCH /discovery
Description

Either start or stop the discovery process. Note this call can return before the desired state has been reached.

Parameters

Name

Located in

Description

Default

Schema

body

body

{
  status: string*
  Desired status of the discovery
  Enum: [
    "running",
    "stopped"
  ]
 
  passphrase: string
  Passphrase to open the vault before starting discovery. Only required if the vault is closed and protected by a passphrase.
}

Responses

Code

Description

Schema

200

successful operation

GET /discovery/api_provider_metadata
Description

Get metadata for the API providers currently supported by BMC Discovery. This can be used as a reference when interacting with the /discovery/runs and /vault/credentials endpoints. Support for new API providers is available in TKU knowledge updates.

New in version 1.2

Responses

Code

Description

Schema

200

successful operation

[
  A list of API providers, along with information on the fields required to create API scans and API credentials for each provider
 
   {
    provider: string*
    Name of the API provider. Used for the 'scan_params.provider' field in the /discovery/runs endpoints, and as an entry in the 'types' list in the /vault/credentials endpoints
 
    scan_params: [
      List of additional 'scan_params' fields this API provider supports in the /discovery/runs endpoint
 
       {
        name: string*
        Name of the field in the 'scan_params' object
 
        description: string*
        type: string*
        The type of this field
 
        is_list: boolean*
        Whether this field is a list of values or a single instance
 
        mandatory: boolean*
        Whether this field is required to create a new API scan or can be skipped
 
        allowed_values: {
          The allowed values for this field. The values are the keys of this object, with descriptions for the values
        }*
      }
    ]*
 
    cred_params: [
      List of additional fields this API provider supports in the /vault/credentials endpoints
 
       {
        name: string*
        Name of this field in the credentials object
 
        description: string*
        type: string*
        The type of this field
 
        is_list: boolean*
        Whether this field is a list of values or a single instance
 
        mandatory: boolean*
        Whether this field is required to create a new API provider credential or can be skipped
 
        allowed_values: [
          The allowed values for this field
 
          string
        ]*
      }
    ]*
  }
]

GET /discovery/cloud_metadata
Description

Get metadata for the cloud providers currently supported by BMC Discovery. This can be used as a reference when interacting with the /discovery/runs and /vault/credentials endpoints. Support for new cloud providers is available in TKU knowledge updates.

New in version 1.1

Responses

Code

Description

Schema

200

successful operation

[
  A list of cloud providers, along with information on the fields required to create cloud scans and cloud credentials for each provider
 
   {
    provider: string*
    Name of the cloud provider. Used for the 'scan_params.provider' field in the /discovery/runs endpoints, and as an entry in the 'types' list in the /vault/credentials endpoints
 
    scan_params: [
      List of additional 'scan_params' fields this cloud provider supports in the /discovery/runs endpoint
 
       {
        name: string*
        Name of the field in the 'scan_params' object
 
        description: string*
        type: string*
        The type of this field
 
        is_list: boolean*
        Whether this field is a list of values or a single instance
 
        mandatory: boolean*
        Whether this field is required to create a new cloud scan or can be skipped
 
        allowed_values: {
          The allowed values for this field. The values are the keys of this object, with descriptions for the values
        }*
      }
    ]*
 
    cred_params: [
      List of additional fields this cloud provider supports in the /vault/credentials endpoints
 
       {
        name: string*
        Name of this field in the credentials object
 
        description: string*
        type: string*
        The type of this field
 
        is_list: boolean*
        Whether this field is a list of values or a single instance
 
        mandatory: boolean*
        Whether this field is required to create a new cloud credential or can be skipped
 
        allowed_values: [
          The allowed values for this field
 
          string
        ]*
      }
    ]*
  }
]

GET /discovery/runs
Description

Get details of all currently processing discovery runs.

Responses

Code

Description

Schema

200

successful operation

[
   run {
    cancelled: string
    If present indicates the discovery run was cancelled. Field contents provides more details.
 
    blocked: boolean
    Flag to indicate if the discovery run is blocked waiting for other prerequisites
 
    done: int64
    Number of completed addresses
 
    key: string*
    Unique identity string for the discovery run
 
    label: string*
    Label of the discovery run
 
    scan_kind: string
    If this is an API or Cloud scan, the 'scan_params' field will also be populated
    Enum: [
      "IP",
      "Cloud",
      "API"
    ]
 
    outpost_id: string
    Used for IP scans only. Discovery Outpost to use for scanning range. No value means any, empty string means local discovery on the appliance or cluster.
 
    scope: string
    Distinguish overlapping address spaces
 
    scan_level: string*
    Scan level
 
    scan_params: {
      Used for API and Cloud scans only. The 'provider' field contains the name of the API or cloud provider being scanned. Each provider also supports a different set of additional fields. Look up the API provider with the /discovery/api_provider_metadata endpoint and the cloud provider with the /discovery/cloud_metadata endpoint to see which fields to expect here
 
      provider: string*
      Name of the API or cloud provider being scanned
    }
 
    scan_options: scanOptions {
      Options controlling the scan. May be extended in future releases.
 
      NO_PING: boolean
      Skip ping before scanning. Used for IP scans only. If this option is omitted, the system default controls whether to ping or not.
 
      SESSION_LOGGING: boolean
      Create session logs during scanning. Used for IP snapshot scans only. If this option is omitted, session logs will not be created.
 
      SKIP_IMPLICIT_SCANS: boolean
      Skip implicit scanning. This is only supported by some access methods. If this option is omitted, implicit scanning will be performed.
 
      MAX_START_SSM_SESSIONS: int64
      Maximum number of concurrent SSM start session requests per region per account. This is only supported for AWS cloud scans. If this option is omitted, the system default sets the limit.
 
      MAX_ACTIVE_SSM_SESSIONS: int64
      Maximum number of active SSM sessions per region per account. This is only supported for AWS cloud scans. If this option is omitted, the system default sets the limit.
    }
 
    scan_type: string*
    Type of scan
 
    scanning: int64
    Number of addresses being scanned
 
    pre_scanning: int64
    Number of addresses being pre-scanned
 
    starttime: date-time*
    Date and time the run started
 
    total: int64
    Number of addresses in the discovery run
 
    user: string*
    User who created the discovery run
 
    valid_ranges: string
    Valid IP address ranges in the run
 
    waiting: int64
    Number of addresses waiting for end of exclude range
 
    uuid: string*
    ID of the discovery run
 
    uri: string*
    URI to the detail information of the discovery run
 
    finished: boolean*
    Flag to indicate if the discovery run is finished
 
    inferred: string*
    URI to the inferred information of the discovery run
 
    results: string*
    URI to the summarized information of the discovery run
 
    consolidating: boolean*
    Flag to indicate if the discovery run is consolidated from another appliance
 
    consolidation_source: string
    Consolidating appliance name of the discovery run. If the consolidating appliance is in a cluster, this field will represent the cluster name (only present if the run is consolidated from another)
  }
]

POST /discovery/runs
Description

Create a new snapshot discovery run.

Use the returned 'uuid' as the run_id to check the status of the new run at /discovery/runs/{run_id}.

New in version 1.1 - added support for cloud scans, added support for scan_options field.

New in version 1.2 - added support for API scans.

Parameters

Name

Located in

Description

Default

Schema

body

body

Snapshot discovery run to be created

newRun {
  scan_kind: string
  Depending on the kind of scan chosen here, populate either the 'ranges' or 'scan_params' fields.
  Enum: [
    "IP",
    "Cloud",
    "API"
  ]
 
  outpost_id: string
  Used for IP scans only. Discovery Outpost to use for scanning range. No value means any, 'Local discovery' means local discovery on the appliance or cluster.
 
  scope: string
  ranges: [
    Used for IP scans only. A list of IP addresses or ranges.
 
    string
  ]
 
  label: string*
  scan_level: string
  Enum: [
    "Full Discovery",
    "Sweep Scan"
  ]
  company: string
  scan_params: {
    Used for API and Cloud scans only. Populate the 'provider' field with the name of the API or cloud provider to scan. Each provider then requires a different set of additional fields. Look up your chosen cloud provider with the /discovery/cloud_metadata endpoint to see which fields to populate in this object.
 
    provider: string*
    Name of the API or cloud provider to scan
  }
 
  scan_options: scanOptions {
    Options controlling the scan. May be extended in future releases.
 
    NO_PING: boolean
    Skip ping before scanning. Used for IP scans only. If this option is omitted, the system default controls whether to ping or not.
 
    SESSION_LOGGING: boolean
    Create session logs during scanning. Used for IP snapshot scans only. If this option is omitted, session logs will not be created.
 
    SKIP_IMPLICIT_SCANS: boolean
    Skip implicit scanning. This is only supported by some access methods. If this option is omitted, implicit scanning will be performed.
 
    MAX_START_SSM_SESSIONS: int64
    Maximum number of concurrent SSM start session requests per region per account. This is only supported for AWS cloud scans. If this option is omitted, the system default sets the limit.
 
    MAX_ACTIVE_SSM_SESSIONS: int64
    Maximum number of active SSM sessions per region per account. This is only supported for AWS cloud scans. If this option is omitted, the system default sets the limit.
  }
}

Responses

Code

Description

Schema

200

successful operation

{
  uuid: string*
  uri: string*
}

GET /discovery/runs/{run_id}
Description

This endpoint is lightweight to call so should be used if you need to poll until a discovery run has finished. When the 'finished' field is returned as true then use the more costly /discovery/runs/{run_id}/results and /discovery/runs/{run_id}/inferred endpoints to start exploring the results of the run.

Parameters

Name

Located in

Description

Default

Schema

run_id

path

ID of the discovery run

string*

Responses

Code

Description

Schema

200

successful operation

run {
  cancelled: string
  If present indicates the discovery run was cancelled. Field contents provides more details.
 
  blocked: boolean
  Flag to indicate if the discovery run is blocked waiting for other prerequisites
 
  done: int64
  Number of completed addresses
 
  key: string*
  Unique identity string for the discovery run
 
  label: string*
  Label of the discovery run
 
  scan_kind: string
  If this is an API or Cloud scan, the 'scan_params' field will also be populated
  Enum: [
    "IP",
    "Cloud",
    "API"
  ]
 
  outpost_id: string
  Used for IP scans only. Discovery Outpost to use for scanning range. No value means any, empty string means local discovery on the appliance or cluster.
 
  scope: string
  Distinguish overlapping address spaces
 
  scan_level: string*
  Scan level
 
  scan_params: {
    Used for API and Cloud scans only. The 'provider' field contains the name of the API or cloud provider being scanned. Each provider also supports a different set of additional fields. Look up the API provider with the /discovery/api_provider_metadata endpoint and the cloud provider with the /discovery/cloud_metadata endpoint to see which fields to expect here
 
    provider: string*
    Name of the API or cloud provider being scanned
  }
 
  scan_options: scanOptions {
    Options controlling the scan. May be extended in future releases.
 
    NO_PING: boolean
    Skip ping before scanning. Used for IP scans only. If this option is omitted, the system default controls whether to ping or not.
 
    SESSION_LOGGING: boolean
    Create session logs during scanning. Used for IP snapshot scans only. If this option is omitted, session logs will not be created.
 
    SKIP_IMPLICIT_SCANS: boolean
    Skip implicit scanning. This is only supported by some access methods. If this option is omitted, implicit scanning will be performed.
 
    MAX_START_SSM_SESSIONS: int64
    Maximum number of concurrent SSM start session requests per region per account. This is only supported for AWS cloud scans. If this option is omitted, the system default sets the limit.
 
    MAX_ACTIVE_SSM_SESSIONS: int64
    Maximum number of active SSM sessions per region per account. This is only supported for AWS cloud scans. If this option is omitted, the system default sets the limit.
  }
 
  scan_type: string*
  Type of scan
 
  scanning: int64
  Number of addresses being scanned
 
  pre_scanning: int64
  Number of addresses being pre-scanned
 
  starttime: date-time*
  Date and time the run started
 
  total: int64
  Number of addresses in the discovery run
 
  user: string*
  User who created the discovery run
 
  valid_ranges: string
  Valid IP address ranges in the run
 
  waiting: int64
  Number of addresses waiting for end of exclude range
 
  uuid: string*
  ID of the discovery run
 
  uri: string*
  URI to the detail information of the discovery run
 
  finished: boolean*
  Flag to indicate if the discovery run is finished
 
  inferred: string*
  URI to the inferred information of the discovery run
 
  results: string*
  URI to the summarized information of the discovery run
 
  consolidating: boolean*
  Flag to indicate if the discovery run is consolidated from another appliance
 
  consolidation_source: string
  Consolidating appliance name of the discovery run. If the consolidating appliance is in a cluster, this field will represent the cluster name (only present if the run is consolidated from another)
}

404

Invalid run id

PATCH /discovery/runs/{run_id}
Parameters

Name

Located in

Description

Default

Schema

run_id

path

ID of the discovery run

string*

body

body

patchRunCancelled {
  cancelled: boolean*
  Flag if the discovery run should be cancelled
}

Responses

Code

Description

Schema

200

successful operation

boolean
Indicate if the cancellation is successfully performed

GET /discovery/runs/{run_id}/results
Description

Get a summary of the results from scanning all endpoints in the run, partitioned by result type.

Parameters

Name

Located in

Description

Default

Schema

run_id

path

ID of the discovery run

string*

Responses

Code

Description

Schema

200

successful operation

runResultsSummary {
  Success: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  Skipped: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  NoAccess: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  NoResponse: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  Error: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  Dropped: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
}

GET /discovery/runs/{run_id}/results/{result_type}
Description

Get a summary of the results from scanning all endpoints in the run that had a specific type of result. Results are returned in the same paginated format as in /data/search. See that endpoint for details on the following parameters:

  • offset
  • limit
  • results_id
  • delete
Parameters

Name

Located in

Description

Default

Schema

run_id

path

ID of the discovery run

string*

result_type

path

string*
Enum: [
  "Success",
  "Skipped",
  "NoAccess",
  "NoResponse",
  "Error",
  "Dropped"
]

offset

query

0

integer

limit

query

100

integer

results_id

query

string

delete

query

boolean

Responses

Code

Description

Schema

200

Returns results in the same paginated format as the search endpoints

[
   searchResults {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. A list of rows, where each cell is of any type
 
       [
        One row of results
 
        any
        A single cell in a results row. Can be of any type
      ]
    ]*
 
    headings: [
      The headings for the rows in 'results'
 
      string
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

GET /discovery/runs/{run_id}/results/{result_type}?format=object
Description

As /discovery/runs/{run_id}/results/{result_type} but returns found nodes as objects instead of rows of attribute values.

Parameters

Name

Located in

Description

Default

Schema

run_id

path

ID of the discovery run

string*

result_type

path

string*
Enum: [
  "Success",
  "Skipped",
  "NoAccess",
  "NoResponse",
  "Error",
  "Dropped"
]

offset

query

0

integer

limit

query

100

integer

results_id

query

string

delete

query

boolean

Responses

Code

Description

Schema

200

Returns results in the same paginated format as the search endpoints

[
   searchResultsAsObjects {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. List of items represented as objects, with attribute names and values. Values can be any type.
 
       {
      }
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

GET /discovery/runs/{run_id}/inferred
Description

Get a summary of all inferred devices from a discovery run, partitioned by device type.

From BMC Discovery 11.2 patch 2, this summary also includes device kinds specific to cloud discovery.

Parameters

Name

Located in

Description

Default

Schema

run_id

path

ID of the discovery run

string*

Responses

Code

Description

Schema

200

successful operation

runInferredSummary {
  Host: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  MFPart: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  NetworkDevice: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  Printer: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  SNMPManagedDevice: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  ManagementController: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  StorageDevice: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  StorageSystem: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  VirtualMachine: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  LoadBalancerService: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  SoftwareInstance: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
  StorageVolume: resultsSummary {
    count: int64*
    uri: string*
    Where to go for more information
  }
}

GET /discovery/runs/{run_id}/inferred/{inferred_kind}
Description

Get a summary of the devices inferred by a discovery run which have a specific inferred kind. Results are returned in the same paginated format as in /data/search. See that endpoint for details on the following parameters:

  • offset
  • limit
  • results_id
  • delete
Parameters

Name

Located in

Description

Default

Schema

run_id

path

ID of the discovery run

string*

inferred_kind

path

string*

offset

query

0

integer

limit

query

100

integer

results_id

query

string

delete

query

boolean

Responses

Code

Description

Schema

200

Returns results in the same paginated format as the search endpoints

[
   searchResults {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. A list of rows, where each cell is of any type
 
       [
        One row of results
 
        any
        A single cell in a results row. Can be of any type
      ]
    ]*
 
    headings: [
      The headings for the rows in 'results'
 
      string
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

404

No such run id or inferred kind

GET /discovery/runs/{run_id}/inferred/{inferred_kind}?format=object
Description

As /discovery/runs/{run_id}/inferred/{inferred_kind} but returns found nodes as objects instead of rows of attribute values.

Parameters

Name

Located in

Description

Default

Schema

run_id

path

ID of the discovery run

string*

inferred_kind

path

string*

offset

query

0

integer

limit

query

100

integer

results_id

query

string

delete

query

boolean

Responses

Code

Description

Schema

200

Returns results in the same paginated format as the search endpoints

[
   searchResultsAsObjects {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. List of items represented as objects, with attribute names and values. Values can be any type.
 
       {
      }
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

404

No such run id or inferred kind


data

Read and import data

GET /data/search
Description

Run a search query, receiving paginated results.

Parameters

Name

Located in

Description

Default

Schema

query

query

The search query to run, in BMC Discovery query language. If your query is too long to fit in a url, use POST /data/search

string*

offset

query

The offset of the first item to return in this page of results.
Can only be supplied if requesting results from an existing results set (by supplying a results_id).
If you want to retrieve all items in order, this field should usually take the value of the 'next_offset' from the previous page of results.

0

integer

limit

query

Limits how many items to return in this page of results. Further items can be retrieved by making another request with a different offset.
Use 0 to request the maximum allowed limit.
Can vary from page to page.

100

integer

results_id

query

An opaque id that can be used to access a result set that has already been generated via a previous search request. Must be supplied if requesting an offset greater than 0.
Note that even if retrieving results from an existing results set, the original query must be supplied in case the result set has timed out and the query needs to be re-run.
The results_id can be found in any page of results apart from the last one.

string

delete

query

Controls whether the result set is deleted or not before results are returned.
Result sets are deleted automatically before the last page of results are returned, but setting this field to true on any page will delete the result set immediately.
This is an optimization to free resources if you don't plan on accessing any further pages of data. Alternatively, if set to false, automatic deletion of the result set will not happen (for this request).

boolean

Responses

Code

Description

Schema

200

As a search query may return multiple results sets of different kinds, the response is a list of results objects - one per kind

[
   searchResults {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. A list of rows, where each cell is of any type
 
       [
        One row of results
 
        any
        A single cell in a results row. Can be of any type
      ]
    ]*
 
    headings: [
      The headings for the rows in 'results'
 
      string
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

POST /data/search
Description

An alternative to GET /data/search, for search queries which are too long for URLs.

Parameters

Name

Located in

Description

Default

Schema

offset

query

0

integer

limit

query

100

integer

results_id

query

string

delete

query

boolean

body

body

searchQuery {
  query: string*
  The search query to run
}

Responses

Code

Description

Schema

200

See notes on GET endpoint results

[
   searchResults {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. A list of rows, where each cell is of any type
 
       [
        One row of results
 
        any
        A single cell in a results row. Can be of any type
      ]
    ]*
 
    headings: [
      The headings for the rows in 'results'
 
      string
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

GET /data/search?format=object
Description

As /data/search but returns results as objects instead of rows of values.

Parameters

Name

Located in

Description

Default

Schema

query

query

string*

offset

query

0

integer

limit

query

100

integer

results_id

query

string

delete

query

boolean

Responses

Code

Description

Schema

200

As a search query may return multiple results sets of different kinds, the response is a list of results objects - one per kind

[
   searchResultsAsObjects {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. List of items represented as objects, with attribute names and values. Values can be any type.
 
       {
      }
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

POST /data/search?format=object
Description

An alternative to GET /data/search?format=object, for search queries which are too long for urls.

Parameters

Name

Located in

Description

Default

Schema

offset

query

0

integer

limit

query

100

integer

results_id

query

string

delete

query

boolean

body

body

searchQuery {
  query: string*
  The search query to run
}

Responses

Code

Description

Schema

200

See notes on GET endpoint results

[
   searchResultsAsObjects {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. List of items represented as objects, with attribute names and values. Values can be any type.
 
       {
      }
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

GET /data/search?format=tree
Description

As /data/search but returns results as a tree of objects.

Parameters

Name

Located in

Description

Default

Schema

query

query

string*

offset

query

0

integer

limit

query

100

integer

results_id

query

string

delete

query

boolean

Responses

Code

Description

Schema

200

As a search query may return multiple results sets of different kinds, the response is a list of results objects - one per kind

[
   searchResultsAsObjects {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. List of items represented as objects, with attribute names and values. Values can be any type.
 
       {
      }
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

POST /data/search?format=tree
Description

An alternative to GET /data/search?format=tree, for search queries which are too long for urls.

Parameters

Name

Located in

Description

Default

Schema

offset

query

0

integer

limit

query

100

integer

results_id

query

string

delete

query

boolean

body

body

searchQuery {
  query: string*
  The search query to run
}

Responses

Code

Description

Schema

200

See notes on GET endpoint results

[
   searchResultsAsObjects {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. List of items represented as objects, with attribute names and values. Values can be any type.
 
       {
      }
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

POST /data/candidate
Description

New in version 1.2 - added support for best candidate search.

Parameters

Name

Located in

Description

Default

Schema

body

body

candidateInput {
  kind: string*
  Node kind to search candidates into, * means all supported node kinds
  Enum: [
    "Host",
    "NetworkDevice",
    "SNMPManagedDevice",
    "Printer",
    "ManagementController",
    "StorageSystem",
    "*"
  ]
 
  name: string
  hostname: string
  sysname: string
  serial: string
  uuid: string
  wwnn: string
  scope: string
  endpoint: string
  dns_name: [
    DNS name to search for, it can be a string or an array of strings
 
    string
  ]
 
  ip_address: [
    IP address to search for, it can be a string or an array of strings
 
    string
  ]
 
  mac_address: [
    MAC address to search for, it can be a string or an array of strings
 
    string
  ]
 
  limit: integer
  attributes: [
    If specified, only these attributes will be retrieved for each node in the results. Otherwise a default set will be used and the node ID will be provided. The score is provided regardless of the attributes requested.
 
    string
  ]
}

Responses

Code

Description

Schema

200

The node object of the best candidate based on the provided parameters.

candidateResult {
  Object represented with attribute names and values. Values can be any type. The score is provided regardless of the attributes requested.
 
  score: integer*
  Score evaluation of the result based on the provided criteria.
}

POST /data/candidates
Description

New in version 1.2 - added support for top candidates search.

Parameters

Name

Located in

Description

Default

Schema

body

body

candidateInput {
  kind: string*
  Node kind to search candidates into, * means all supported node kinds
  Enum: [
    "Host",
    "NetworkDevice",
    "SNMPManagedDevice",
    "Printer",
    "ManagementController",
    "StorageSystem",
    "*"
  ]
 
  name: string
  hostname: string
  sysname: string
  serial: string
  uuid: string
  wwnn: string
  scope: string
  endpoint: string
  dns_name: [
    DNS name to search for, it can be a string or an array of strings
 
    string
  ]
 
  ip_address: [
    IP address to search for, it can be a string or an array of strings
 
    string
  ]
 
  mac_address: [
    MAC address to search for, it can be a string or an array of strings
 
    string
  ]
 
  limit: integer
  attributes: [
    If specified, only these attributes will be retrieved for each node in the results. Otherwise a default set will be used and the node ID will be provided. The score is provided regardless of the attributes requested.
 
    string
  ]
}

Responses

Code

Description

Schema

200

Enter parameters to identify a device, the response is a list of candidate nodes ordered by descending score

[
   candidateResults {
    count: integer*
    Total number of items in the result set.
 
    results: [
      List of items represented as objects, with attribute names and values. Values can be any type. The score is provided regardless of the attributes requested.
 
       {
      }
    ]*
  }
]

GET /data/nodes/{node_id}
Description

Get the state of a node with specified id

Parameters

Name

Located in

Description

Default

Schema

node_id

path

ID of node to find

string*

Responses

Code

Description

Schema

200

successful operation

nodeResults {
  destroyed: boolean*
  Whether the node is destroyed or not
 
  kind: string*
  The kind of the node
 
  modified: date-time*
  The last modified time of the node
 
  state: {
    The full state of the node, containing all attribute names and values
  }*
}

GET /data/nodes/{node_id}?relationships=true
Description

Get the state of a node with specified id, along with the traversal specs of all current relationships it has.

Parameters

Name

Located in

Description

Default

Schema

node_id

path

ID of node to find

string*

Responses

Code

Description

Schema

200

successful operation

nodeResultsRels {
  destroyed: boolean*
  Whether the node is destroyed or not
 
  kind: string*
  The kind of the node
 
  modified: date-time*
  The last modified time of the node
 
  state: {
    The full state of the node, containing all attribute names and values
  }*
 
  relationships: [
    A list of current live traversal specs that can be followed from this node.
 
    string
  ]*
}

GET /data/nodes/{node_id}?traverse={traverse_spec}
Description

Get the state of a node with specified id, along with the IDs of all nodes reached by following a traversal spec.

Parameters

Name

Located in

Description

Default

Schema

node_id

path

ID of node to find

string*

traverse_spec

path

A traversal spec to follow and retrieve related node IDs. May be wildcarded

string*

flags

query

Search flags to use when traversing to related nodes, comma separated

[
  string
  Enum: [
    "include_destroyed",
    "exclude_current"
  ]
]

Responses

Code

Description

Schema

200

successful operation

nodeResultsTraverse {
  destroyed: boolean*
  Whether the node is destroyed or not
 
  kind: string*
  The kind of the node
 
  modified: date-time*
  The last modified time of the node
 
  state: {
    The full state of the node, containing all attribute names and values
  }*
 
  relationships: {
    Results of following the traversal spec, which may have been wildcarded. Maps each concrete traversal spec to a list of (relationship, target node) pairs that can be reached.
 
    default: [
       traversal {
        rel: string*
        The ID of the relationship node in this traversal.
 
        node: string*
        The ID of the target node reached in this traversal.
      }
    ]
  }*
}

GET /data/nodes/{node_id}?attributes={attributes}
Description

Get the state of a node with specified id, with only the attributes specified.

Parameters

Name

Located in

Description

Default

Schema

node_id

path

ID of node to find

string*

attributes

path

If specified, only these attributes will be retrieved for the node

[
  string
]*

Responses

Code

Description

Schema

200

successful operation

nodeResults {
  destroyed: boolean*
  Whether the node is destroyed or not
 
  kind: string*
  The kind of the node
 
  modified: date-time*
  The last modified time of the node
 
  state: {
    The full state of the node, containing all attribute names and values
  }*
}

GET /data/nodes/{node_id}/graph
Description

Graph data represents a set of nodes and relationships that are associated to the given node. If the node is of ModelDefinition kind, the graph data is obtained from the model's contents rather than running the generic graph traversal function.

Parameters

Name

Located in

Description

Default

Schema

node_id

path

ID of node for which the graph data is generated

string*

focus

query

Context used for determining how the graph should be traversed. Must be one of:

  • 'software-connected': focuses on software and communication between items of software.
  • 'software': focuses on software and communication between items of software that are in the same host.
  • 'infrastructure': focuses on the connectivity to network and storage components.
    Applicable only to node kinds that are not ModelDefinition.

"software-connected"

string
Enum: [
  "software-connected",
  "software",
  "infrastructure"
]

apply_rules

query

Whether to apply global rules - which is a set of pre-defined constraints to prevent traversing to too many nodes - while obtaining the graph data.
Applicable only to node kinds that are not ModelDefinition.

true

boolean

complete

query

Whether to return the complete set of node and relationship attributes when obtaining the graph data.

false

boolean

Responses

Code

Description

Schema

200

successful operation

nodeGraphResults {
  nodes: [
    List of node data involved in the graph data
 
     {
      id: string*
      ID of the node
 
      kind: string*
      Kind of the node
 
      name: string*
      Name of the node
 
      short_name: string*
      Shortened name of the node
    }
  ]*
 
  links: [
    List of relationships involved in the graph data
 
     {
      rel_id: string*
      ID of the relationship
 
      kind: string*
      Kind of the relationship
 
      src_id: string*
      ID of the source node
 
      tgt_id: string*
      ID of the target node
    }
  ]*
}

GET /data/kinds/{kind}
Description

Finds all nodes of a specified node kind. Nodes can be filtered by zero to many attribute value using the request's query string. For example, /data/kinds/Host?os_type=Windows. All attribute values are assumed to be strings. Note that Swagger does not support free-form query strings, so tools (such as the Swagger UI) or code generated for this endpoint will not be aware of these.

Note also that as results of subsequent pages use the query string to control pagination, the following query string keys are reserved:

  • offset
  • limit
  • format
  • delete
  • results_id

For an explanation of these parameters see GET /data/search. More involved filtering can be achieved using that endpoint.

Parameters

Name

Located in

Description

Default

Schema

kind

path

Node kind to retrieve results for

string*

attributes

query

Attributes to retrieve

string

offset

query

0

integer

limit

query

100

integer

results_id

query

string

delete

query

boolean

Responses

Code

Description

Schema

200

Returns results in the same paginated format as the search endpoints

[
   searchResults {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. A list of rows, where each cell is of any type
 
       [
        One row of results
 
        any
        A single cell in a results row. Can be of any type
      ]
    ]*
 
    headings: [
      The headings for the rows in 'results'
 
      string
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

GET /data/kinds/{kind}?format=object
Description

As /data/kinds/{kind} but returns found nodes as objects instead of rows of attribute values.

Parameters

Name

Located in

Description

Default

Schema

kind

path

Node kind to retrieve results for

string*

attributes

query

Attributes to retrieve

string

offset

query

0

integer

limit

query

100

integer

results_id

query

string

delete

query

boolean

Responses

Code

Description

Schema

200

Returns results in the same paginated format as the search endpoints

[
   searchResultsAsObjects {
    kind: string*
    The node kind of these results
 
    count: integer*
    Total number of items of this kind in the result set. Note that if your search query uses the EXPLODE keyword, there may be more rows of results returned in total than the count indicates. This is because items are exploded on demand. Therefore it is important to use the 'next_offset' when requesting the next page of results.
 
    offset: integer*
    The offset of the first item in this page of results
 
    results: [
      One page of results. List of items represented as objects, with attribute names and values. Values can be any type.
 
       {
      }
    ]*
 
    results_id: string
    The opaque id of the results set holding all results of the original search query. Must be passed back when requesting subsequent pages. Only present if there are more pages of results to be shown.
 
    next_offset: integer
    The offset to use when requesting the next page of results. Only present if there IS a next page.Note that if your search query uses the EXPLODE keyword, the 'next_offset' is the only way to know which item to request next (comparing the 'results' size and 'offset' value on this page is not guaranteed to work).
 
    next: string
    The path to the next page of results (if there IS a next page).
  }
]

GET /data/partitions
Responses

Code

Description

Schema

200

successful operation

{
}

POST /data/import
Description

Imports data. Returns the import UUID.

Parameters

Name

Located in

Description

Default

Schema

body

body

Import records

import {
  source: string*
  Name of import source
 
  type: string*
  Type of import
 
  items: [
    Import items
 
     importItem {
      kind: string
      Optional data kind
 
      data: {
        Item data
      }*
    }
  ]*
 
  uuid: string
  UUID of import
 
  complete: boolean
  If false, more records for the import UUID are to follow
}

Responses

Code

Description

Schema

200

successful operation

string
ImportRecord UUID

POST /data/write
Description

Perform arbitrary write operations

Parameters

Name

Located in

Description

Default

Schema

body

body

Commands

[
   {
    cmd: string*
    Command to execute
  }
]

Responses

Code

Description

Schema

200

successful operation

[
   {
    cmd: string*
    Command that was executed
 
    code: integer*
    HTTP result code
 
    message: string
    Error message (for error codes)
  }
]


vault

Manage the credential vault

GET /vault
Responses

Code

Description

Schema

200

successful operation

vault {
  open: boolean*
  passphrase_set: boolean*
  passphrase_saved: boolean*
}

PATCH /vault
Parameters

Name

Located in

Description

Default

Schema

body

body

patchVault {
  open: boolean*
  passphrase: string
}

Responses

Code

Description

Schema

200

successful operation


credentials

Manage credentials

GET /vault/credential_types
Description

Get a list of all credential types and filter by group and/or category.

Parameters

Name

Located in

Description

Default

Schema

group

query

Filter credential types by group

string

category

query

Filter credential types by category

string

Responses

Code

Description

Schema

200

successful operation

[
   credentialType {
    name: string*
    label: string*
    description: string*
    groups: [
      string
    ]*
    categories: [
      string
    ]*
    uri: string*
  }
]

GET /vault/credential_types/{cred_type_name}
Parameters

Name

Located in

Description

Default

Schema

cred_type_name

path

Name of the credential type

string*

Responses

Code

Description

Schema

200

successful operation

credentialType {
  name: string*
  label: string*
  description: string*
  groups: [
    string
  ]*
  categories: [
    string
  ]*
  uri: string*
}

GET /vault/credentials
Responses

Code

Description

Schema

200

successful operation

[
   credential {
    A credential can be used for one or more types of access, with the 'types' field listing all the access types a credential applies to. See the /vault/credential_types endpoint for a list of types. The access types determine which fields from this object will be populated. Also, credentials used to access cloud providers may contain additional fields to those listed here. Look up your chosen cloud provider with the /discovery/cloud_metadata endpoint to see a list of fields.
 
    index: int64
    enabled: boolean
    username: string
    password: string
    label: string
    description: string
    ip_range: string
    ip_exclusion: string
    range_prefixes: [
      string
    ]
    types: [
      string
    ]*
    internal.valid: boolean
    internal.secondary: boolean
    internal.created: date-time
    internal.modified: date-time
    internal.messages: [
      string
    ]
    su.enabled: boolean
    su.username: string
    su.password: string
    shell.record: boolean
    shell.prompt: string
    shell.force_subshell: boolean
    vsphere.port: int64
    vsphere.timeout: int64
    vcenter.port: int64
    vcenter.timeout: int64
    windows.port: int64
    telnet.port: int64
    telnet.timeout: int64
    rlogin.port: int64
    rlogin.timeout: int64
    cimc.port: int64
    cimc.timeout: int64
    ribcl.port: int64
    ribcl.timeout: int64
    vplex.port: int64
    vplex.timeout: int64
    ssh.port: int64
    ssh.timeout: int64
    ssh.prefauth: [
      string
    ]
    ssh.key.set: boolean
    ssh.key.passphrase: string
    ssh.key.data: string
    snmp.port: int64
    snmp.timeout: int64
    snmp.version: string
    snmp.retries: int64
    snmp.getbulk: boolean
    snmp.community: string
    snmp.v3.privkey: string
    snmp.v3.authkey: string
    snmp.v3.privproto: string
    snmp.v3.securityname: string
    snmp.v3.context: string
    snmp.v3.authproto: string
    wbem.http.port: int64
    wbem.https.port: int64
    wbem.http.enabled: boolean
    wbem.https.enabled: boolean
    wbem.timeout: int64
    mainframe_agent.port: int64
    mainframe_agent.timeout: int64
    export.port: int64
    export.protocol: string
    export.path: string
    uuid: string
    uri: string
    web_basic.timeout: int64
    web_basic.http.enabled: boolean
    web_digest.timeout: int64
    web_digest.http.enabled: boolean
    web_oauth2.timeout: int64
    web_oauth2.token_endpoint: string
    web_oauth2.http.enabled: boolean
  }
]

POST /vault/credentials
Description

New in version 1.1 - added support for cloud credentials.

New in version 1.2 - added support for API credentials.

Parameters

Name

Located in

Description

Default

Schema

body

body

Credential to be added. Note that a default label is generated if no label is provided.

credentialInput {
  A credential can be used for one or more types of access, with the 'types' field listing all the access types a credential applies to. See the /vault/credential_types endpoint for a list of types. Different access types require different fields from this object to be populated when creating or updating a credential. Also, credentials used to access cloud providers may require additional fields to those listed here. Look up your chosen cloud provider with the /discovery/cloud_metadata endpoint to see a list of fields.
 
  index: int64
  enabled: boolean
  username: string
  password: string
  label: string
  description: string
  ip_range: string
  ip_exclusion: string
  range_prefixes: [
    string
  ]
  types: [
    string
  ]
  su.enabled: boolean
  su.username: string
  su.password: string
  shell.record: boolean
  shell.prompt: string
  shell.force_subshell: boolean
  vsphere.port: int64
  vsphere.timeout: int64
  vcenter.port: int64
  vcenter.timeout: int64
  windows.port: int64
  telnet.port: int64
  telnet.timeout: int64
  rlogin.port: int64
  rlogin.timeout: int64
  cimc.port: int64
  cimc.timeout: int64
  ribcl.port: int64
  ribcl.timeout: int64
  vplex.port: int64
  vplex.timeout: int64
  ssh.port: int64
  ssh.timeout: int64
  ssh.prefauth: [
    string
  ]
  ssh.key.set: boolean
  ssh.key.passphrase: string
  ssh.key.data: string
  snmp.port: int64
  snmp.timeout: int64
  snmp.version: string
  snmp.retries: int64
  snmp.getbulk: boolean
  snmp.community: string
  snmp.v3.privkey: string
  snmp.v3.authkey: string
  snmp.v3.privproto: string
  snmp.v3.securityname: string
  snmp.v3.context: string
  snmp.v3.authproto: string
  wbem.http.port: int64
  wbem.https.port: int64
  wbem.http.enabled: boolean
  wbem.https.enabled: boolean
  wbem.timeout: int64
  mainframe_agent.port: int64
  mainframe_agent.timeout: int64
  export.port: int64
  export.protocol: string
  export.path: string
  web_basic.timeout: int64
  web_basic.http.enabled: boolean
  web_digest.timeout: int64
  web_digest.http.enabled: boolean
  web_oauth2.timeout: int64
  web_oauth2.token_endpoint: string
  web_oauth2.http.enabled: boolean
}

Responses

Code

Description

Schema

200

successful operation

{
  uuid: string*
  uri: string*
}

GET /vault/credentials/{cred_id}
Parameters

Name

Located in

Description

Default

Schema

cred_id

path

ID of the credential

string*

Responses

Code

Description

Schema

200

successful operation

credential {
  A credential can be used for one or more types of access, with the 'types' field listing all the access types a credential applies to. See the /vault/credential_types endpoint for a list of types. The access types determine which fields from this object will be populated. Also, credentials used to access cloud providers may contain additional fields to those listed here. Look up your chosen cloud provider with the /discovery/cloud_metadata endpoint to see a list of fields.
 
  index: int64
  enabled: boolean
  username: string
  password: string
  label: string
  description: string
  ip_range: string
  ip_exclusion: string
  range_prefixes: [
    string
  ]
  types: [
    string
  ]*
  internal.valid: boolean
  internal.secondary: boolean
  internal.created: date-time
  internal.modified: date-time
  internal.messages: [
    string
  ]
  su.enabled: boolean
  su.username: string
  su.password: string
  shell.record: boolean
  shell.prompt: string
  shell.force_subshell: boolean
  vsphere.port: int64
  vsphere.timeout: int64
  vcenter.port: int64
  vcenter.timeout: int64
  windows.port: int64
  telnet.port: int64
  telnet.timeout: int64
  rlogin.port: int64
  rlogin.timeout: int64
  cimc.port: int64
  cimc.timeout: int64
  ribcl.port: int64
  ribcl.timeout: int64
  vplex.port: int64
  vplex.timeout: int64
  ssh.port: int64
  ssh.timeout: int64
  ssh.prefauth: [
    string
  ]
  ssh.key.set: boolean
  ssh.key.passphrase: string
  ssh.key.data: string
  snmp.port: int64
  snmp.timeout: int64
  snmp.version: string
  snmp.retries: int64
  snmp.getbulk: boolean
  snmp.community: string
  snmp.v3.privkey: string
  snmp.v3.authkey: string
  snmp.v3.privproto: string
  snmp.v3.securityname: string
  snmp.v3.context: string
  snmp.v3.authproto: string
  wbem.http.port: int64
  wbem.https.port: int64
  wbem.http.enabled: boolean
  wbem.https.enabled: boolean
  wbem.timeout: int64
  mainframe_agent.port: int64
  mainframe_agent.timeout: int64
  export.port: int64
  export.protocol: string
  export.path: string
  uuid: string
  uri: string
  web_basic.timeout: int64
  web_basic.http.enabled: boolean
  web_digest.timeout: int64
  web_digest.http.enabled: boolean
  web_oauth2.timeout: int64
  web_oauth2.token_endpoint: string
  web_oauth2.http.enabled: boolean
}

PUT /vault/credentials/{cred_id}
Description

Replaces a single credential. All required credential properties must be present. Optional properties that are missing will be reset to their defaults.

Parameters

Name

Located in

Description

Default

Schema

cred_id

path

ID of the credential

string*

body

body

Credential properties

credentialInput {
  A credential can be used for one or more types of access, with the 'types' field listing all the access types a credential applies to. See the /vault/credential_types endpoint for a list of types. Different access types require different fields from this object to be populated when creating or updating a credential. Also, credentials used to access cloud providers may require additional fields to those listed here. Look up your chosen cloud provider with the /discovery/cloud_metadata endpoint to see a list of fields.
 
  index: int64
  enabled: boolean
  username: string
  password: string
  label: string
  description: string
  ip_range: string
  ip_exclusion: string
  range_prefixes: [
    string
  ]
  types: [
    string
  ]
  su.enabled: boolean
  su.username: string
  su.password: string
  shell.record: boolean
  shell.prompt: string
  shell.force_subshell: boolean
  vsphere.port: int64
  vsphere.timeout: int64
  vcenter.port: int64
  vcenter.timeout: int64
  windows.port: int64
  telnet.port: int64
  telnet.timeout: int64
  rlogin.port: int64
  rlogin.timeout: int64
  cimc.port: int64
  cimc.timeout: int64
  ribcl.port: int64
  ribcl.timeout: int64
  vplex.port: int64
  vplex.timeout: int64
  ssh.port: int64
  ssh.timeout: int64
  ssh.prefauth: [
    string
  ]
  ssh.key.set: boolean
  ssh.key.passphrase: string
  ssh.key.data: string
  snmp.port: int64
  snmp.timeout: int64
  snmp.version: string
  snmp.retries: int64
  snmp.getbulk: boolean
  snmp.community: string
  snmp.v3.privkey: string
  snmp.v3.authkey: string
  snmp.v3.privproto: string
  snmp.v3.securityname: string
  snmp.v3.context: string
  snmp.v3.authproto: string
  wbem.http.port: int64
  wbem.https.port: int64
  wbem.http.enabled: boolean
  wbem.https.enabled: boolean
  wbem.timeout: int64
  mainframe_agent.port: int64
  mainframe_agent.timeout: int64
  export.port: int64
  export.protocol: string
  export.path: string
  web_basic.timeout: int64
  web_basic.http.enabled: boolean
  web_digest.timeout: int64
  web_digest.http.enabled: boolean
  web_oauth2.timeout: int64
  web_oauth2.token_endpoint: string
  web_oauth2.http.enabled: boolean
}

Responses

Code

Description

Schema

200

successful operation

PATCH /vault/credentials/{cred_id}
Description

Updates partial resources of a credential. Missing properties are left unchanged.

New in version 1.1 - added support for cloud credentials.

New in version 1.2 - added support for API credentials.

Parameters

Name

Located in

Description

Default

Schema

cred_id

path

ID of the credential

string*

body

body

Credential properties

credentialInput {
  A credential can be used for one or more types of access, with the 'types' field listing all the access types a credential applies to. See the /vault/credential_types endpoint for a list of types. Different access types require different fields from this object to be populated when creating or updating a credential. Also, credentials used to access cloud providers may require additional fields to those listed here. Look up your chosen cloud provider with the /discovery/cloud_metadata endpoint to see a list of fields.
 
  index: int64
  enabled: boolean
  username: string
  password: string
  label: string
  description: string
  ip_range: string
  ip_exclusion: string
  range_prefixes: [
    string
  ]
  types: [
    string
  ]
  su.enabled: boolean
  su.username: string
  su.password: string
  shell.record: boolean
  shell.prompt: string
  shell.force_subshell: boolean
  vsphere.port: int64
  vsphere.timeout: int64
  vcenter.port: int64
  vcenter.timeout: int64
  windows.port: int64
  telnet.port: int64
  telnet.timeout: int64
  rlogin.port: int64
  rlogin.timeout: int64
  cimc.port: int64
  cimc.timeout: int64
  ribcl.port: int64
  ribcl.timeout: int64
  vplex.port: int64
  vplex.timeout: int64
  ssh.port: int64
  ssh.timeout: int64
  ssh.prefauth: [
    string
  ]
  ssh.key.set: boolean
  ssh.key.passphrase: string
  ssh.key.data: string
  snmp.port: int64
  snmp.timeout: int64
  snmp.version: string
  snmp.retries: int64
  snmp.getbulk: boolean
  snmp.community: string
  snmp.v3.privkey: string
  snmp.v3.authkey: string
  snmp.v3.privproto: string
  snmp.v3.securityname: string
  snmp.v3.context: string
  snmp.v3.authproto: string
  wbem.http.port: int64
  wbem.https.port: int64
  wbem.http.enabled: boolean
  wbem.https.enabled: boolean
  wbem.timeout: int64
  mainframe_agent.port: int64
  mainframe_agent.timeout: int64
  export.port: int64
  export.protocol: string
  export.path: string
  web_basic.timeout: int64
  web_basic.http.enabled: boolean
  web_digest.timeout: int64
  web_digest.http.enabled: boolean
  web_oauth2.timeout: int64
  web_oauth2.token_endpoint: string
  web_oauth2.http.enabled: boolean
}

Responses

Code

Description

Schema

200

successful operation

DELETE /vault/credentials/{cred_id}
Description

Deletes a specific credential.

Parameters

Name

Located in

Description

Default

Schema

cred_id

path

ID of the credential

string*

Responses

Code

Description

Schema

200

successful operation


knowledge

Upload new TKUs and pattern modules

GET /knowledge
Description

Get the current state of the appliance's knowledge, including TKU versions.

New in version 1.1 - includes installed versions of the Devices and Product Content packages.

Responses

Code

Description

Schema

200

successful operation

knowledgeState {
  Info on appliance knowledge. The fields latest_edp, latest_storage, latest_tku and upload_list may have null values if the knowledge type is not present in the system.
 
  devices: string*
  Version of the Devices package installed
 
  latest_edp: knowledgeUpload {
    Details on a knowledge upload.
 
    active_count: int64
    inactive_count: int64
    modified: boolean
    name: string
    origin: string
    package: string
    submission_date: date-time
    superseded_count: int64
    upload_id: string
  }
 
  latest_storage: knowledgeUpload {
    Details on a knowledge upload.
 
    active_count: int64
    inactive_count: int64
    modified: boolean
    name: string
    origin: string
    package: string
    submission_date: date-time
    superseded_count: int64
    upload_id: string
  }
 
  latest_tku: knowledgeUpload {
    Details on a knowledge upload.
 
    active_count: int64
    inactive_count: int64
    modified: boolean
    name: string
    origin: string
    package: string
    submission_date: date-time
    superseded_count: int64
    upload_id: string
  }
 
  product_content: string*
  Version of the Product Content package installed
 
  tpl_version: [
    A list of two version numbers - major, minor
 
    int64
  ]*
 
  upload_list: [
    List of all previous appliance uploads.
 
     knowledgeUpload {
      Details on a knowledge upload.
 
      active_count: int64
      inactive_count: int64
      modified: boolean
      name: string
      origin: string
      package: string
      submission_date: date-time
      superseded_count: int64
      upload_id: string
    }
  ]*
}

POST /knowledge/{filename}
Description

Upload a TKU or pattern module to the appliance. The body of the request should contain the knowledge upload file either as binary data or in multipart/form-data format (according to RFC 2388).

After calling this endpoint, use GET /knowledge/status to see progress of the upload.

From BMC Discovery 11.1 patch 3, the REST API supports uploading individual TPL files.

On versions of BMC Discovery prior to 11.1 patch 5, set the 'Content-Type' header to 'application/octet-stream' if uploading as binary data.

Parameters

Name

Located in

Description

Default

Schema

filename

path

Filename of the upload, for reporting purposes. Must have one of these extensions: .tpl, .zip, .drpm, .hrd

string*

activate

query

Flag if patterns should be activated after upload

true

boolean

allow_restart

query

Flag if services may be restarted in order to update Network Devices or Product Content. If this is false, but a restart IS required, the upload will not be performed. This case can be detected by checking the optional field 'restart_required' in the body of the error response
New in version 1.1

false

boolean

file

formData

File to upload

file*

Responses

Code

Description

Schema

200

successful operation

400

invalid upload

500

server side error

503

another upload is in progress

GET /knowledge/status
Description

Get the current state of a knowledge upload.

Responses

Code

Description

Schema

200

successful operation

{
  uploading: boolean*
  Whether a knowledge upload is in progress or not
 
  processing: boolean*
  Whether any sort of knowledge activity (including an upload) is in progress
 
  last_result: string*
  The result of the last knowledge upload - either 'success' or 'failure'. Empty if there have not been any uploads, or an upload is still in progress
 
  messages: [
    Progress and information messages reported by the last knowledge upload to run, or the one in progress
 
    string
  ]*
 
  error: string*
  Any errors reported by the last knowledge upload to run, or the one in progress
}


events

Push events

POST /events
Description

Returns a unique ID if the event has been recorded, otherwise an empty string is returned e.g. if the event source has been disabled.

Parameters

Name

Located in

Description

Default

Schema

body

body

event {
  source: string*
  Name of an event source which has been defined in the system
 
  type: string*
  params: {
    Parameters of the event depending on the event type
  }
}

Responses

Code

Description

Schema

200

successful operation

string
Event ID


admin

Manage the BMC Discovery appliance

GET /admin/baseline
Description

Get a summary of the appliance status, and details of which baseline checks have passed or failed.

New in version 1.1

Responses

Code

Description

Schema

200

successful operation

baselineStatus {
  summary: baselineSummary {
    last_ok: boolean*
    Whether the last baseline check contained any failures or not
 
    last_message: string*
    Summary message from the last baseline check
 
    last_checked: date-time
    Time the baseline was last checked
  }
  results: baselineResults {
    PASSED: [
      Checks which passed the last baseline run
 
       baselineCheckResult {
        name: string*
        The name of this check
 
        severity: string*
        How important this check is
        Enum: [
          "INFO",
          "MINOR",
          "MAJOR",
          "CRITICAL"
        ]
 
        enabled: boolean*
        Whether this check will be included in the next baseline run
 
        message: string*
        A message describing the status of this check
 
        details: [
          Detailed results of the individual components of this check
 
           baselineCheckDetail {
            status: string*
            Last result of running this component of a baseline check
            Enum: [
              "PASSED",
              "FAILED",
              "NOT_RUN"
            ]
 
            messages: [
              Messages generated from the last run of this component
 
              string
            ]*
 
            machine_name: string
            The BMC Discovery cluster member that this component of the check was run on. Only present if the appliance is clustered and this component is run once per cluster member.
          }
        ]
      }
    ]*
 
    FAILED: [
      Checks which failed the last baseline run
 
       baselineCheckResult {
        name: string*
        The name of this check
 
        severity: string*
        How important this check is
        Enum: [
          "INFO",
          "MINOR",
          "MAJOR",
          "CRITICAL"
        ]
 
        enabled: boolean*
        Whether this check will be included in the next baseline run
 
        message: string*
        A message describing the status of this check
 
        details: [
          Detailed results of the individual components of this check
 
           baselineCheckDetail {
            status: string*
            Last result of running this component of a baseline check
            Enum: [
              "PASSED",
              "FAILED",
              "NOT_RUN"
            ]
 
            messages: [
              Messages generated from the last run of this component
 
              string
            ]*
 
            machine_name: string
            The BMC Discovery cluster member that this component of the check was run on. Only present if the appliance is clustered and this component is run once per cluster member.
          }
        ]
      }
    ]*
 
    NOT_RUN: [
      Checks currently disabled from baseline runs
 
       baselineCheckResult {
        name: string*
        The name of this check
 
        severity: string*
        How important this check is
        Enum: [
          "INFO",
          "MINOR",
          "MAJOR",
          "CRITICAL"
        ]
 
        enabled: boolean*
        Whether this check will be included in the next baseline run
 
        message: string*
        A message describing the status of this check
 
        details: [
          Detailed results of the individual components of this check
 
           baselineCheckDetail {
            status: string*
            Last result of running this component of a baseline check
            Enum: [
              "PASSED",
              "FAILED",
              "NOT_RUN"
            ]
 
            messages: [
              Messages generated from the last run of this component
 
              string
            ]*
 
            machine_name: string
            The BMC Discovery cluster member that this component of the check was run on. Only present if the appliance is clustered and this component is run once per cluster member.
          }
        ]
      }
    ]*
  }
}


GET /admin/about
Description

Get information about the appliance, like its version and versions of the installed packages.

New in version 1.1

Responses

Code

Description

Schema

200

successful operation

about {
  versions: aboutVersions {
    devices: string*
    Version of the Devices package installed
 
    os_updates: string*
    Version of the OS Updates package installed
 
    product: string*
    Version of BMC Discovery
 
    product_content: string*
    Version of the Product Content package installed
  }
}


GET /admin/licensing
Description

New in version 1.1

Responses

Code

Description

Schema

200

successful operation

file

GET /admin/licensing/csv
Description

Download raw license data in CSV format as a zip file for offline analysis.

New in version 1.1

Responses

Code

Description

Schema

200

successful operation

file

GET /admin/licensing/raw
Description

Download the encrypted raw license data on this appliance for import on another appliance.

New in version 1.1

Responses

Code

Description

Schema

200

successful operation

file


topology

Retrieve topology data from the datastore

GET /data/nodes/{node_id}/graph
Description

Graph data represents a set of nodes and relationships that are associated to the given node. If the node is of ModelDefinition kind, the graph data is obtained from the model's contents rather than running the generic graph traversal function.

Parameters

Name

Located in

Description

Default

Schema

node_id

path

ID of node for which the graph data is generated

string*

focus

query

Context used for determining how the graph should be traversed. Must be one of:

  • 'software-connected': focuses on software and communication between items of software.
  • 'software': focuses on software and communication between items of software that are in the same host.
  • 'infrastructure': focuses on the connectivity to network and storage components.
    Applicable only to node kinds that are not ModelDefinition.

"software-connected"

string
Enum: [
  "software-connected",
  "software",
  "infrastructure"
]

apply_rules

query

Whether to apply global rules - which is a set of pre-defined constraints to prevent traversing to too many nodes - while obtaining the graph data.
Applicable only to node kinds that are not ModelDefinition.

true

boolean

complete

query

Whether to return the complete set of node and relationship attributes when obtaining the graph data.

false

boolean

Responses

Code

Description

Schema

200

successful operation

nodeGraphResults {
  nodes: [
    List of node data involved in the graph data
 
     {
      id: string*
      ID of the node
 
      kind: string*
      Kind of the node
 
      name: string*
      Name of the node
 
      short_name: string*
      Shortened name of the node
    }
  ]*
 
  links: [
    List of relationships involved in the graph data
 
     {
      rel_id: string*
      ID of the relationship
 
      kind: string*
      Kind of the relationship
 
      src_id: string*
      ID of the source node
 
      tgt_id: string*
      ID of the target node
    }
  ]*
}

POST /topology/nodes
Description

Get topology data from one or more starting nodes

Parameters

Name

Located in

Description

Default

Schema

body

body

topologyNodesQuery {
  node_ids: [
    A list of node IDs. Requests must have either the node_ids parameter or the search_query parameter.
 
    string
  ]
 
  search_query: string
  A search query to run. Requests must have either the node_ids parameter or the search_query parameter.
 
  focuses: [
    List of one or more focuses to use for determining how the graph should be traversed when obtaining topology data.
 
    string
  ]
 
  extra_rules: [
    Extra rules used to determine whether or not a particular node should be included or excluded when conducting a traversal.
 
     {
    }
  ]
 
  show_rules: boolean
  Whether or not to show the rules used in the topology retrieval in the response.
 
  explode_groups: [
    "Explode" some or all groups - returns full data for all members in the specified groups, unconditionally. This should either be a list of string group IDs or the string 'all'.
 
    string
  ]
 
  shared_overrides: {
    Overrides to shared nodes.
  }
 
  grouping: string
  Controls automated grouping style. Currently only applied if the context is software-connected.
  Enum: [
    "aggressive",
    "simple",
    "rootlocal",
    "root",
    "nevergroup"
  ]
 
  max_depth: integer
  Maximum depth to traverse from root nodes during topology retrieval.
 
  expanding_group: boolean
  Whether or not the request has been made because we are expanding a previously grouped set of results from previously retrieved topology data.
 
  show_suppressed: boolean
  Whether or not to show in the response the list of node IDs that have been suppressed from the results by exclusion rules or due to shared evaluation.
 
  attributes: [
    If specified, only these attributes will be retrieved for all nodes in the results. Otherwise a default set will be used.
 
    string
  ]
 
  at_time: date-time
  The time in the past for which to retrieve topology data.
 
  annotate_cycles: boolean
  Whether or not to annotate relationships that lead to cycles in the returned topology data.
}

Responses

Code

Description

Schema

200

successful operation

topologyNodesResults {
  links: [
    List of relationships involved in the graph data
 
     {
      rel_id: string*
      ID of the relationship
 
      kind: string*
      Kind of the relationship
 
      src_id: string*
      ID of the source node
 
      tgt_id: string*
      ID of the target node
    }
  ]*
 
  nodes: [
    List of node data involved in the graph data
 
     {
    }
  ]*
}

POST /topology/nodes/kinds
Description

Get nodes of the specified kinds which are related to a given set of nodes

Parameters

Name

Located in

Description

Default

Schema

body

body

topologyNodesKindsQuery {
  node_ids: [
    A list of node IDs. Requests must have either the node_ids parameter or the search_query parameter.
 
    string
  ]
 
  search_query: string
  A search query to run. Requests must have either the node_ids parameter or the search_query parameter.
 
  node_kinds: [
    List of node kinds
 
    string
  ]
}

Responses

Code

Description

Schema

200

successful operation

[
   nodeResults {
    destroyed: boolean*
    Whether the node is destroyed or not
 
    kind: string*
    The kind of the node
 
    modified: date-time*
    The last modified time of the node
 
    state: {
      The full state of the node, containing all attribute names and values
    }*
  }
]

GET /topology/visualization_state
Description

Get the current state of the visualization for the authenticated user.

Responses

Code

Description

Schema

200

successful operation

visualizationStateResponse {
  enabled: boolean*
  show_big: boolean*
  show_labels: boolean*
  small_x: integer*
  small_y: integer*
  layout: integer*
  surround_type: string*
  impact_direction: string*
  context: integer*
}

PATCH /topology/visualization_state
Description

Update one or more attributes of the current state of the visualization for the authenticated user.

Parameters

Name

Located in

Description

Default

Schema

body

body

visualizationStateRequest {
  enabled: boolean
  show_big: boolean
  show_labels: boolean
  small_x: integer
  small_y: integer
  layout: integer
  surround_type: string
  impact_direction: string
  context: integer
}

Responses

Code

Description

Schema

200

successful operation

visualizationStateResponse {
  enabled: boolean*
  show_big: boolean*
  show_labels: boolean*
  small_x: integer*
  small_y: integer*
  layout: integer*
  surround_type: string*
  impact_direction: string*
  context: integer*
}

PUT /topology/visualization_state
Description

Update any or all of the attributes of the current state of the visualization for the authenticated user.

Parameters

Name

Located in

Description

Default

Schema

body

body

visualizationStatePutRequest {
  enabled: boolean*
  show_big: boolean*
  show_labels: boolean*
  small_x: integer*
  small_y: integer*
  layout: integer*
  surround_type: string*
  impact_direction: string*
  context: integer*
}

Responses

Code

Description

Schema

200

successful operation

visualizationStateResponse {
  enabled: boolean*
  show_big: boolean*
  show_labels: boolean*
  small_x: integer*
  small_y: integer*
  layout: integer*
  surround_type: string*
  impact_direction: string*
  context: integer*
}


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

Comments