Devices API
TrueSight Network Automation REST API – DeviceService
The base URL for the API is:
{{status colour="Blue" title="GET"/}}
/v3.0/devices
Click here to expand...
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" | string |
limit | query | Define the number of rows in a page or the maximum number of devices to return | 25 | integer |
offset | query | Return the specified page number | 1 | integer |
query | Filter for devices matching this name, asterisk wildcards allowed |
| string | |
filter.realm | query | Filter for devices that belong to this realm |
| string |
filter.address | query | Filter for devices matching this address, asterisk wildcards allowed |
| string |
filter.vendor | query | Filter for devices from this vendor, by GUID |
| string |
filter.deviceType | query | Filter for devices of this device type, by GUID |
| string |
filter.model | query | Filter for devices matching this model, asterisk wildcards allowed |
| string |
filter.osImage | query | Filter for devices matching this operating system name, asterisk wildcards allowed |
| string |
filter.online | query | Filter for devices that are online or offline |
| boolean |
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 devices |
|
500 | Internal server error: Unexpected exception occurred |
|
{{status colour="Green" title="POST"/}}
/v3.0/devices
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
body | body | Complete attributes of the new device |
| |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
| string* |
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 |
|
{{status colour="Green" title="POST"/}}
/v3.0/devices/filtered
Click here to expand...
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" | string |
offset | query | Return the specified page number | 1 | integer |
limit | query | Define the number of rows in a page or the maximum number of devices to return | 25 | integer |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
| string* |
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 |
|
{{status colour="Blue" title="GET"/}}
/v3.0/devices/{nameOrKey}
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device 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 devices |
|
404 | Not found: No single matching accessible device found |
|
500 | Internal server error: Unexpected exception occurred |
|
{{status colour="Yellow" title="PUT"/}}
/v3.0/devices/{nameOrKey}
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| string* |
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]' |
| string* |
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 |
|
{{status colour="Red" title="DELETE"/}}
/v3.0/devices/{nameOrKey}
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| string* |
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 | boolean |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
| string* |
Responses
Code | Description | Schema |
|---|---|---|
200 | successful operation | string |
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 |
|
{{status colour="Yellow" title="PATCH"/}}
/v3.0/devices/{nameOrKey}
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| string* |
body | body | New attribute values for the device, 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 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 |
|
{{status colour="Blue" title="GET"/}}
/v3.0/devices/{nameOrKey}/configurations/{cfgKey}
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| string* |
cfgKey | path | Database key of the configuration 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 devices |
|
404 | Not found: No single matching accessible device or configuration found |
|
500 | Internal server error: Unexpected exception occurred |
|
{{status colour="Blue" title="GET"/}}
/v3.0/devices/{nameOrKey}/configurations/{cfgKey}/binaryData
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| string* |
cfgKey | path | Database key of the configuration of interest |
| string* |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
| string* |
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 |
|
{{status colour="Blue" title="GET"/}}
/v3.0/devices/{nameOrKey}/configurations/{cfgKey}/data
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| string* |
cfgKey | path | Database key of the configuration of interest |
| string* |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
| string* |
Responses
Code | Description | Schema |
|---|---|---|
200 | successful operation | string |
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 |
|
{{status colour="Blue" title="GET"/}}
/v3.0/devices/{nameOrKey}/configurations/{trailGuid}
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| string* |
trailGuid | path | The GUID of the configuration trail of interest |
| string* |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
| string* |
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 |
|
{{status colour="Yellow" title="PUT"/}}
/v3.0/devices/{nameOrKey}/current_configuration/{trailGuid}
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| string* |
trailGuid | path | The GUID of the configuration trail "Device End of Life" |
| string* |
body | body | Complete new configuration of configuration trail "Device End of Life"; |
| string |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
| string* |
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 |
|
{{status colour="Blue" title="GET"/}}
/v3.0/devices/{nameOrKey}/current_configurations
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device 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 devices |
|
404 | Not found: No single matching accessible device found |
|
500 | Internal server error: Unexpected exception occurred |
|
{{status colour="Blue" title="GET"/}}
/v3.0/devices/{nameOrKey}/status
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device 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 devices |
|
404 | Not found: No single matching accessible device found |
|
500 | Internal server error: Unexpected exception occurred |
|
{{status colour="Blue" title="GET"/}}
/v3.0/devices/{nameOrKey}/status/{actionGuid}/transcript
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device of interest |
| string* |
actionGuid | path | The GUID of the device action of interest |
| string* |
Authorization | header | Authorization token formatted as 'Bearer [token]' |
| string* |
Responses
Code | Description | Schema |
|---|---|---|
200 | successful operation | string |
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 |
|
{{status colour="Blue" title="GET"/}}
/v3.0/devices/{nameOrKey}/trusted_configurations
Click here to expand...
Parameters
Name | Located in | Description | Default | Schema |
|---|---|---|---|---|
nameOrKey | path | Name or database key of the device 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 devices |
|
404 | Not found: No single matching accessible device found |
|
500 | Internal server error: Unexpected exception occurred |
|
Object Definitions
Object | Schema |
|---|---|
AbbreviatedDeviceDTO | Click here to expand...{ |
ActionStatusDTO | Click here to expand...{ |
ComplianceStatusDTO | Click here to expand...{ |
ComponentId | Click here to expand...{ |
ConfigurationDTO | Click here to expand...{ |
DeviceDTO | Click here to expand...{ |
DeviceFilterDTO | Click here to expand...{ |
DeviceInterfaceDTO | Click here to expand...{ |
DeviceStatusDTO | Click here to expand...{ |
DynamicFieldValueDTO | Click here to expand...{ |
EntityDTO | Click here to expand...{ |
FailedRuleDTO | Click here to expand...{ |
HardwareInventoryDTO | Click here to expand...{ |
IOSHardwareInventoryFilterDTO | Click here to expand...{ |
JsonPatch | Click here to expand...[ |
JsonPatch.OneOperation | Click here to expand... |
JsonPatch.Pointer | Click here to expand...string |
JsonPatch.Add | Click here to expand...{ |
JsonPatch.Remove | Click here to expand...{ |
JsonPatch.Replace | Click here to expand...{ |
JsonPatch.Move | Click here to expand...{ |
JsonPatch.Copy | Click here to expand...{ |
JsonPatch.Test | Click here to expand...{ |
OsImageLoadHistoryDTO | Click here to expand...{ |
PassedRuleDTO | Click here to expand...{ |
StorageDTO | Click here to expand...{ |
TimePeriodDTO | Click here to expand...{ |