Skip to Content
Information
Important This version of the product has reached end of support. The documentation is available for your convenience. However, you must be logged in to access it. You will not be able to leave comments.

Groups API

TrueSight Network Automation REST API – Version 3.0 – Groups
The base URL for the API is:

https://serverName:portNumber/bca-networks/api


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

 /v3.0/groups
Click here to expand...
Description

Retrieves groups, matching any filter criteria; may filter by filterable group dynamic fields by including query parameters in the form 'filter.dynamicFieldName=value'

Parameters

Name

Located in

Description

Default

Schema

query

Filter for groups matching this name, asterisk wildcards allowed


string

filter.realm

query

Filter for groups that belong to this realm


string

filter.autoGroup

query

Filter for auto-groups or non-auto-groups; when true, returns only auto-groups (including empty ones); when false, returns only non-auto-groups; when this filter is absent, no filtering is done


boolean
Enum: [
  "true",
  "false"
]

orderBy

query

Sort by the specified attribute (name, realm, or a listable group dynamic field name) in the specified order (prefix with a '+' for ascending or a '-' for descending)

"+name"

string
Enum: [
  "+name",
  "-name",
  "+realm",
  "-realm"
]

offset

query

Return the specified page number

1

integer

limit

query

Define the number of rows in a page or the maximum number of groups to return

25

integer

Authorization

header

Authorization token formatted as 'Bearer [token]'


string*

Responses

Code

Description

Schema

200

successful operation

[
   #GroupDTO
]

401

Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in


403

Forbidden: Not allowed to access groups


500

Internal server error: Unexpected exception occurred


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

 /v3.0/groups
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new group


Authorization

header

Authorization token formatted as 'Bearer [token]'


string*

Responses

Code

Description

Schema

201

Created: New group successfully added


400

Bad request: Input group DTO is missing or new group is invalid


401

Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in


403

Forbidden: Not allowed to add a new group


500

Internal server error: Unexpected exception occurred


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

 /v3.0/groups/{id}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

id

path

Database key of the group to be modified


string*

body

body

Complete new attribute values for the group; anything left out will be considered to be null and will be nulled out in the group; any required dynamic fields missing or null in the input will revert to default values; to change the realm a group belongs to, must first remove all devices from the group


Authorization

header

Authorization token formatted as 'Bearer [token]'


string*

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input group DTO is missing, modified group is invalid, or attempted to make an invalid type of change (such as renaming an auto-group); see error message for details


401

Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in


403

Forbidden: Not allowed to modify the group


404

Not found: No single matching accessible group found


500

Internal server error: Unexpected exception occurred


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

 /v3.0/groups/{id}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

id

path

Database key of the group to be deleted


string*

Authorization

header

Authorization token formatted as 'Bearer [token]'


string*

Responses

Code

Description

Schema

200

successful operation

string

400

Bad request: group is currently in use or is a non-empty auto-group


401

Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in


403

Forbidden: Not allowed to delete the group


404

Not found: No single matching accessible group found


500

Internal server error: Unexpected exception occurred


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

 /v3.0/groups/{id}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

id

path

Database key of the group to be modified


string*

body

body

New attribute values for the group, in JSON Patch format


Authorization

header

Authorization token formatted as 'Bearer [token]'


string*

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input JSON patch information is missing, modified group is invalid, or attempted to make an invalid type of change (such as renaming an auto-group); see error message for details


401

Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in


403

Forbidden: Not allowed to modify the group


404

Not found: No single matching accessible group found


500

Internal server error: Unexpected exception occurred


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

 /v3.0/groups/{id}/devices
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

id

path

Database key of the group of interest


string*

Authorization

header

Authorization token formatted as 'Bearer [token]'


string*

Responses

Code

Description

Schema

200

successful operation

401

Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in


403

Forbidden: Not allowed to access groups


404

Not found: No single matching accessible group found


500

Internal server error: Unexpected exception occurred


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

 /v3.0/groups/{id}/devices/{deviceId}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

id

path

Database key of the group of interest


string*

deviceId

path

Database key of the device to be added to the group


string*

Authorization

header

Authorization token formatted as 'Bearer [token]'


string*

Responses

Code

Description

Schema

200

successful operation

string

400

Bad request: Device database key is not valid, device is not in the same realm as the group, or attempted to add a device to an auto-group


401

Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in


403

Forbidden: Not allowed to modify the group


404

Not found: No single matching accessible group found


500

Internal server error: Unexpected exception occurred


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

 /v3.0/groups/{id}/devices/{deviceId}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

id

path

Database key of the group of interest


string*

deviceId

path

Database key of the device to be removed from the group


string*

Authorization

header

Authorization token formatted as 'Bearer [token]'


string*

Responses

Code

Description

Schema

200

successful operation

string

400

Bad request: Device database key is not valid, device is not a member of the group, or attempted to remove a device from an auto-group


401

Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in


403

Forbidden: Not allowed to modify the group


404

Not found: No single matching accessible group found


500

Internal server error: Unexpected exception occurred


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

 /v3.0/groups/{nameOrKey}
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the group of interest; a name must be unique across all realms for a group to be returned


string*

Authorization

header

Authorization token formatted as 'Bearer [token]'


string*

Responses

Code

Description

Schema

200

successful operation

401

Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in


403

Forbidden: Not allowed to access groups


404

Not found: No single matching accessible group found


500

Internal server error: Unexpected exception occurred


Object Definitions

Object

Schema

AbbreviatedDeviceDTO

Click here to expand...

{
    id: string
    The device's unique database key
 
    name: string
    The device's unique display name
 
    deviceDetailsLink: string
    Link to get complete details about this device
 
    realmId: string
    The database key of the realm this device belongs to
 
    realmName: string
    The name of the realm this device belongs to
 
    modelName: string
    The discovered model
 
    osImageName: string
    The discovered operating system version
 
    deviceTypeGuid: string
    The GUID of the device type
 
    deviceTypeName: string
    The name of the device type
 
    vendorGuid: string
    The GUID of the vendor
 
    vendorName: string
    The name of the vendor
 
    categoryId: integer
    The category
 
    categoryName: string
    The meaning of the numeric categoryId
 
    onlineFlag: boolean
    Whether or not this device is online
 
    discrepanciesFlag: boolean
    Whether or not this device has discrepancies
 
    violationsFlag: boolean
    Whether or not this device has compliance violations
 
    primaryInterfaceAddress: string
    The primary interface IP address, host name, or URL
 
    primaryInterfaceDeviceAgentId: string
    The database key of the primary interface device agent
 
    primaryInterfaceDeviceAgentName: string
    The name of the primary interface device agent
 
    primaryInterfaceDeviceAgentNIC: string
    The name of the primary interface device agent NIC
 
    primaryInterfaceAccessModeId: integer
    The primary interface access mode
 
    primaryInterfaceAccessModeName: string
    The meaning of the numeric primaryInterfaceAccessModeId
 
    primaryInterfaceTransferModeId: integer
    The primary interface transfer mode
 
    primaryInterfaceTransferModeName: string
    The meaning of the numeric primaryInterfaceTransferModeId
 
    primaryInterfaceDeviceSecurityProfileId: string
    The database key of the primary interface device security profile
 
    primaryInterfaceDeviceSecurityProfileName: string
    The name of the primary interface device security profile
 
    dynamicFields: [
      The dynamic fields
 
       #DynamicFieldValueDTO
    ]
}

DynamicFieldValueDTO

Click here to expand...

{
    id: string
    The database key of the dynamic field whose value this is (read-only)
 
    name: string
    The name of the dynamic field (read-only)
 
    values: [
      The value(s) for the dynamic field; for a single-value field, only the first entry is relevant; read-only for Auto Derived and Configuration Profiled types
 
      string
    ]
 
    dynamicFieldDetailsLink: string
    Link to get more detailed information about the dynamic field (read-only)
}

GroupDTO

Click here to expand...

{
    id: string
    The group's unique database key (read-only)
 
    name: string*
    The group's display name
 
    realmId: string*
    The database key of the realm this group belongs to
 
    realmDetailsLink: string
    Link to get complete details about the parent realm (read-only)
 
    autoGroupFlag: boolean
    Whether or not this group is an auto-group (read-only)
 
    dynamicFields: [
      The dynamic fields
 
       #DynamicFieldValueDTO
    ]
 
    memberDevicesLink: string
    Link to get a list of the member devices (read-only)
}

JsonPatch

Click here to expand...

[
    A list of JSON Patch operations
 
     #JsonPatch.OneOperation
  ]

JsonPatch.OneOperation

JsonPatch.Pointer

Click here to expand...

string
  Pointer or path to an element or property

JsonPatch.Add

Click here to expand...

{
    op: string*
    Enum: [
      "add"
    ]
    value: any*
    path: #JsonPatch.Pointer *
}

JsonPatch.Remove

Click here to expand...

{
    op: string*
    Enum: [
      "remove"
    ]
    path: #JsonPatch.Pointer *
}

JsonPatch.Replace

Click here to expand...

{
    op: string*
    Enum: [
      "replace"
    ]
    value: any*
    path: #JsonPatch.Pointer *
}

JsonPatch.Move

Click here to expand...

{
    op: string*
    Enum: [
      "move"
    ]
    path: #JsonPatch.Pointer *
    from: #JsonPatch.Pointer *
}

JsonPatch.Copy

Click here to expand...

{
    op: string*
    Enum: [
      "copy"
    ]
    path: #JsonPatch.Pointer *
    from: #JsonPatch.Pointer *
}

JsonPatch.Test

Click here to expand...

{
    op: string*
    Enum: [
      "test"
    ]
    value: any*
    path: #JsonPatch.Pointer *
}

 

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

TrueSight Network Automation 8.9