Devices API
TrueSight Network Automation REST API – DeviceService
The base URL for the API is:
https://serverName:portNumber/bca-networks/api
GET /v3.0/devices
Description
Retrieves devices, matching any filter criteria, with the returned result being abbreviated or partially-detailed devices. May filter by filterable device dynamic fields by including query parameters in the form 'filter.dynamicFieldName=value'
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
orderBy | query | Sort by the specified attribute (name, realm, address, model, osImage, vendorName, or a listable device dynamic field name) in the specified order (prefix with a '+' for ascending or a '-' for descending) | "+name" |
|
limit | query | Define the number of rows in a page or the maximum number of devices to return | 25 |
|
offset | query | Return the specified page number | 1 |
|
query | Filter for devices matching this name, asterisk wildcards allowed |
| ||
filter.realm | query | Filter for devices that belong to this realm |
| |
filter.address | query | Filter for devices matching this address, asterisk wildcards allowed |
| |
filter.vendor | query | Filter for devices from this vendor, by GUID |
| |
filter.deviceType | query | Filter for devices of this device type, by GUID |
| |
filter.model | query | Filter for devices matching this model, asterisk wildcards allowed |
| |
filter.osImage | query | Filter for devices matching this operating system name, asterisk wildcards allowed |
| |
filter.online | query | Filter for devices that are online or offline |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
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 devices | |
500 | Internal server error: Unexpected exception occurred |
POST /v3.0/devices
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
body | body | Complete attributes of the new device | ||
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
Responses
Code | Description | Schema |
---|---|---|
201 | Created: New device successfully added | |
400 | Bad request: Input device DTO is missing or new device 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 device | |
500 | Internal server error: Unexpected exception occurred |
POST /v3.0/devices/filtered
Description
Retrieves devices, matching any filter criteria passed in the request body, with the returned result being abbreviated or partially-detailed devices.
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
body | body | Filter for devices matching the various criteria specified in the DeviceFilterDTO; when null, no filtering occurs | ||
orderBy | query | Sort by the specified attribute (name, realm, address, model, osImage, vendorName, or a listable device dynamic field name) in the specified order (prefix with a '+' for ascending or a '-' for descending) | "+name" |
|
offset | query | Return the specified page number | 1 |
|
limit | query | Define the number of rows in a page or the maximum number of devices to return | 25 |
|
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
Responses
Code | Description | Schema |
---|---|---|
200 | successful operation | |
400 | Bad request: Input device filter contains invalid selections | |
401 | Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in | |
403 | Forbidden: Not allowed to access devices | |
500 | Internal server error: Unexpected exception occurred |
GET /v3.0/devices/{nameOrKey
}
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
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 devices | |
404 | Not found: No single matching accessible device found | |
500 | Internal server error: Unexpected exception occurred |
PUT /v3.0/devices/{nameOrKey
}
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
body | body | Complete new attribute values for the device; anything left out will be considered to be null and will be nulled out in the device; any required dynamic fields missing or null in the input will revert to default values | ||
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
Responses
Code | Description | Schema |
---|---|---|
200 | successful operation | |
400 | Bad request: Input device DTO is missing or modified device is invalid | |
401 | Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in | |
403 | Forbidden: Not allowed to modify the device | |
404 | Not found: No single matching accessible device found | |
500 | Internal server error: Unexpected exception occurred |
DELETE /v3.0/devices/{nameOrKey
}
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
clearReferences | query | When true, will attempt to clear references to the device that would normally prevent it from being deleted. Not every reference can be cleared, so this call can still fail. | false |
|
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
Responses
Code | Description | Schema |
---|---|---|
200 | successful operation |
|
400 | Bad request: device is currently in use | |
401 | Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in | |
403 | Forbidden: Not allowed to delete the device | |
404 | Not found: No single matching accessible device found | |
500 | Internal server error: Unexpected exception occurred |
PATCH /v3.0/devices/{nameOrKey
}
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
body | body | New attribute values for the device, in JSON Patch format | ||
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
Responses
Code | Description | Schema |
---|---|---|
200 | successful operation | |
400 | Bad request: Input JSON patch information is missing or modified device is invalid | |
401 | Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in | |
403 | Forbidden: Not allowed to modify the device | |
404 | Not found: No single matching accessible device found | |
500 | Internal server error: Unexpected exception occurred |
GET /v3.0/devices/{nameOrKey}/configurations/{cfgKey
}
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
cfgKey | path | Database key of the configuration of interest |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
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 devices | |
404 | Not found: No single matching accessible device or configuration found | |
500 | Internal server error: Unexpected exception occurred |
GET /v3.0/devices/{nameOrKey}/configurations/{cfgKey}/binaryData
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
cfgKey | path | Database key of the configuration of interest |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
Responses
Code | Description | Schema |
---|---|---|
200 | OK: Request completed successfully | |
401 | Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in | |
403 | Forbidden: Not allowed to access devices | |
404 | Not found: No single matching accessible device or configuration found, or the configuration has no binary data | |
500 | Internal server error: Unexpected exception occurred |
GET /v3.0/devices/{nameOrKey}/configurations/{cfgKey}/data
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
cfgKey | path | Database key of the configuration of interest |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
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 devices | |
404 | Not found: No single matching accessible device or configuration found, or the configuration has no ASCII data | |
500 | Internal server error: Unexpected exception occurred |
GET /v3.0/devices/{nameOrKey}/configurations/{trailGuid
}
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
trailGuid | path | The GUID of the configuration trail of interest |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
Responses
Code | Description | Schema |
---|---|---|
200 | successful operation | |
400 | Bad request: Input trail GUID is invalid | |
401 | Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in | |
403 | Forbidden: Not allowed to access devices | |
404 | Not found: No single matching accessible device found | |
500 | Internal server error: Unexpected exception occurred |
PUT /v3.0/devices/{nameOrKey}/current_configuration/{trailGuid
}
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
trailGuid | path | The GUID of the configuration trail "Device End of Life" |
| |
body | body | Complete new configuration of configuration trail "Device End of Life"; |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
Responses
Code | Description | Schema |
---|---|---|
200 | successful operation |
|
400 | Bad request: Input device DTO is missing or modified device is invalid | |
401 | Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in | |
403 | Forbidden: Not allowed to modify the device | |
404 | Not found: No single matching accessible device found | |
500 | Internal server error: Unexpected exception occurred |
GET /v3.0/devices/{nameOrKey}/current_configurations
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
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 devices | |
404 | Not found: No single matching accessible device found | |
500 | Internal server error: Unexpected exception occurred |
GET /v3.0/devices/{nameOrKey}/status
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
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 devices | |
404 | Not found: No single matching accessible device found | |
500 | Internal server error: Unexpected exception occurred |
GET /v3.0/devices/{nameOrKey}/status/{actionGuid}/transcript
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
actionGuid | path | The GUID of the device action of interest |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
Responses
Code | Description | Schema |
---|---|---|
200 | successful operation |
|
400 | Bad request: Input action GUID is invalid | |
401 | Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in | |
403 | Forbidden: Not allowed to access devices or transcripts | |
404 | Not found: No single matching accessible device found, or device has no transcript for the specified action | |
500 | Internal server error: Unexpected exception occurred |
GET /v3.0/devices/{nameOrKey}/trusted_configurations
Parameters
Name | Located in | Description | Default | Schema |
---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
|
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 devices | |
404 | Not found: No single matching accessible device found | |
500 | Internal server error: Unexpected exception occurred |
Object Definitions
Object | Schema |
---|---|
AbbreviatedDeviceDTO | Abbreviated or summarized information about a device
|
ActionStatusDTO | Status information about an executed span action
|
ComplianceStatusDTO | Which rules the device is compliant with, and which rules the device is violating
|
ComponentId | Identifies a component in a form that can be input to either the same TrueSight Network Automation server that emitted it or to a different TrueSight Network Automation server; the name, qualifiers, and type uniquely identify a component; and they verify that anything successfully retrieved by a database key is the right component
|
ConfigurationDTO | Details about a configuration
|
DeviceDTO | Details about a device
|
DeviceFilterDTO | Criteria for filtering devices
|
DeviceInterfaceDTO | Details for making a device connection
|
DeviceStatusDTO | Status information about a device
|
DynamicFieldValueDTO | A dynamic field value
|
EntityDTO | A hardware component within the hardware inventory
|
FailedRuleDTO | Information about a rule the device is violating
|
HardwareInventoryDTO | A device's hardware inventory
|
IOSHardwareInventoryFilterDTO | Criteria for filtering against a device's hardware inventory
|
JsonPatch | A list of JSON Patch operations
|
JsonPatch.OneOperation | One JSON Patch operation |
JsonPatch.Pointer | Pointer or path to an element or property
|
JsonPatch.Add | Add a value to an object or inserts it into an array. In the case of an array, the value is inserted before the given index. The - character can be used instead of an index to insert at the end of an array. The value can be any JSON value.
|
JsonPatch.Remove | Remove a value from an object or array.
|
JsonPatch.Replace | Replace an existing value. THe value can be any JSON value.
|
JsonPatch.Move | Move a value from one location to the other. "path" is the destination.
|
JsonPatch.Copy | Copy a value from one location to another. "path" is the destination.
|
JsonPatch.Test | Test that the specified value is set in the document at the specified path. If the test fails, then the patch as a whole is not applied. The Value can be any JSON value.
|
OsImageLoadHistoryDTO | Information about an OS image discovered to be running on the device
|
PassedRuleDTO | Information about a rule with which the device is compliant
|
StorageDTO | A file system or memory component within the hardware inventory
|
TimePeriodDTO | Identifies a date/time range
|
Comments
Log in or register to comment.