Get Device

get https://app.mk.io/api/v1/projects/:project_name/fleet/devices/:name

Get a device by name. To learn more about devices, read Device Concept.

Authentication

Authorization Bearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

project_name string Required
name string Required

Response

200 A single device
kindstringRequired
The kind of record.
metadataobjectMetadataSchemaRequired
Device metadata.
Show 10 propertiesHide 10 properties
createdstringOptionalformat: date-time
The time when the resource was created
createdBystringOptionalformat: uuid
ID of the user who created the resource
createdByEmailstringOptional
Email of the user who created the resource
displayNamestringOptional
The display name of the resource
idstringRequiredformat: uuid
The ID of the resource
labelsmap from strings to stringOptional
A dictionary of labels associated with the resource
Show value schemaHide value schema
[any key]string
namestringOptional
The name of the resource
updatedstringOptionalformat: date-time
The time when the resource was last updated
updatedBystringOptionalformat: uuid
ID of the user who last updated the resource
updatedByEmailstringOptional
Email of the user who last updated the resource
specobjectDeviceBodySpecRequired
Device specification.
Show 8 propertiesHide 8 properties
autoPreloadLatestSoftwarebooleanOptionalDefaults to false
Whether the device should automatically preload the latest available software version.
availableNetworkslist of objectsAvailableNetworkFragmentRequired
The list of <glossary:network>s available to the device and, optionally, the interfaces they are connected to. Leave the available networks list empty to give the device access to all of the networks with routes to the device's <glossary:site>. Read Available networks to learn more.
Show 2 propertiesHide 2 properties
interfaceNamestringRequiredpattern: [^\s\/]{1,16}
The name of the <<glossary:device interface>> that will be connected to the network.
networkNamestringRequiredpattern: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
The name of the <glossary:network> that will be made available to this device.
desiredSoftwareVersionstringOptional<=255 characters
The desired version of software that should be running on the device.
geolocationobjectGeolocationFragmentOptional
Optional geolocation data for the device.
Show 1 propertyHide 1 property
coordinateslist of doublesRequired0-2 items
Co-ordinates that describe the geolocation (ISO 6709), an array of two floating point numbers [latitude(North - South), longitude(East - West)]. Set an empty array to clear the geolocation.
locationIdstringOptionalpattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
The location id is the identity of the actual device that will be associated with this record. This can be used instead of the shortCode field when registering an on-prem device. The location id does not change so this can be a simpler approach for large scale system administration.
preloadSoftwareVersionstringOptional<=255 characters
A version of the software that should be preloaded on the device.
shortCodestringOptional8-8 characters
The short code from a device's web user interface, used to on-board the device. The short code expires quickly, so it should be used immediately after it is generated. Read On-board fleet devices to learn more about on-boarding devices.
siteNamestringOptionalpattern: ^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$
The name of the <glossary:site> where the device is located.
statusobjectDeviceStatusGetSchemaRequired
Device status.
Show 16 propertiesHide 16 properties
alarmSeverityenumOptional

The most severe alarm level last reported by the device.

  • 0 - Clear
  • 1 - Info
  • 2 - Warning
  • 3 - Error
  • 4 - Critical
Allowed values:01234
assignedFlowslist of objectsAssignedFlowGetSchemaOptional
The a list of the <glossary:flow> names assigned to the device.
Show 1 propertyHide 1 property
namestringRequiredpattern: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
The name of a <glossary:flow> assigned to the device.
beamHAobjectBeamHASchemaOptional
Information about the beamHA the device is connected to.
Show 4 propertiesHide 4 properties
activeControllerDeviceNamestringOptional1-64 characters
The name of the active controller device in the beamHA.
roleslist of stringsRequired0-3 items
The roles of the device in the beamHA (high availability) group.
statusstringOptional
The status of the beamHA group. Only returned for the active controller device.
unregisteredDeviceslist of stringsOptional
List of location IDs of devices that are part of the beamHA but not registered. Only returned for the active controller device.
capabilitiesobjectDeviceCapabilitiesSchemaOptional
Device capabilities based on software version and hardware.
Show 1 propertyHide 1 property
configurationBackupbooleanOptional
Whether the device supports configuration backup. Returns false for devices with beam software version older than 1.6.
currentSoftwareVersionstring or nullOptional<=255 characters
The current software version running on the device, as reported by the device.
geolocationobjectGeolocationFragmentOptional
Optional geolocation data for the device.
Show 1 propertyHide 1 property
coordinateslist of doublesRequired0-2 items
Co-ordinates that describe the geolocation (ISO 6709), an array of two floating point numbers [latitude(North - South), longitude(East - West)]. Set an empty array to clear the geolocation.
interfaceslist of objectsDeviceInterfaceSchemaOptional
A list of the physical and virtual interfaces reported by the device. If an interface is referenced directly by a source or a destination, it may be continue to be present in the list even if the device no longer reports it. The state field indicates if the interface is currently present on the device.
Show 4 propertiesHide 4 properties
ipAddresseslist of stringsOptional
The IP address associated with this interface, if applicable.
namestringRequiredpattern: ^([^\s\/]{1,16}|[a-zA-Z][a-zA-Z0-9_]{1,255})$
The name of the interface on the device.
stateenumRequired
Whether the interface is currently present on the device. If an interface is referenced directly by a source or a destination, it may be continue to be present in the list even if the device no longer reports it.
Allowed values:NotPresentPresent
typeenumRequired
The type of the physical or virtual interface on the device (IP, SDI/ASI or RF).
Allowed values:IPSDIASIRF
lastContactstring or nullOptional
The last time the device contacted the system.
locationIdstring or nullOptionalpattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
The location id is the identity of the actual device that will be associated with this record. This can be used instead of the shortCode field when registering an on-prem device. The location id does not change so this can be a simpler approach for large scale system administration.
preloadedSoftwarelist of objects or nullPreloadSoftwareInfoOptional
The preloaded software present on the device.
Show 7 propertiesHide 7 properties
downgradeCompatiblebooleanOptional
Whether switching to this release is safe from an underlying component perspective. False if this release has a lower minimum version requirement than the currently installed release. True when no suitable reference release can be found (fail open).
namestringRequired1-255 characters
The name of the preloaded software present on the device.
precentProgressintegerOptional0 to 100
Indication of coarse progress for states with a significant duration.
progressDetailsstringOptional<=255 charactersDefaults to
Additional information about states with a significant duration.
stateenumRequired
The current state of the preloaded software.
Allowed values:RequestedDownloadingDownloadedImportingPreloadFailedPreloadCancelledRemovingRemoved
upgradeCompatiblebooleanOptional
Whether the device's current software version meets the minimum version requirement for upgrading to this release. Mirrors the field on the device software list endpoint.
versionstringRequired<=255 characters
The version of the preloaded software.
rollbackSoftwareVersionstring or nullOptional<=255 characters
The rollback software version, as reported by the device.
secondsSinceLastContactinteger or nullOptional
The number of seconds since the last time the device contacted the system.
serialNumberstring or nullOptional1-255 characters
The serial number of the device, as reported by the device.
softwareNamestring or nullOptional0-255 characters
The name of the software installed on the device.
softwareUpgradeStateenumOptional
Indicates if a software upgrade is in progress or has failed.
Allowed values:IdleSwitchingSwitchFailed
urlstringOptional1-2048 characters
The URL to access the device's web interface remotely.

Errors

400 Bad Request
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
401 Unauthorized
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
403 Forbidden
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
404 Not Found
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
429 Too Many Requests
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
500 Internal Server Error
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code