This documentation relates to the latest released version of BMC Discovery.
See the information on this topic for versions 11.2 or 11.1.

This version of BMC Discovery supports versions 1.1 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/api/v1.1

discovery

Control scanning and view results

GET /discovery
 Discovery status
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
 Change the status of the discovery process
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/cloud_metadata
 Get metadata for supported cloud providers
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
 Currently processing 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 a Cloud scan, the 'scan_params' field will also be populated
    Enum: [
      "IP",
      "Cloud"
    ]
 
    range_prefix: string
    Distinguish overlapping address spaces
 
    scan_level: string*
    Scan level
 
    scan_params: {
      Used for Cloud scans only. The 'provider' field contains the name of the cloud provider being scanned. Each provider also supports a different set of additional fields. Look up the cloud provider with the /discovery/cloud_metadata endpoint to see which fields to expect here
 
      provider: string*
      Name of the 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 attribute is omitted, the system default controls whether to ping or not.
    }
 
    scan_type: string*
    Type of scan
 
    scanning: int64
    Number of addresses being scanned
 
    pre_scanning: int64
    Number of addresses being pre-scanned
 
    starttime: datetime*
    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
 Add new run
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.

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"
  ]
 
  range_prefix: 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 Cloud scans only. Populate the 'provider' field with the name of the 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 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 attribute is omitted, the system default controls whether to ping or not.
  }
}

Responses

Code

Description

Schema

200

successful operation

{
  uuid: string*
  uri: string*
}

GET /discovery/runs/{run_id}
 Get details of a specific discovery run
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 a Cloud scan, the 'scan_params' field will also be populated
  Enum: [
    "IP",
    "Cloud"
  ]
 
  range_prefix: string
  Distinguish overlapping address spaces
 
  scan_level: string*
  Scan level
 
  scan_params: {
    Used for Cloud scans only. The 'provider' field contains the name of the cloud provider being scanned. Each provider also supports a different set of additional fields. Look up the cloud provider with the /discovery/cloud_metadata endpoint to see which fields to expect here
 
    provider: string*
    Name of the 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 attribute is omitted, the system default controls whether to ping or not.
  }
 
  scan_type: string*
  Type of scan
 
  scanning: int64
  Number of addresses being scanned
 
  pre_scanning: int64
  Number of addresses being pre-scanned
 
  starttime: datetime*
  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}
 Update the state of a specific discovery run
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
 Get all results of a discovery run
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}
 Get results of a discovery run for a specific 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
 
         {
          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
 Get results of a discovery run for a specific result type
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
 Get all devices inferred by a discovery run
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}
 Get inferred devices by 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
 
         {
          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
 Get inferred devices by kind
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

Retrieve data from the model

GET /data/search
 Search the data
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
 
         {
          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
 Search the data
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
 
         {
          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
 Search the data
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
 Search the data
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/nodes/{node_id}
 Find a single node
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: datetime*
  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
 Find a single node and its relationships
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: datetime*
  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}
 Find a single node and nodes related to it
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: datetime*
  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}/graph
 Get the graph data of a node
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

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}
 Find nodes by 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*

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
 
         {
          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
 Find nodes by kind
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*

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).
  }
]


vault

Manage the credential vault

GET /vault
 Get details of the state of the vault
Responses

Code

Description

Schema

200

successful operation

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

PATCH /vault
 Change the state of the 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
 Get a list of all 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}
 Get the properties of a specific credential type
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
 Get a list of all 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
    password.cyberark: string
    label: string
    description: string
    ip_range: string
    ip_exclusion: string
    range_prefixes: [
      string
    ]
    types: [
      string
    ]*
    internal.valid: boolean
    internal.secondary: boolean
    internal.created: datetime
    internal.modified: datetime
    internal.messages: [
      string
    ]
    dip.required: [
      string
    ]
    dip.ip.name: string
    dip.ip.dynamic: boolean
    dip.fields: [
      string
    ]
    dip.match.endpoint: string
    dip.provider.type: string
    su.enabled: boolean
    su.username: string
    su.password: string
    su.password.cyberark: 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
    ssh.key.passphrase.cyberark: string
    ssh.key.data.cyberark: string
    snmp.port: int64
    snmp.timeout: int64
    snmp.version: string
    snmp.retries: int64
    snmp.getbulk: boolean
    snmp.community: string
    snmp.community.cyberark: string
    snmp.v3.privkey: string
    snmp.v3.authkey: string
    snmp.v3.privkey.cyberark: string
    snmp.v3.authkey.cyberark: 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
    mainview.port: int64
    mainview.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
 Create a new credential
Description

New in version 1.1 - added support for cloud 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
  password.cyberark: string
  label: string
  description: string
  ip_range: string
  ip_exclusion: string
  range_prefixes: [
    string
  ]
  types: [
    string
  ]
  dip.required: [
    string
  ]
  dip.ip.name: string
  dip.ip.dynamic: boolean
  dip.fields: [
    string
  ]
  dip.match.endpoint: string
  dip.provider.type: string
  su.enabled: boolean
  su.username: string
  su.password: string
  su.password.cyberark: 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
  ssh.key.passphrase.cyberark: string
  ssh.key.data.cyberark: string
  snmp.port: int64
  snmp.timeout: int64
  snmp.version: string
  snmp.retries: int64
  snmp.getbulk: boolean
  snmp.community: string
  snmp.community.cyberark: string
  snmp.v3.privkey: string
  snmp.v3.authkey: string
  snmp.v3.privkey.cyberark: string
  snmp.v3.authkey.cyberark: 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
  mainview.port: int64
  mainview.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}
 Get the properties of 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

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
  password.cyberark: string
  label: string
  description: string
  ip_range: string
  ip_exclusion: string
  range_prefixes: [
    string
  ]
  types: [
    string
  ]*
  internal.valid: boolean
  internal.secondary: boolean
  internal.created: datetime
  internal.modified: datetime
  internal.messages: [
    string
  ]
  dip.required: [
    string
  ]
  dip.ip.name: string
  dip.ip.dynamic: boolean
  dip.fields: [
    string
  ]
  dip.match.endpoint: string
  dip.provider.type: string
  su.enabled: boolean
  su.username: string
  su.password: string
  su.password.cyberark: 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
  ssh.key.passphrase.cyberark: string
  ssh.key.data.cyberark: string
  snmp.port: int64
  snmp.timeout: int64
  snmp.version: string
  snmp.retries: int64
  snmp.getbulk: boolean
  snmp.community: string
  snmp.community.cyberark: string
  snmp.v3.privkey: string
  snmp.v3.authkey: string
  snmp.v3.privkey.cyberark: string
  snmp.v3.authkey.cyberark: 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
  mainview.port: int64
  mainview.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}
 Replace a credential
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
  password.cyberark: string
  label: string
  description: string
  ip_range: string
  ip_exclusion: string
  range_prefixes: [
    string
  ]
  types: [
    string
  ]
  dip.required: [
    string
  ]
  dip.ip.name: string
  dip.ip.dynamic: boolean
  dip.fields: [
    string
  ]
  dip.match.endpoint: string
  dip.provider.type: string
  su.enabled: boolean
  su.username: string
  su.password: string
  su.password.cyberark: 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
  ssh.key.passphrase.cyberark: string
  ssh.key.data.cyberark: string
  snmp.port: int64
  snmp.timeout: int64
  snmp.version: string
  snmp.retries: int64
  snmp.getbulk: boolean
  snmp.community: string
  snmp.community.cyberark: string
  snmp.v3.privkey: string
  snmp.v3.authkey: string
  snmp.v3.privkey.cyberark: string
  snmp.v3.authkey.cyberark: 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
  mainview.port: int64
  mainview.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}
 Patch a credential
Description

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

New in version 1.1 - added support for cloud 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
  password.cyberark: string
  label: string
  description: string
  ip_range: string
  ip_exclusion: string
  range_prefixes: [
    string
  ]
  types: [
    string
  ]
  dip.required: [
    string
  ]
  dip.ip.name: string
  dip.ip.dynamic: boolean
  dip.fields: [
    string
  ]
  dip.match.endpoint: string
  dip.provider.type: string
  su.enabled: boolean
  su.username: string
  su.password: string
  su.password.cyberark: 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
  ssh.key.passphrase.cyberark: string
  ssh.key.data.cyberark: string
  snmp.port: int64
  snmp.timeout: int64
  snmp.version: string
  snmp.retries: int64
  snmp.getbulk: boolean
  snmp.community: string
  snmp.community.cyberark: string
  snmp.v3.privkey: string
  snmp.v3.authkey: string
  snmp.v3.privkey.cyberark: string
  snmp.v3.authkey.cyberark: 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
  mainview.port: int64
  mainview.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}
 Delete a credential
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
 Info on appliance 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: datetime
    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: datetime
    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: datetime
    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: datetime
      superseded_count: int64
      upload_id: string
    }
  ]*
}

POST /knowledge/{filename}
 Upload knowledge to the appliance
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
 Info on knowledge uploads
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
 Push an event to BMC Discovery.
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
 Get the current status of the BMC Discovery appliance 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: datetime
    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
 Get basic information about the appliance
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
 Get the latest signed licensing report in plain text
Description

New in version 1.1

Responses

Code

Description

Schema

200

successful operation

file

GET /admin/licensing/csv
 Get (anonymized) license data in csv format as a zip file
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
 Get encrypted raw license data as a zip file
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


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

2 Comments

  1.  

    1.  

© Copyright 2004 - 2019 BMC Software, Inc.
Legal notices