Create Device

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

Create a device. To learn more about devices, read Device Concept.

RBAC Capability Required: fleet.device.create

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

Request

This endpoint expects an object.

metadata object DefaultMetadata Required

Resource metadata.

• displayName string Required

A human-readable name for the resource.

• labels map from strings to string Optional

A dictionary of labels associated with the resource. Maximum number of labels: 32. Maximum length of a label or value: 256 characters. Label: alphanumeric, hyphens, and underscores. Value: alphanumeric, hyphens, underscores, and spaces.

[any key] string

spec object DeviceBodySpec Required

Device specification.

• autoPreloadLatestSoftware boolean Optional Defaults to false

Whether the device should automatically preload the latest available software version.

• availableNetworks list of objects AvailableNetworkFragment Required

The list of glossary:networks 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.

• 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]([a-z0-9-]{0,61}[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 GeolocationFragment 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.

• 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]([a-z0-9-]{0,61}[a-z0-9])?)?$

The name of the glossary:site\ where the device is located.

Response

201 The created device

• kind string Required

The kind of record.

• metadata object MetadataSchema 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

• 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 DeviceBodySpec Required

Device specification.

• autoPreloadLatestSoftware boolean Optional Defaults to false

Whether the device should automatically preload the latest available software version.

• availableNetworks list of objects AvailableNetworkFragment Required

• 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]([a-z0-9-]{0,61}[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 GeolocationFragment Optional

Optional geolocation data for the device.

• coordinates list of doubles Required 0-2 items

• status object DeviceStatusGetSchema 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: 01234

• assignedFlows list of objects AssignedFlowGetSchema Optional

The a list of the glossary:flow\ names assigned to the device.

• name string Required pattern: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

The name of a glossary:flow assigned to the device.

• beamHA object BeamHASchema 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.

• 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.

• capabilities object DeviceCapabilitiesSchema 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.

• interfaces list of objects DeviceInterfaceSchema 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 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.

• ipAddresses list of strings Optional

The IP address associated with this interface, if applicable.

• 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 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: IPSDIASIRF

• 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}$

• preloadedSoftware list of objects or null PreloadSoftwareInfo Optional

The preloaded software present on the device.

Errors

• 400 Bad Request
  • error object ErrorDetail Required

Pertinent information about the error

• code string Required

  • detail string Required
  • extraDetail map from strings to any Optional
  • ref string Required
  • status integer Required

• 401 Unauthorized

  • error object ErrorDetail Required

Pertinent information about the error

• code string Required

  • detail string Required
  • extraDetail map from strings to any Optional
  • ref string Required
  • status integer Required

• 403 Forbidden

  • error object ErrorDetail Required

Pertinent information about the error

• code string Required

  • detail string Required
  • extraDetail map from strings to any Optional
  • ref string Required
  • status integer Required

• 404 Not Found

  • error object ErrorDetail Required

Pertinent information about the error

• code string Required

  • detail string Required
  • extraDetail map from strings to any Optional
  • ref string Required
  • status integer Required

• 409 Conflict

  • error object ErrorDetail Required

Pertinent information about the error

• code string Required

  • detail string Required
  • extraDetail map from strings to any Optional
  • ref string Required
  • status integer Required

• 429 Too Many Requests

  • error object ErrorDetail Required

Pertinent information about the error

• code string Required

  • detail string Required
  • extraDetail map from strings to any Optional
  • ref string Required
  • status integer Required

• 500 Internal Server Error

  • error object ErrorDetail Required

Pertinent information about the error

• code string Required
  • detail string Required
  • extraDetail map from strings to any Optional
  • ref string Required
  • status integer Required