Endpoints in the REST API

This version of BMC Discovery supports versions 1.4 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.4

Related topics

Importing data into the system - POST /data/import

Writing and modifying data in the system - POST /data/write

admin

Manage the BMC Discovery appliance

{{status subtle="false" colour="Blue" title="GET"/}}

 /admin/baseline
Click here to expand...
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.
         }
       ]
     }
   ]*
 }
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /admin/about
Click here to expand...
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
 }
}


{{status subtle="false" colour="Blue" title="GET"/}}

 /admin/licensing
Click here to expand...
Description
New in version 1.1
Responses

Code

Description

Schema

200

successful operation

file

{{status subtle="false" colour="Blue" title="GET"/}}

 /admin/licensing/csv
Click here to expand...
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

{{status subtle="false" colour="Blue" title="GET"/}}

 /admin/licensing/raw
Click here to expand...
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


credentials

Manage credentials

{{status subtle="false" colour="Blue" title="GET"/}}

 /vault/credential_types
Click here to expand...
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*
 }
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /vault/credential_types/{cred_type_name}
Click here to expand...
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*
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /vault/credentials
Click here to expand...
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
   scopes: [
     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
   kerberos.realm: 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
   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
 }
]

{{status subtle="false" colour="Green" title="POST"/}}

 /vault/credentials
Click here to expand...
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
 scopes: [
   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
 kerberos.realm: 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
 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*
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /vault/credentials/{cred_id}
Click here to expand...
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
 scopes: [
   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
 kerberos.realm: 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
 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
}

{{status subtle="false" colour="Yellow" title="PUT"/}}

 /vault/credentials/{cred_id}
Click here to expand...
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
 scopes: [
   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
 kerberos.realm: 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
 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


{{status subtle="false" colour="Yellow" title="PATCH"/}}

 /vault/credentials/{cred_id}
Click here to expand...
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
 scopes: [
   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
 kerberos.realm: 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
 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


{{status subtle="false" colour="Red" title="DELETE"/}}

 /vault/credentials/{cred_id}
Click here to expand...
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


data

Read and import data

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/search
Click here to expand...
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).
 }
]

{{status subtle="false" colour="Green" title="POST"/}}

 /data/search
Click here to expand...
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).
 }
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/search?format=object
Click here to expand...
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).
 }
]

{{status subtle="false" colour="Green" title="POST"/}}

 /data/search?format=object
Click here to expand...
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).
 }
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/search?format=tree
Click here to expand...
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).
 }
]

{{status subtle="false" colour="Green" title="POST"/}}

 /data/search?format=tree
Click here to expand...
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).
 }
]

{{status subtle="false" colour="Green" title="POST"/}}

 /data/condition
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

offset

query


0

integer

limit

query


100

integer

results_id

query



string

delete

query



boolean

body

body



searchConditions {
 conditions: [
    conditionGraphObject {
     type: string*
     Type of condition object: 'node' or 'rel'

     label: string
     Label of this condition object

     kind: string
     Node/relationship kind

     condition: {
       Expression to match
     }

     show: [
       Values to show in search results

        {
       }
     ]

     order_by: {
       Ordering expression
     }
   }
 ]
 label: string*
 The label from the conditions around which the search is centered

 parameters: {
   Parameter values to use in the condition
 }
}

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

{{status subtle="false" colour="Green" title="POST"/}}

 /data/condition?format=object
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

offset

query


0

integer

limit

query


100

integer

results_id

query



string

delete

query



boolean

body

body



searchConditions {
 conditions: [
    conditionGraphObject {
     type: string*
     Type of condition object: 'node' or 'rel'

     label: string
     Label of this condition object

     kind: string
     Node/relationship kind

     condition: {
       Expression to match
     }

     show: [
       Values to show in search results

        {
       }
     ]

     order_by: {
       Ordering expression
     }
   }
 ]
 label: string*
 The label from the conditions around which the search is centered

 parameters: {
   Parameter values to use in the condition
 }
}

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


{{status subtle="false" colour="Green" title="POST"/}}

 /data/condition?format=tree
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

offset

query


0

integer

limit

query


100

integer

results_id

query



string

delete

query



boolean

body

body



searchConditions {
 conditions: [
    conditionGraphObject {
     type: string*
     Type of condition object: 'node' or 'rel'

     label: string
     Label of this condition object

     kind: string
     Node/relationship kind

     condition: {
       Expression to match
     }

     show: [
       Values to show in search results

        {
       }
     ]

     order_by: {
       Ordering expression
     }
   }
 ]
 label: string*
 The label from the conditions around which the search is centered

 parameters: {
   Parameter values to use in the condition
 }
}

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

{{status subtle="false" colour="Green" title="POST"/}}

 /data/condition/param_values
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

body

body



getParamValues {
 conditions: [
    conditionGraphObject {
     type: string*
     Type of condition object: 'node' or 'rel'

     label: string
     Label of this condition object

     kind: string
     Node/relationship kind

     condition: {
       Expression to match
     }

     show: [
       Values to show in search results

        {
       }
     ]

     order_by: {
       Ordering expression
     }
   }
 ]
 parameter: string*
 Name of the parameter

 parameters: {
   Already-set parameter values
 }
}

Responses

Code

Description

Schema

200

Values and counts

[
  getParamValuesResult {
   value: string*
   Value

   count: integer*
   Number of time the value appears
 }
]

{{status subtle="false" colour="Green" title="POST"/}}

 /data/candidate
Click here to expand...
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.
}

{{status subtle="false" colour="Green" title="POST"/}}

 /data/candidates
Click here to expand...
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.

      {
     }
   ]*
 }
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/nodes/{node_id}
Click here to expand...
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
 }*
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/nodes/{node_id}?relationships=true
Click here to expand...
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
 ]*
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/nodes/{node_id}?traverse={traverse_spec}
Click here to expand...
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.
     }
   ]
 }*
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/nodes/{node_id}?attributes={attributes}
Click here to expand...
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
 }*
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/nodes/{node_id}/graph
Click here to expand...
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
   }
 ]*
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/kinds/{kind}
Click here to expand...
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).
 }
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/kinds/{kind}?format=object
Click here to expand...
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).
 }
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/partitions
Click here to expand...
Description

Gets names and ids of all data store partitions.

New in version 1.2
Responses

Code

Description

Schema

200

successful operation

{
}

{{status subtle="false" colour="Green" title="POST"/}}

 /data/partitions
Click here to expand...
Description

Creates a partition.

Partition flags are:

  • maintain_history — store history of all changes to nodes and relationships
  • permit_node_destruction — when nodes are destroyed, completely remove them rather than marking them as destroyed
  • exclude_from_main_queries — do not search in this partition when performing a global search

Returns the partition id.

New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

body

body

Partition details to create


createPartition {
 name: string*
 Name of the partition

 flags: [
   Partition flags

   string
   Enum: [
     "maintain_history",
     "permit_node_destruction",
     "exclude_from_main_queries"
   ]
 ]
}

Responses

Code

Description

Schema

201

successful operation

string
Partition id

{{status subtle="false" colour="Green" title="POST"/}}

 /data/import
Click here to expand...
Description

Imports data. Returns the import UUID.

New in version 1.2
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

{{status subtle="false" colour="Green" title="POST"/}}

 /data/write
Click here to expand...
Description

Perform arbitrary write operations.

New in version 1.2
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)
 }
]

discovery

Control scanning and view results

{{status subtle="false" colour="Blue" title="GET"/}}

 /discovery
Click here to expand...
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"
 ]
}

{{status subtle="false" colour="Yellow" title="PATCH"/}}

 /discovery
Click here to expand...
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


{{status subtle="false" colour="Blue" title="GET"/}}

 /discovery/api_provider_metadata
Click here to expand...
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
       ]*
     }
   ]*
 }
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /discovery/cloud_metadata
Click here to expand...
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
       ]*
     }
   ]*
 }
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /discovery/runs
Click here to expand...
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.

     MAX_ACTIVE_IAP_SESSIONS: int64
     Maximum number of active IAP sessions per region per account. This is only supported for GCP 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)
 }
]

{{status subtle="false" colour="Green" title="POST"/}}

 /discovery/runs
Click here to expand...
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.

   MAX_ACTIVE_IAP_SESSIONS: int64
   Maximum number of active IAP sessions per region per account. This is only supported for GCP cloud scans. If this option is omitted, the system default sets the limit.
 }
}

Responses

Code

Description

Schema

200

successful operation

{
 uuid: string*
 uri: string*
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /discovery/runs/{run_id}
Click here to expand...
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.

   MAX_ACTIVE_IAP_SESSIONS: int64
   Maximum number of active IAP sessions per region per account. This is only supported for GCP 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


{{status subtle="false" colour="Yellow" title="PATCH"/}}

 /discovery/runs/{run_id}
Click here to expand...
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

{{status subtle="false" colour="Blue" title="GET"/}}

 /discovery/runs/{run_id}/results
Click here to expand...
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
 }
}


{{status subtle="false" colour="Blue" title="GET"/}}

 /discovery/runs/{run_id}/results/{result_type}
Click here to expand...
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).
 }
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /discovery/runs/{run_id}/results/{result_type}?format=object
Click here to expand...
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).
 }
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /discovery/runs/{run_id}/inferred
Click here to expand...
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
 }
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /discovery/runs/{run_id}/inferred/{inferred_kind}
Click here to expand...
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


{{status subtle="false" colour="Blue" title="GET"/}}

 /discovery/runs/{run_id}/inferred/{inferred_kind}?format=object
Click here to expand...
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


events

Push events

{{status subtle="false" colour="Green" title="POST"/}}

 /events
Click here to expand...
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

kerberos

Manage Kerberos resources

{{status subtle="false" colour="Blue" title="GET"/}}

 /vault/kerberos/realms
Click here to expand...
Description

Retrieve all available realms

New in version 1.3
Responses

Code

Description

Schema

200

A list of all available realms

realmsResponse {
 can_write: boolean*
 Whether or not the user can edit realms

 realms: [
   A list of all available realms

    realmResponse {
     admin_server: string*
     The address (IP or DNS name) of the admin server

     admin_port: integer*
     The port of the admin server

     kdc: string*
     The address (IP or DNS name) of the KDC

     kdc_port: integer*
     The port of the KDC

     name: string*
     The name of the realm

     number_of_keytabs: integer*
     The number of users with keytabs

     number_of_ccaches: integer*
     The number of users with ccaches

     number_of_credentials: integer*
     The number of credentials using the realm

     number_of_datasources: integer*
     The number of data sources using the realm
   }
 ]*
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /vault/kerberos/realms/{realm_name}
Click here to expand...
Description

Retrieve a Kerberos realm by name

New in version 1.3
Parameters

Name

Located in

Description

Default

Schema

realm_name

path

The name of the realm


string*

Responses

Code

Description

Schema

200

A list of realms

[
  realmResponse {
   admin_server: string*
   The address (IP or DNS name) of the admin server

   admin_port: integer*
   The port of the admin server

   kdc: string*
   The address (IP or DNS name) of the KDC

   kdc_port: integer*
   The port of the KDC

   name: string*
   The name of the realm

   number_of_keytabs: integer*
   The number of users with keytabs

   number_of_ccaches: integer*
   The number of users with ccaches

   number_of_credentials: integer*
   The number of credentials using the realm

   number_of_datasources: integer*
   The number of data sources using the realm
 }
]

{{status subtle="false" colour="Green" title="POST"/}}

 /vault/kerberos/realms/{realm_name}
Click here to expand...
Description

Create a Kerberos realm

New in version 1.3
Parameters

Name

Located in

Description

Default

Schema

realm_name

path

The name of the realm


string*

body

body

Values to create a new realm


KerberosInput {
 admin_server: string
 The address (IP or DNS name) of the admin server

 admin_port: integer
 The port of the admin server

 kdc: string*
 The address (IP or DNS name) of the KDC

 kdc_port: integer
 The port of the KDC
}

Responses

Code

Description

Schema

200

Successful operation

realmResponse {
 admin_server: string*
 The address (IP or DNS name) of the admin server

 admin_port: integer*
 The port of the admin server

 kdc: string*
 The address (IP or DNS name) of the KDC

 kdc_port: integer*
 The port of the KDC

 name: string*
 The name of the realm

 number_of_keytabs: integer*
 The number of users with keytabs

 number_of_ccaches: integer*
 The number of users with ccaches

 number_of_credentials: integer*
 The number of credentials using the realm

 number_of_datasources: integer*
 The number of data sources using the realm
}

{{status subtle="false" colour="Yellow" title="PATCH"/}}

 /vault/kerberos/realms/{realm_name}
Click here to expand...
Description

Update a Kerberos realm

New in version 1.3
Parameters

Name

Located in

Description

Default

Schema

realm_name

path

The name of the realm


string*

body

body

Values to update a realm


KerberosInput {
 admin_server: string
 The address (IP or DNS name) of the admin server

 admin_port: integer
 The port of the admin server

 kdc: string*
 The address (IP or DNS name) of the KDC

 kdc_port: integer
 The port of the KDC
}

Responses

Code

Description

Schema

200

Successful operation

realmResponse {
 admin_server: string*
 The address (IP or DNS name) of the admin server

 admin_port: integer*
 The port of the admin server

 kdc: string*
 The address (IP or DNS name) of the KDC

 kdc_port: integer*
 The port of the KDC

 name: string*
 The name of the realm

 number_of_keytabs: integer*
 The number of users with keytabs

 number_of_ccaches: integer*
 The number of users with ccaches

 number_of_credentials: integer*
 The number of credentials using the realm

 number_of_datasources: integer*
 The number of data sources using the realm
}

{{status subtle="false" colour="Red" title="DELETE"/}}

 /vault/kerberos/realms/{realm_name}
Click here to expand...
Description

Delete a Kerberos realm

New in version 1.3
Parameters

Name

Located in

Description

Default

Schema

realm_name

path

The name of the realm


string*

Responses

Code

Description

Schema

200

Successful operation


{{status subtle="false" colour="Green" title="POST"/}}

 /vault/kerberos/realms/{realm_name}/test
Click here to expand...
Description

Test user credentials by attempting to acquire a new Kerberos Ticket Granting Ticket (TGT)

New in version 1.3
Parameters

Name

Located in

Description

Default

Schema

realm_name

path

The name of the realm


string*

body

body

kuser credentials to get a Kerberos ticket


KerberosUserInput {
 principal: string*
 Name of user principal for the test

 password: string*
 Password of user principal for the test
}

Responses

Code

Description

Schema

200

Successful operation


{{status subtle="false" colour="Blue" title="GET"/}}

 /vault/kerberos/realms/{realm_name}/keytabs
Click here to expand...
Description

Return a list of users with a Kerberos keytab file

New in version 1.3
Parameters

Name

Located in

Description

Default

Schema

realm_name

path

The name of the realm


string*

Responses

Code

Description

Schema

200

A list of users with keytabs

[
 string
]

{{status subtle="false" colour="Green" title="POST"/}}

 /vault/kerberos/realms/{realm_name}/keytabs
Click here to expand...
Description

Upload a Kerberos keytab file

New in version 1.3
Parameters

Name

Located in

Description

Default

Schema

realm_name

path

The name of the realm


string*

username

formData

name of the user


string*

keytab

formData



file*

Responses

Code

Description

Schema

200

Successful operation


{{status subtle="false" colour="Red" title="DELETE"/}}

 /vault/kerberos/realms/{realm_name}/keytabs/{username}
Click here to expand...
Description

Delete the keytab file for a user

New in version 1.3
Parameters

Name

Located in

Description

Default

Schema

realm_name

path

The name of the realm


string*

username

path

The user name


string*

Responses

Code

Description

Schema

200

successful operation


{{status subtle="false" colour="Blue" title="GET"/}}

 /vault/kerberos/realms/{realm_name}/ccaches
Click here to expand...
Description

Return a list of users with a Kerberos credential cache file

New in version 1.3
Parameters

Name

Located in

Description

Default

Schema

realm_name

path

The name of the realm


string*

Responses

Code

Description

Schema

200

A list of users with ccaches

[
 string
]

{{status subtle="false" colour="Green" title="POST"/}}

 /vault/kerberos/realms/{realm_name}/ccaches
Click here to expand...
Description

Upload a Kerberos credential cache file

New in version 1.3
Parameters

Name

Located in

Description

Default

Schema

realm_name

path

The name of the realm


string*

username

formData

name of the user


string*

ccache

formData



file*

Responses

Code

Description

Schema

200

Successful operation


{{status subtle="false" colour="Red" title="DELETE"/}}

 /vault/kerberos/realms/{realm_name}/ccaches/{username}
Click here to expand...
Description

Deletes the credential cache file for a user

New in version 1.3
Parameters

Name

Located in

Description

Default

Schema

realm_name

path

The name of the realm


string*

username

path

The user name


string*

Responses

Code

Description

Schema

200

successful operation



knowledge

Upload new TKUs and pattern modules

{{status subtle="false" colour="Blue" title="GET"/}}

 /knowledge
Click here to expand...
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
   }
 ]*
}

{{status subtle="false" colour="Green" title="POST"/}}

 /knowledge/{filename}
Click here to expand...
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


{{status subtle="false" colour="Blue" title="GET"/}}

 /knowledge/status
Click here to expand...
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
}

models

Manage service and application models

{{status subtle="false" colour="Blue" title="GET"/}}

 /models
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

name

query

Substring to match in model name


string

type

query

Type of model


string
Enum: [
 "rules_template",
 "rules",
 "sam",
 "static",
 "instance",
 "imported"
]

kind

query

Node kind created by model


string
Enum: [
 "BusinessService",
 "TechnicalService",
 "BusinessApplicationInstance"
]

published

query

Only return models that are / are not published


boolean

review_suggested

query

Only return models that do or do not require review


boolean

version

query

Model version number


integer

favorite

query

Only return models that are / are not the invoking user's favorite


boolean

compatibility

query

Only return models that are compatible with the provided client product name


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

successful operation

[
 any
]

{{status subtle="false" colour="Green" title="POST"/}}

 /models
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

body

body

Model to create


modelDefinition {
 name: string
 Name of the model

 type: string
 Type of model
 Enum: [
   "sam",
   "rules_template",
   "rules",
   "static",
   "instance",
   "imported"
 ]

 kind: string
 Published node kind
 Enum: [
   "BusinessService",
   "TechnicalService",
   "BusinessApplicationInstance"
 ]

 key: string
 Unique key

 version: integer
 Version of the model

 description: string
 Description of the model

 notes: string
 Notes about the model

 compatibility: string
 Identifier of client compatibility

 attributes: {
   Attributes to store on published node
 }

 metadata: {
   Additional metadata stored on the model
 }

 conditions: {
   Conditions in a rule-based model
 }

 templates: {
   Templates used by this model
 }

 contents: {
   Nodes and relationships in this model
 }

 published: boolean
 True if the model is published

 favorite: boolean
 True if the model is a favorite of the calling user

 depended_upon: [
   Keys of models that this one depends upon

   string
 ]

 dependants: [
   Keys of models that depend on this one

   string
 ]

 containers: [
   Keys of models that contain this one

   string
 ]

 contained: [
   Keys of models that are contained in this one

   string
 ]
}

Responses

Code

Description

Schema

201

successful creation

modelDefinition {
 name: string
 Name of the model

 type: string
 Type of model
 Enum: [
   "sam",
   "rules_template",
   "rules",
   "static",
   "instance",
   "imported"
 ]

 kind: string
 Published node kind
 Enum: [
   "BusinessService",
   "TechnicalService",
   "BusinessApplicationInstance"
 ]

 key: string
 Unique key

 version: integer
 Version of the model

 description: string
 Description of the model

 notes: string
 Notes about the model

 compatibility: string
 Identifier of client compatibility

 attributes: {
   Attributes to store on published node
 }

 metadata: {
   Additional metadata stored on the model
 }

 conditions: {
   Conditions in a rule-based model
 }

 templates: {
   Templates used by this model
 }

 contents: {
   Nodes and relationships in this model
 }

 published: boolean
 True if the model is published

 favorite: boolean
 True if the model is a favorite of the calling user

 depended_upon: [
   Keys of models that this one depends upon

   string
 ]

 dependants: [
   Keys of models that depend on this one

   string
 ]

 containers: [
   Keys of models that contain this one

   string
 ]

 contained: [
   Keys of models that are contained in this one

   string
 ]
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /models/{key}
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

key

path

Model key


string*

expand_related

query

If true, expands the result to include other models that are related by Containment and Dependency relationships


boolean

Responses

Code

Description

Schema

200

successful operation

modelDefinition {
 name: string
 Name of the model

 type: string
 Type of model
 Enum: [
   "sam",
   "rules_template",
   "rules",
   "static",
   "instance",
   "imported"
 ]

 kind: string
 Published node kind
 Enum: [
   "BusinessService",
   "TechnicalService",
   "BusinessApplicationInstance"
 ]

 key: string
 Unique key

 version: integer
 Version of the model

 description: string
 Description of the model

 notes: string
 Notes about the model

 compatibility: string
 Identifier of client compatibility

 attributes: {
   Attributes to store on published node
 }

 metadata: {
   Additional metadata stored on the model
 }

 conditions: {
   Conditions in a rule-based model
 }

 templates: {
   Templates used by this model
 }

 contents: {
   Nodes and relationships in this model
 }

 published: boolean
 True if the model is published

 favorite: boolean
 True if the model is a favorite of the calling user

 depended_upon: [
   Keys of models that this one depends upon

   string
 ]

 dependants: [
   Keys of models that depend on this one

   string
 ]

 containers: [
   Keys of models that contain this one

   string
 ]

 contained: [
   Keys of models that are contained in this one

   string
 ]
}

{{status subtle="false" colour="Yellow" title="PATCH"/}}

 /models/{key}
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

key

path

Model key


string*

body

body

Model state to patch


modelDefinition {
 name: string
 Name of the model

 type: string
 Type of model
 Enum: [
   "sam",
   "rules_template",
   "rules",
   "static",
   "instance",
   "imported"
 ]

 kind: string
 Published node kind
 Enum: [
   "BusinessService",
   "TechnicalService",
   "BusinessApplicationInstance"
 ]

 key: string
 Unique key

 version: integer
 Version of the model

 description: string
 Description of the model

 notes: string
 Notes about the model

 compatibility: string
 Identifier of client compatibility

 attributes: {
   Attributes to store on published node
 }

 metadata: {
   Additional metadata stored on the model
 }

 conditions: {
   Conditions in a rule-based model
 }

 templates: {
   Templates used by this model
 }

 contents: {
   Nodes and relationships in this model
 }

 published: boolean
 True if the model is published

 favorite: boolean
 True if the model is a favorite of the calling user

 depended_upon: [
   Keys of models that this one depends upon

   string
 ]

 dependants: [
   Keys of models that depend on this one

   string
 ]

 containers: [
   Keys of models that contain this one

   string
 ]

 contained: [
   Keys of models that are contained in this one

   string
 ]
}

Responses

Code

Description

Schema

200

successful patch

modelDefinition {
 name: string
 Name of the model

 type: string
 Type of model
 Enum: [
   "sam",
   "rules_template",
   "rules",
   "static",
   "instance",
   "imported"
 ]

 kind: string
 Published node kind
 Enum: [
   "BusinessService",
   "TechnicalService",
   "BusinessApplicationInstance"
 ]

 key: string
 Unique key

 version: integer
 Version of the model

 description: string
 Description of the model

 notes: string
 Notes about the model

 compatibility: string
 Identifier of client compatibility

 attributes: {
   Attributes to store on published node
 }

 metadata: {
   Additional metadata stored on the model
 }

 conditions: {
   Conditions in a rule-based model
 }

 templates: {
   Templates used by this model
 }

 contents: {
   Nodes and relationships in this model
 }

 published: boolean
 True if the model is published

 favorite: boolean
 True if the model is a favorite of the calling user

 depended_upon: [
   Keys of models that this one depends upon

   string
 ]

 dependants: [
   Keys of models that depend on this one

   string
 ]

 containers: [
   Keys of models that contain this one

   string
 ]

 contained: [
   Keys of models that are contained in this one

   string
 ]
}

{{status subtle="false" colour="Red" title="DELETE"/}}

 /models/{key}
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

key

path

Model key


string*

Responses

Code

Description

Schema

204

successful delete


{{status subtle="false" colour="Blue" title="GET"/}}

 /models/{key}/topology
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

key

path

Model key


string*

attributes

query

Additional attributes to retrieve


string

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

    {
   }
 ]*
}


{{status subtle="false" colour="Blue" title="GET"/}}

 /models/{key}/nodecount
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

key

path

Model key


string*

Responses

Code

Description

Schema

200

successful operation

groupNodeCountMeta {
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /models/{key}/nodes
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

key

path

Model key


string*

format

query

Result format


string
Enum: [
 "array",
 "object",
 "tree"
]

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

successful operation

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

{{status subtle="false" colour="Blue" title="GET"/}}

 /models/{key}/nodes/{kind}
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

key

path

Model key


string*

kind

path

Node kind


string*

format

query

Result format


string
Enum: [
 "array",
 "object",
 "tree"
]

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

successful operation

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

{{status subtle="false" colour="Blue" title="GET"/}}

 /models/by_node_id/{node_id}
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

node_id

path

Model node id


string*

expand_related

query



boolean

Responses

Code

Description

Schema

200

successful operation

modelDefinition {
 name: string
 Name of the model

 type: string
 Type of model
 Enum: [
   "sam",
   "rules_template",
   "rules",
   "static",
   "instance",
   "imported"
 ]

 kind: string
 Published node kind
 Enum: [
   "BusinessService",
   "TechnicalService",
   "BusinessApplicationInstance"
 ]

 key: string
 Unique key

 version: integer
 Version of the model

 description: string
 Description of the model

 notes: string
 Notes about the model

 compatibility: string
 Identifier of client compatibility

 attributes: {
   Attributes to store on published node
 }

 metadata: {
   Additional metadata stored on the model
 }

 conditions: {
   Conditions in a rule-based model
 }

 templates: {
   Templates used by this model
 }

 contents: {
   Nodes and relationships in this model
 }

 published: boolean
 True if the model is published

 favorite: boolean
 True if the model is a favorite of the calling user

 depended_upon: [
   Keys of models that this one depends upon

   string
 ]

 dependants: [
   Keys of models that depend on this one

   string
 ]

 containers: [
   Keys of models that contain this one

   string
 ]

 contained: [
   Keys of models that are contained in this one

   string
 ]
}

{{status subtle="false" colour="Yellow" title="PATCH"/}}

 /models/by_node_id/{node_id}
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

node_id

path

Model node id


string*

body

body

Model state to patch


modelDefinition {
 name: string
 Name of the model

 type: string
 Type of model
 Enum: [
   "sam",
   "rules_template",
   "rules",
   "static",
   "instance",
   "imported"
 ]

 kind: string
 Published node kind
 Enum: [
   "BusinessService",
   "TechnicalService",
   "BusinessApplicationInstance"
 ]

 key: string
 Unique key

 version: integer
 Version of the model

 description: string
 Description of the model

 notes: string
 Notes about the model

 compatibility: string
 Identifier of client compatibility

 attributes: {
   Attributes to store on published node
 }

 metadata: {
   Additional metadata stored on the model
 }

 conditions: {
   Conditions in a rule-based model
 }

 templates: {
   Templates used by this model
 }

 contents: {
   Nodes and relationships in this model
 }

 published: boolean
 True if the model is published

 favorite: boolean
 True if the model is a favorite of the calling user

 depended_upon: [
   Keys of models that this one depends upon

   string
 ]

 dependants: [
   Keys of models that depend on this one

   string
 ]

 containers: [
   Keys of models that contain this one

   string
 ]

 contained: [
   Keys of models that are contained in this one

   string
 ]
}

Responses

Code

Description

Schema

200

successful patch

modelDefinition {
 name: string
 Name of the model

 type: string
 Type of model
 Enum: [
   "sam",
   "rules_template",
   "rules",
   "static",
   "instance",
   "imported"
 ]

 kind: string
 Published node kind
 Enum: [
   "BusinessService",
   "TechnicalService",
   "BusinessApplicationInstance"
 ]

 key: string
 Unique key

 version: integer
 Version of the model

 description: string
 Description of the model

 notes: string
 Notes about the model

 compatibility: string
 Identifier of client compatibility

 attributes: {
   Attributes to store on published node
 }

 metadata: {
   Additional metadata stored on the model
 }

 conditions: {
   Conditions in a rule-based model
 }

 templates: {
   Templates used by this model
 }

 contents: {
   Nodes and relationships in this model
 }

 published: boolean
 True if the model is published

 favorite: boolean
 True if the model is a favorite of the calling user

 depended_upon: [
   Keys of models that this one depends upon

   string
 ]

 dependants: [
   Keys of models that depend on this one

   string
 ]

 containers: [
   Keys of models that contain this one

   string
 ]

 contained: [
   Keys of models that are contained in this one

   string
 ]
}

{{status subtle="false" colour="Red" title="DELETE"/}}

 /models/by_node_id/{node_id}
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

node_id

path

Model node id


string*

Responses

Code

Description

Schema

204

successful delete


{{status subtle="false" colour="Blue" title="GET"/}}

 /models/by_node_id/{node_id}/topology
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

node_id

path

Model node id


string*

attributes

query

Additional attributes to retrieve, as a comma separated list


string

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

    {
   }
 ]*
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /models/by_node_id/{node_id}/nodecount
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

node_id

path

Model node id


string*

Responses

Code

Description

Schema

200

successful operation

groupNodeCountMeta {
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /models/by_node_id/{node_id}/nodes
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

node_id

path

Model node id


string*

format

query

Result format


string
Enum: [
 "array",
 "object",
 "tree"
]

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

successful operation

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


{{status subtle="false" colour="Blue" title="GET"/}}

 /models/by_node_id/{node_id}/nodes/{kind}
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

node_id

path

Model node id


string*

kind

path

Node kind


string*

format

query

Result format


string
Enum: [
 "array",
 "object",
 "tree"
]

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

successful operation

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

{{status subtle="false" colour="Green" title="POST"/}}

 /models/multi
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

body

body

Multiple operation input


[
  {
   method: string*
   Enum: [
     "POST",
     "PATCH",
     "CLONE",
     "DELETE"
   ]
   body: {
   }*
 }
]

Responses

Code

Description

Schema

200

Successful operation

[
  {
   code: integer*
   HTTP status code of operation

   body: {
     Success result
   }

   message: string
   Error message
 }
]

taxonomy

Retrieve taxonomy data

{{status subtle="false" colour="Blue" title="GET"/}}

 /taxonomy/sections
Click here to expand...
Description
New in version 1.4
Responses

Code

Description

Schema

200

successful operation

[
 string
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /taxonomy/locales
Click here to expand...
Description
New in version 1.4
Responses

Code

Description

Schema

200

successful operation

[
 string
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /taxonomy/nodekinds
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

section

query

The model section, such as 'inferred' or 'ddd'. If not specified, returns node kinds from all sections


string

Responses

Code

Description

Schema

200

successful operation

[
 string
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /taxonomy/nodekinds?format=info
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

section

query

The model section, such as 'inferred' or 'ddd'. If not specified, returns node kinds from all sections


string

locale

query



string

Responses

Code

Description

Schema

200

successful operation

TaxonomyNodeKindInfo {
 name: string*
 Name of node kind

 display_name: string*
 Locale name of node kind

 display_plural: string*
 Locale plural name of node kind

 category: string
 Locale category name

 description: string*
 Description of node kind

 section: string
 Model section
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /taxonomy/nodekinds/{kind}
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

kind

path

Name of node kind


string*

locale

query



string

Responses

Code

Description

Schema

200

successful operation

TaxonomyNodeKind {
 name: string*
 Name of node kind

 display_name: string*
 Locale name of node kind

 display_plural: string*
 Locale plural name of node kind

 category: string*
 Locale category name

 description: string*
 Description of node kind

 long_description: string*
 Long description of node kind

 section: string*
 Model section

 parent_class: string*
 Name of parent class

 child_classes: [
   Name of child classes

   string
 ]*

 attrs: [
   List of attributes defined for this node kind

    {
     name: string*
     Name of attribute

     description: string*
     Description of attribute

     type: string*
     Type of attribute

     display_name: string*
     Locale name of attribute
   }
 ]*

 inherited_attrs: [
   List of attributes inherited from class hierarchy

    {
     name: string*
     Name of attribute

     description: string*
     Description of attribute

     type: string*
     Type of attribute

     display_name: string*
     Locale name of attribute
   }
 ]*

 extension_attrs: [
   Names of attributes found on this node kind that have not been defined in the taxonomy

   string
 ]*

 label_attr: string*
 Name of attribute used as the label

 exprs: [
   List of expressions defined for this node kind

    {
     name: string*
     Name of expression

     description: string*
     Description of expression

     value: string*
     Value of expression

     display_name: string*
     Locale name of expression
   }
 ]*

 inherited_exprs: [
   List of expressions inherited from class hierarchy

    {
     name: string*
     Name of expression

     description: string*
     Description of expression

     value: string*
     Value of expression

     display_name: string*
     Locale name of expression
   }
 ]*

 rels: [
   List of relationships defined for this node kind

    {
     spec: string*
     Specification of relationship

     description: string*
     Description of relationship

     display_name: string*
     Locale name of relationship

     impact_to: boolean
     True if the related node is impacted by this one

     impact_from: boolean
     True if this node is impacted by the related node
   }
 ]*

 inherited_rels: [
   List of relationships inherited from class hierarchy

    {
     spec: string*
     Specification of relationship

     description: string*
     Description of relationship

     display_name: string*
     Locale name of relationship

     impact_to: boolean
     True if the related node is impacted by this one

     impact_from: boolean
     True if this node is impacted by the related node
   }
 ]*

 display_rels: [
   List of display relationships defined for this node kind

    {
     name: string*
     Name of display relationship

     description: string*
     Description of display relationship

     specs: [
       List of relationship specifications

       string
     ]*

     display_name: string*
     Locale name of display relationship
   }
 ]*

 inherited_display_rels: [
   List of display relationships inherited from class hierarchy

    {
     name: string*
     Name of display relationship

     description: string*
     Description of display relationship

     specs: [
       List of relationship specifications

       string
     ]*

     display_name: string*
     Locale name of display relationship
   }
 ]*
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /taxonomy/nodekinds/{kind}/fieldlists
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

kind

path

Name of node kind


string*

Responses

Code

Description

Schema

200

successful operation

[
 string
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /taxonomy/nodekinds/{kind}/fieldlists/{fieldlist}
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

kind

path

Name of node kind


string*

fieldlist

path

Name of field list


string*

Responses

Code

Description

Schema

200

successful operation

[
  TaxonomyField {
   name: string*
   Name of attribute or relationship spec

   type: string*
   Field type
   Enum: [
     "attr",
     "display_link",
     "expr",
     "link",
     "sep"
   ]
 }
]


{{status subtle="false" colour="Blue" title="GET"/}}

 /taxonomy/relkinds
Click here to expand...
Description
New in version 1.4
Responses

Code

Description

Schema

200

successful operation

[
 string
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /taxonomy/relkinds?format=info
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

locale

query



string

Responses

Code

Description

Schema

200

successful operation

TaxonomyNodeKindInfo {
 name: string*
 Name of node kind

 display_name: string*
 Locale name of node kind

 display_plural: string*
 Locale plural name of node kind

 category: string
 Locale category name

 description: string*
 Description of node kind

 section: string
 Model section
}

{{status subtle="false" colour="Blue" title="GET"/}}

 /taxonomy/relkinds/{kind}
Click here to expand...
Description
New in version 1.4
Parameters

Name

Located in

Description

Default

Schema

kind

path

Name of relationship kind


string*

locale

query



string

Responses

Code

Description

Schema

200

successful operation

TaxonomyNodeKind {
 name: string*
 Name of node kind

 display_name: string*
 Locale name of node kind

 display_plural: string*
 Locale plural name of node kind

 category: string*
 Locale category name

 description: string*
 Description of node kind

 long_description: string*
 Long description of node kind

 section: string*
 Model section

 parent_class: string*
 Name of parent class

 child_classes: [
   Name of child classes

   string
 ]*

 attrs: [
   List of attributes defined for this node kind

    {
     name: string*
     Name of attribute

     description: string*
     Description of attribute

     type: string*
     Type of attribute

     display_name: string*
     Locale name of attribute
   }
 ]*

 inherited_attrs: [
   List of attributes inherited from class hierarchy

    {
     name: string*
     Name of attribute

     description: string*
     Description of attribute

     type: string*
     Type of attribute

     display_name: string*
     Locale name of attribute
   }
 ]*

 extension_attrs: [
   Names of attributes found on this node kind that have not been defined in the taxonomy

   string
 ]*

 label_attr: string*
 Name of attribute used as the label

 exprs: [
   List of expressions defined for this node kind

    {
     name: string*
     Name of expression

     description: string*
     Description of expression

     value: string*
     Value of expression

     display_name: string*
     Locale name of expression
   }
 ]*

 inherited_exprs: [
   List of expressions inherited from class hierarchy

    {
     name: string*
     Name of expression

     description: string*
     Description of expression

     value: string*
     Value of expression

     display_name: string*
     Locale name of expression
   }
 ]*

 rels: [
   List of relationships defined for this node kind

    {
     spec: string*
     Specification of relationship

     description: string*
     Description of relationship

     display_name: string*
     Locale name of relationship

     impact_to: boolean
     True if the related node is impacted by this one

     impact_from: boolean
     True if this node is impacted by the related node
   }
 ]*

 inherited_rels: [
   List of relationships inherited from class hierarchy

    {
     spec: string*
     Specification of relationship

     description: string*
     Description of relationship

     display_name: string*
     Locale name of relationship

     impact_to: boolean
     True if the related node is impacted by this one

     impact_from: boolean
     True if this node is impacted by the related node
   }
 ]*

 display_rels: [
   List of display relationships defined for this node kind

    {
     name: string*
     Name of display relationship

     description: string*
     Description of display relationship

     specs: [
       List of relationship specifications

       string
     ]*

     display_name: string*
     Locale name of display relationship
   }
 ]*

 inherited_display_rels: [
   List of display relationships inherited from class hierarchy

    {
     name: string*
     Name of display relationship

     description: string*
     Description of display relationship

     specs: [
       List of relationship specifications

       string
     ]*

     display_name: string*
     Locale name of display relationship
   }
 ]*
}

topology

Retrieve topology data from the datastore

{{status subtle="false" colour="Blue" title="GET"/}}

 /data/nodes/{node_id}/graph
Click here to expand...
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
   }
 ]*
}

{{status subtle="false" colour="Green" title="POST"/}}

 /topology/nodes
Click here to expand...
Description

Get topology data from one or more starting nodes

If an array of node_ids or a search query is provided, starts from the matching nodes and finds all nodes directly or indirectly related to them according to the focus.

If conditions or templates are specified, finds just the nodes matched by the condition, the relationships in the condition, plus any other relationships between the matched nodes. In this case, if node_ids is also specified, those nodes and their relationships are added to the output, but no further related nodes are added.

Parameters

Name

Located in

Description

Default

Schema

body

body



topologyNodesQuery {
 node_ids: [
   A list of node IDs. Requests must have one of node_ids, search_query, conditions or templates.

   string
 ]

 search_query: string
 A search query to run. Requests must have one of node_ids, search_query, conditions or templates.

 conditions: [
   Array of condition objects. Requests must have one of node_ids, search_query, conditions or templates.

    {
   }
 ]

 parameters: {
   Parameters required by conditions
 }

 templates: {
   Model templates and parameters. Requests must have one of node_ids, search_query, conditions or templates.
 }

 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

    {
   }
 ]*
}

{{status subtle="false" colour="Green" title="POST"/}}

 /topology/nodes/kinds
Click here to expand...
Description

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

New in version 1.2
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
   }*
 }
]

{{status subtle="false" colour="Blue" title="GET"/}}

 /topology/visualization_state
Click here to expand...
Description

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

New in version 1.2
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*
}

{{status subtle="false" colour="Yellow" title="PATCH"/}}

 /topology/visualization_state
Click here to expand...
Description

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

New in version 1.2
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*
}

{{status subtle="false" colour="Yellow" title="PUT"/}}

 /topology/visualization_state
Click here to expand...
Description

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

New in version 1.2
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*
}

vault

Manage the credential vault

{{status subtle="false" colour="Blue" title="GET"/}}

 /vault
Click here to expand...
Responses

Code

Description

Schema

200

successful operation

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

{{status subtle="false" colour="Yellow" title="PATCH"/}}

 /vault
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

body

body



patchVault {
 open: boolean*
 passphrase: string
}

Responses

Code

Description

Schema

200

successful operation


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*