Get Device

Fleets API · Devices

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.

RBAC Capability Required: fleet.device.get

Authentication

• Authorization header — Bearer authentication of the form Bearer <token>.

Path parameters

Example request

curl -X GET "https://app.mk.io/api/v1/projects/{project_name}/fleet/devices/{name}" \
  -H "Authorization: Bearer <token>"

Responses

200 — A single device

• kind · string · Required — The kind of record.
• metadata · object · Required — Device metadata.
  • created · string · Optional · format: date-time — The time when the resource was created
  • createdBy · string · Optional · format: uuid — ID of the user who created the resource
  • createdByEmail · string · Optional — Email of the user who created the resource
  • displayName · string · Optional — The display name of the resource
  • id · string · Required · format: uuid — The ID of the resource
  • labels · map from strings to string · Optional — A dictionary of labels associated with the resource
    • [any key] · string — map of additional properties
  • name · string · Optional — The name of the resource
  • updated · string · Optional · format: date-time — The time when the resource was last updated
  • updatedBy · string · Optional · format: uuid — ID of the user who last updated the resource
  • updatedByEmail · string · Optional — Email of the user who last updated the resource
• spec · object · Required — Device specification.
  • autoPreloadLatestSoftware · boolean · Optional · Defaults to false — Whether the device should automatically preload the latest available software version.
  • availableNetworks · list of objects · Required — 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.
    • Array items (object):
      • interfaceName · string · Required · pattern: [^\s/]{1,16} — The name of the <<glossary:device interface>> that will be connected to the network.
      • networkName · string · Required · pattern: ^a-z0-9?$ — The name of the <glossary:network> that will be made available to this device.
  • desiredSoftwareVersion · string · Optional · <=255 characters — The desired version of software that should be running on the device.
  • geolocation · object · Optional — Optional geolocation data for the device.
    • coordinates · list of doubles · Required · 0-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.
      • Array items (double):
  • locationId · string · Optional · pattern: ^[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.
  • preloadSoftwareVersion · string · Optional · <=255 characters — A version of the software that should be preloaded on the device.
  • shortCode · string · Optional · 8-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.
  • siteName · string · Optional · pattern: ^(a-z0-9?)?$ — The name of the <glossary:site> where the device is located.
• status · object · Required — Device status.
  • alarmSeverity · enum · Optional — The most severe alarm level last reported by the device. - 0 - Clear - 1 - Info - 2 - Warning - 3 - Error - 4 - Critical
    • Allowed values: 0, 1, 2, 3, 4
  • assignedFlows · list of objects · Optional — The a list of the <glossary:flow> names assigned to the device.
    • Array items (object):
      • name · string · Required · pattern: ^a-z0-9?$ — The name of a <glossary:flow> assigned to the device.
  • beamHA · object · Optional — Information about the beamHA the device is connected to.
    • activeControllerDeviceName · string · Optional · 1-64 characters — The name of the active controller device in the beamHA.
    • roles · list of strings · Required · 0-3 items — The roles of the device in the beamHA (high availability) group.
      • Array items (string):
    • status · string · Optional — The status of the beamHA group. Only returned for the active controller device.
    • unregisteredDevices · list of strings · Optional — List of location IDs of devices that are part of the beamHA but not registered. Only returned for the active controller device.
      • Array items (string):
  • capabilities · object · Optional — Device capabilities based on software version and hardware.
    • configurationBackup · boolean · Optional — Whether the device supports configuration backup. Returns false for devices with beam software version older than 1.6.
  • currentSoftwareVersion · string or null · Optional · <=255 characters — The current software version running on the device, as reported by the device.
  • geolocation · object · Optional — Optional geolocation data for the device.
    • coordinates · list of doubles · Required · 0-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.
      • Array items (double):
  • interfaces · list of objects · Optional — 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.
    • Array items (object):
      • ipAddresses · list of strings · Optional — The IP address associated with this interface, if applicable.
        • Array items (string):
      • name · string · Required · _pattern: ^([^

\s/]{1,16}|[a-zA-Z][a-zA-Z0-9_]{1,255})$_ — The name of the interface on the device.
- state · enum · Required — 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: NotPresent, Present
- type · enum · Required — The type of the physical or virtual interface on the device (IP, SDI/ASI or RF).
- Allowed values: IP, SDIASI, RF

• lastContact · string or null · Optional — The last time the device contacted the system.
• locationId · string or null · Optional · pattern: ^[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.
• preloadedSoftware · list of objects or null · Optional — The preloaded software present on the device.
  • Array items (object):
    • downgradeCompatible · boolean · Optional — 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).
    • name · string · Required · 1-255 characters — The name of the preloaded software present on the device.
    • precentProgress · integer · Optional · 0 to 100 — Indication of coarse progress for states with a significant duration.
    • progressDetails · string · Optional · <=255 characters · _Defaults to _ — Additional information about states with a significant duration.
    • state · enum · Required — The current state of the preloaded software.
      • Allowed values: Requested, Downloading, Downloaded, Importing, PreloadFailed, PreloadCancelled, Removing, Removed
    • upgradeCompatible · boolean · Optional — 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.
    • version · string · Required · <=255 characters — The version of the preloaded software.
• rollbackSoftwareVersion · string or null · Optional · <=255 characters — The rollback software version, as reported by the device.
• secondsSinceLastContact · integer or null · Optional — The number of seconds since the last time the device contacted the system.
• serialNumber · string or null · Optional · 1-255 characters — The serial number of the device, as reported by the device.
• softwareName · string or null · Optional · 0-255 characters — The name of the software installed on the device.
• softwareUpgradeState · enum · Optional — Indicates if a software upgrade is in progress or has failed.
  • Allowed values: Idle, Switching, SwitchFailed
• url · string · Optional · 1-2048 characters — The URL to access the device's web interface remotely.