Class DeviceManagementAPI

Cancel device migration

Cancels an ongoing device migration process for one or more UniFi devices. This stops the migration and returns devices to their previous state.

Throws

When MAC address validation fails

Throws

When migration cancellation fails

Example

// Cancel migration for single device
await client.cancel_migrate_device('aa:bb:cc:dd:ee:ff');

// Cancel migration for multiple devices
await client.cancel_migrate_device([
  'aa:bb:cc:dd:ee:ff',
  'ff:ee:dd:cc:bb:aa'
]);
Copy

See

• migrate_device to start device migration
• list_devices to get device information

PHP: cancel_migrate_device($macs) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr', $payload);

Cancel rolling upgrade

Cancels an ongoing rolling upgrade process for UniFi devices. This stops the automatic firmware upgrade sequence across devices.

Throws

When rolling upgrade cancellation fails

Example

// Cancel ongoing rolling upgrade
await client.cancel_rolling_upgrade();

// With cancellation support
const controller = new AbortController();
await client.cancel_rolling_upgrade({ signal: controller.signal });
Copy

See

• start_rolling_upgrade to start a rolling upgrade
• check_firmware_update to check for available updates

PHP: cancel_rolling_upgrade() -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr', $payload);

Check for firmware updates

Initiates a check for available firmware updates for all UniFi devices in the site. This triggers the controller to query for new firmware versions.

Throws

When firmware update check fails

Example

// Check for firmware updates
await client.check_firmware_update();

// Then list devices to see available updates
const devices = await client.list_devices();
const devicesWithUpdates = devices.filter(device => device.upgradable);
Copy

See

• list_devices to see which devices have available updates
• upgrade_device to upgrade specific devices
• start_rolling_upgrade to upgrade all devices automatically

PHP: check_firmware_update() -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr', $payload);

List UniFi devices (Access Points, Switches, Gateways, etc.)

Description

Retrieves information about UniFi devices in the network. Can optionally filter by specific MAC addresses. When no MAC addresses are provided, returns all devices.

Example

// Get all devices
const allDevices = await client.list_devices();

// Get specific device by MAC
const device = await client.list_devices('aa:bb:cc:dd:ee:ff');

// Get multiple devices by MAC
const devices = await client.list_devices(['aa:bb:cc:dd:ee:ff', 'ff:ee:dd:cc:bb:aa']);

// Filter access points only
const allDevices = await client.list_devices();
const accessPoints = allDevices.filter(device => device.type === 'uap');
Copy

See

• list_devices_basic for basic device information (faster)
• adopt_device to adopt new devices

Since

1.0.0

Remarks

PHP: list_devices($macs = []) -> return $this->fetch_results('/api/s/' . $this->site . '/stat/device', $payload);

Adopt one or more UniFi devices to the current site

Description

Adopts UniFi devices (Access Points, Switches, Gateways) to the current site. Devices must be in an adoptable state (showing as pending adoption in the controller).

Throws

When MAC address format is invalid

Throws

When device is not in adoptable state or already adopted

Example

// Adopt single device
await client.adopt_device('aa:bb:cc:dd:ee:ff');

// Adopt multiple devices
await client.adopt_device(['aa:bb:cc:dd:ee:ff', 'ff:ee:dd:cc:bb:aa']);

// With error handling
try {
  await client.adopt_device('aa:bb:cc:dd:ee:ff');
  console.log('Device adopted successfully');
} catch (error) {
  console.error('Adoption failed:', error.message);
}
Copy

See

• advanced_adopt_device for adoption with custom SSH credentials
• list_devices to check device status after adoption

Since

1.0.0

Remarks

PHP: adopt_device($macs) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr', $payload);

Adopt a device using custom SSH credentials

Description

Adopts a UniFi device using custom SSH credentials for advanced scenarios where the device requires specific authentication parameters.

Throws

When required parameters are missing or invalid

Throws

When advanced adoption fails

Example

// Advanced adoption with custom credentials
await client.advanced_adopt_device(
  'aa:bb:cc:dd:ee:ff',
  '192.168.1.100',
  'ubnt',
  'ubnt',
  'https://controller.example.com:8443',
  22,
  true
);
Copy

See

adopt_device for standard device adoption

Since

1.0.0

Remarks

PHP: advanced_adopt_device($mac, $ip, $username, $password, $url, $port = 22, $ssh_key_verify = true)

Delete device

Permanently removes a device from the UniFi Controller. This operation cannot be undone and the device will need to be re-adopted.

Throws

When MAC address validation fails

Throws

When device deletion fails

Example

// Delete a device by MAC address
await client.delete_device('aa:bb:cc:dd:ee:ff');
Copy

Warning

This operation is irreversible

See

• list_devices to get device MAC addresses
• adopt_device to re-adopt deleted devices

PHP: delete_device($mac)

Disable access point

Disables or enables an Access Point device. When disabled, the AP will stop broadcasting wireless networks.

Throws

When ap_id validation fails

Throws

When AP disable/enable fails

Example

// Disable an Access Point
await client.disable_ap('507f1f77bcf86cd799439011', true);

// Enable an Access Point
await client.disable_ap('507f1f77bcf86cd799439011', false);
Copy

See

• list_devices to get AP device IDs
• restart_device to restart disabled APs

PHP: disable_ap($ap_id, $disable) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/device/' . trim($ap_id), $payload);

Force provision device

Forces provisioning of one or more UniFi devices. This triggers the device to re-download its configuration from the controller.

Throws

When MAC address validation fails

Throws

When force provision fails

Example

// Force provision single device
await client.force_provision('aa:bb:cc:dd:ee:ff');

// Force provision multiple devices
await client.force_provision([
  'aa:bb:cc:dd:ee:ff',
  'ff:ee:dd:cc:bb:aa'
]);
Copy

See

• list_devices to get device MAC addresses
• restart_device for device restart operations

PHP: force_provision($mac) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr/', $payload);

List access point groups

Retrieves all Access Point groups configured in the site. AP groups allow organizing and managing multiple APs together.

Throws

When AP group listing fails

Example

// List all AP groups
const apGroups = await client.list_apgroups();
console.log(`Found ${apGroups.length} AP groups`);

// Find specific AP group
const mainGroup = apGroups.find(group => group.name === 'Main Building');
Copy

See

• create_apgroup to create new AP groups
• delete_apgroup to remove AP groups

PHP: list_apgroups() -> return $this->fetch_results('/v2/api/site/' . $this->site . '/apgroups');

List access points

Retrieves information about Access Point devices. Can optionally filter by specific MAC address.

Throws

When AP listing fails

Example

// List all Access Points
const aps = await client.list_aps();

// Get specific AP by MAC
const ap = await client.list_aps('aa:bb:cc:dd:ee:ff');
Copy

See

• list_devices for all device types
• adopt_device to adopt new APs

PHP: list_aps($mac = '') -> return $this->fetch_results('/api/s/' . $this->site . '/stat/device', $payload);

List device name mappings

Retrieves device name mappings from the controller. This shows custom names assigned to devices.

Throws

When device name mapping retrieval fails

Example

// Get device name mappings
const mappings = await client.list_device_name_mappings();
Copy

See

• rename_ap to rename devices
• list_devices to get device information

PHP: list_device_name_mappings() -> return $this->fetch_results('/api/s/' . $this->site . '/stat/device-name-mapping');

List device states

Retrieves current state information for all devices. This includes connection status and operational state.

Throws

When device state retrieval fails

Example

// Get device states
const states = await client.list_device_states();
Copy

See

• list_devices for detailed device information
• stat_sysinfo for system status

PHP: list_device_states() -> return $this->fetch_results('/api/s/' . $this->site . '/stat/device-state');

List devices (basic information)

Retrieves basic device information with reduced data payload. Faster than full device listing for simple operations.

Throws

When basic device listing fails

Example

// Get basic info for all devices
const devices = await client.list_devices_basic();

// Get basic info for specific device
const device = await client.list_devices_basic('aa:bb:cc:dd:ee:ff');
Copy

See

list_devices for complete device information

PHP: list_devices_basic($device_mac = '') -> return $this->fetch_results('/api/s/' . $this->site . '/stat/device-basic', $payload);

List available firmware versions

Retrieves available firmware versions for devices. Can optionally filter by device type.

Throws

When firmware listing fails

Example

// List all available firmware
const firmware = await client.list_firmware();

// List firmware for specific device type
const apFirmware = await client.list_firmware('uap');
Copy

See

• check_firmware_update to check for updates
• upgrade_device to upgrade device firmware

PHP: list_firmware($device_type = '') -> return $this->fetch_results('/api/s/' . $this->site . '/stat/firmware', $payload);

List device models

Retrieves information about supported device models. This includes model names, capabilities, and specifications.

Throws

When device model listing fails

Example

// Get supported device models
const models = await client.list_models();
Copy

See

list_devices to see actual devices

PHP: list_models() -> return $this->fetch_results('/api/s/' . $this->site . '/stat/device-model');

Locate access point (LED blink)

Enables or disables the locate LED feature on an Access Point. When enabled, the AP's LED will blink to help physically locate the device.

Throws

When MAC address validation fails

Throws

When locate operation fails

Example

// Enable locate mode (LED blinks)
await client.locate_ap('aa:bb:cc:dd:ee:ff', true);

// Disable locate mode
await client.locate_ap('aa:bb:cc:dd:ee:ff', false);
Copy

See

• led_override for permanent LED control
• list_aps to get AP MAC addresses

PHP: locate_ap($mac, $enable) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr', $payload);

Migrate device to another controller

Migrates one or more UniFi devices to a different controller. The devices will be removed from the current controller and adopted by the target.

Throws

When MAC address or inform_url validation fails

Throws

When device migration fails

Example

// Migrate single device
await client.migrate_device(
  'aa:bb:cc:dd:ee:ff',
  'http://new-controller.example.com:8080/inform'
);

// Migrate multiple devices
await client.migrate_device(
  ['aa:bb:cc:dd:ee:ff', 'ff:ee:dd:cc:bb:aa'],
  'http://new-controller.example.com:8080/inform'
);
Copy

See

• cancel_migrate_device to cancel ongoing migration
• list_devices to get device MAC addresses

PHP: migrate_device($macs, $inform_url) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr', $payload);

Power cycle switch port

Power cycles a specific port on a UniFi switch. This turns the port off and then back on to reset connected devices.

Throws

When MAC address or port_idx validation fails

Throws

When power cycle fails

Example

// Power cycle port 8 on a switch
await client.power_cycle_switch_port('aa:bb:cc:dd:ee:ff', 8);
Copy

See

• list_devices to get switch MAC addresses
• restart_device to restart the entire switch

PHP: power_cycle_switch_port($mac, $port_idx) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr', $payload);

Reboot Cloud Key

Reboots the UniFi Cloud Key device. This will temporarily interrupt controller services.

Throws

When Cloud Key reboot fails

Example

// Reboot the Cloud Key
await client.reboot_cloudkey();
Copy

Warning

This will temporarily interrupt controller services

See

restart_device to restart other devices

PHP: reboot_cloudkey() -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/system', $payload);

Rename access point

Changes the name of an Access Point device. The new name will be displayed in the controller interface.

Throws

When ap_id or ap_name validation fails

Throws

When AP rename fails

Example

// Rename an Access Point
await client.rename_ap('507f1f77bcf86cd799439011', 'Main Office AP');
Copy

See

• list_devices to get AP device IDs
• list_device_name_mappings to see current names

PHP: rename_ap($ap_id, $ap_name) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/upd/device/' . trim($ap_id), $payload);

Restart access point (deprecated)

Deprecated

Use restart_device() instead

PHP: restart_ap() -> throw new MethodDeprecatedException('Function restart_ap() has been deprecated, use restart_device() instead.');

Restart device

Restarts one or more UniFi devices. Can perform either soft restart (graceful) or hard restart (forced).

Throws

When MAC address validation fails

Throws

When device restart fails

Example

// Soft restart single device
await client.restart_device('aa:bb:cc:dd:ee:ff');

// Hard restart multiple devices
await client.restart_device(
  ['aa:bb:cc:dd:ee:ff', 'ff:ee:dd:cc:bb:aa'],
  'hard'
);
Copy

See

• list_devices to get device MAC addresses
• reboot_cloudkey to restart Cloud Key

PHP: restart_device($macs, $reboot_type = 'soft') -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr', $payload);

Set access point WLAN group

Assigns an Access Point to a specific WLAN group for radio configuration. This controls which wireless networks are broadcast on which radios.

Throws

When parameter validation fails

Throws

When WLAN group assignment fails

Example

// Assign 2.4GHz radio to a WLAN group
await client.set_ap_wlangroup(
  'ng',
  '507f1f77bcf86cd799439011',
  'wlan-group-id'
);

// Assign 5GHz radio to a different WLAN group
await client.set_ap_wlangroup(
  'na',
  '507f1f77bcf86cd799439011',
  'another-wlan-group-id'
);
Copy

See

• list_devices to get AP device IDs
• list_wlan_groups to get WLAN group IDs

PHP: set_ap_wlangroup($type_id, $device_id, $group_id) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/upd/device/' . trim($device_id), $payload);

Set device settings (base method)

Updates device settings using a custom payload. This is a low-level method for advanced device configuration.

Throws

When device_id or payload validation fails

Throws

When device settings update fails

Example

// Update device settings with custom payload
await client.set_device_settings_base(
  '507f1f77bcf86cd799439011',
  {
    name: 'New Device Name',
    led_override: 'off'
  }
);
Copy

See

• list_devices to get device IDs
• rename_ap for device naming
• led_override for LED control

PHP: set_device_settings_base($device_id, $payload) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/device/' . trim($device_id), $payload);

Set element adoption

Enables or disables automatic device adoption for the site. When enabled, new devices will be automatically adopted.

Throws

When element adoption setting update fails

Example

// Enable automatic device adoption
await client.set_element_adoption(true);

// Disable automatic device adoption
await client.set_element_adoption(false);
Copy

See

adopt_device for manual device adoption

PHP: set_element_adoption($enable) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/set/setting/element_adopt', $payload);

Start rolling upgrade

Initiates a rolling firmware upgrade for specified device types. Devices will be upgraded automatically in sequence to minimize downtime.

Throws

When rolling upgrade start fails

Example

// Start rolling upgrade for all device types
await client.start_rolling_upgrade();

// Start rolling upgrade for specific device types
await client.start_rolling_upgrade(['uap', 'usw']);
Copy

See

• cancel_rolling_upgrade to cancel ongoing upgrade
• check_firmware_update to check for available updates

PHP: start_rolling_upgrade($payload = ['uap', 'usw', 'ugw', 'uxg']) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr/set-rollupgrade', $payload);

Unset locate access point (deprecated)

Deprecated

Use locate_ap() instead

PHP: unset_locate_ap() -> throw new MethodDeprecatedException('Function unset_locate_ap() has been deprecated, use locate_ap() instead.');

Upgrade all devices

Initiates firmware upgrade for all devices of a specified type. This upgrades all devices simultaneously rather than in sequence.

Throws

When device upgrade fails

Example

// Upgrade all Access Points
await client.upgrade_all_devices('uap');

// Upgrade all switches
await client.upgrade_all_devices('usw');
Copy

See

• upgrade_device to upgrade specific devices
• start_rolling_upgrade for sequential upgrades

PHP: upgrade_all_devices($type = 'uap') -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr/upgrade-all', $payload);

Upgrade device

Initiates firmware upgrade for a specific device. The device will download and install the latest available firmware.

Throws

When MAC address validation fails

Throws

When device upgrade fails

Example

// Upgrade specific device
await client.upgrade_device('aa:bb:cc:dd:ee:ff');
Copy

See

• upgrade_all_devices to upgrade all devices of a type
• check_firmware_update to check for available updates

PHP: upgrade_device($mac) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr/upgrade', $payload);

Upgrade device with external firmware

Upgrades one or more devices using firmware from an external URL. This allows using custom or beta firmware versions.

Throws

When firmware_url or MAC address validation fails

Throws

When external upgrade fails

Example

// Upgrade single device with external firmware
await client.upgrade_device_external(
  'https://firmware.example.com/device-firmware.bin',
  'aa:bb:cc:dd:ee:ff'
);

// Upgrade multiple devices with external firmware
await client.upgrade_device_external(
  'https://firmware.example.com/device-firmware.bin',
  ['aa:bb:cc:dd:ee:ff', 'ff:ee:dd:cc:bb:aa']
);
Copy

Warning

Use only trusted firmware sources

See

• upgrade_device for standard firmware upgrades
• list_firmware to see available firmware versions

PHP: upgrade_device_external($firmware_url, $macs) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr/upgrade-external', $payload);

Create access point group

Creates a new Access Point group for organizing and managing multiple APs together. AP groups allow applying common settings and configurations to multiple devices.

Throws

When group_name validation fails

Throws

When AP group creation fails

Example

// Create empty AP group
await client.create_apgroup('Main Building APs');

// Create AP group with devices
await client.create_apgroup('Office APs', [
  'aa:bb:cc:dd:ee:ff',
  'ff:ee:dd:cc:bb:aa'
]);
Copy

See

• list_apgroups to list existing AP groups
• edit_apgroup to modify AP groups
• delete_apgroup to remove AP groups

PHP: create_apgroup($group_name, $device_macs = []) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/apgroup', $payload);

Delete access point group

Permanently removes an Access Point group from the controller. Devices in the group will be moved to the default group.

Throws

When group_id validation fails

Throws

When AP group deletion fails

Example

// Delete an AP group
await client.delete_apgroup('507f1f77bcf86cd799439011');
Copy

Warning

This operation cannot be undone

See

• list_apgroups to get AP group IDs
• create_apgroup to create new AP groups

PHP: delete_apgroup($group_id) -> return $this->fetch_results_boolean('/v2/api/site/' . $this->site . '/apgroups/' . trim($group_id));

Edit access point group

Updates an existing Access Point group with new name and device assignments. This allows modifying group membership and properties.

Throws

When parameter validation fails

Throws

When AP group edit fails

Example

// Update AP group name and devices
await client.edit_apgroup(
  '507f1f77bcf86cd799439011',
  'Updated Office APs',
  ['aa:bb:cc:dd:ee:ff', 'ff:ee:dd:cc:bb:aa']
);
Copy

See

• list_apgroups to get AP group IDs
• create_apgroup to create new AP groups
• delete_apgroup to remove AP groups

PHP: edit_apgroup($group_id, $group_name, $device_macs) -> return $this->fetch_results('/v2/api/site/' . $this->site . '/apgroups/' . trim($group_id), $payload);