Class SiteManagementAPI

Download backup

Downloads a backup file from the specified filepath. This method returns raw backup data that should be saved to a file. The filepath is typically obtained from list_backups().

Throws

When filepath is empty or invalid

Throws

When backup download fails

Example

// List available backups first
const backups = await client.list_backups();

// Download the most recent backup
if (backups.length > 0) {
  const backupData = await client.download_backup(backups[0].filename);
  // Save backupData to file system
}

// Download specific backup with error handling
try {
  const backupData = await client.download_backup('/path/to/backup.unf');
  console.log('Backup downloaded successfully');
} catch (error) {
  console.error('Failed to download backup:', error.message);
}
Copy

See

• list_backups to get available backup files
• generate_backup to create a new backup

Since

1.0.0

Remarks

PHP: download_backup($filepath) -> return $this->exec_curl($filepath); Note: This method returns raw backup data that should be saved to a file

Generate backup

Initiates the creation of a new backup for the current site. The backup process runs asynchronously on the controller. Use list_backups() to check for completion.

Throws

When backup generation fails to start

Example

// Generate a new backup
await client.generate_backup();
console.log('Backup generation started');

// Wait and check for completion
setTimeout(async () => {
  const backups = await client.list_backups();
  console.log(`Found ${backups.length} backups`);
}, 30000); // Check after 30 seconds

// Generate backup with error handling
try {
  await client.generate_backup();
  console.log('Backup generation initiated successfully');
} catch (error) {
  console.error('Failed to start backup generation:', error.message);
}
Copy

See

• list_backups to check backup status
• download_backup to download completed backups
• generate_backup_site for site-specific backup generation

Since

1.0.0

Remarks

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

Generate backup for site

Initiates the creation of a new backup specifically for the current site. This is functionally identical to generate_backup() but explicitly targets site-level backup generation.

Throws

When site backup generation fails to start

Example

// Generate a site-specific backup
await client.generate_backup_site();
console.log('Site backup generation started');

// Generate backup for current site with monitoring
try {
  await client.generate_backup_site();
  
  // Poll for completion
  const checkBackup = async () => {
    const backups = await client.list_backups();
    const latestBackup = backups[0];
    if (latestBackup && Date.now() - latestBackup.datetime < 60000) {
      console.log('New backup completed:', latestBackup.filename);
    } else {
      setTimeout(checkBackup, 5000); // Check again in 5 seconds
    }
  };
  
  setTimeout(checkBackup, 10000); // Start checking after 10 seconds
} catch (error) {
  console.error('Failed to start site backup:', error.message);
}
Copy

See

• generate_backup for general backup generation
• list_backups to check backup status
• download_backup to download completed backups

Since

1.0.0

Remarks

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

List available backups

Retrieves a list of all available backup files for the current site. Each backup entry includes metadata such as filename, size, and creation date.

Throws

When backup listing fails

Example

// List all available backups
const backups = await client.list_backups();
console.log(`Found ${backups.length} backups`);

// Display backup information
backups.forEach(backup => {
  console.log(`Backup: ${backup.filename}`);
  console.log(`Size: ${backup.size} bytes`);
  console.log(`Created: ${new Date(backup.datetime * 1000).toLocaleString()}`);
});

// Find most recent backup
const sortedBackups = backups.sort((a, b) => b.datetime - a.datetime);
const latestBackup = sortedBackups[0];
if (latestBackup) {
  console.log(`Latest backup: ${latestBackup.filename}`);
}

// Filter backups by age
const oneWeekAgo = Date.now() / 1000 - (7 * 24 * 60 * 60);
const recentBackups = backups.filter(backup => backup.datetime > oneWeekAgo);
console.log(`${recentBackups.length} backups from the last week`);
Copy

See

• generate_backup to create new backups
• download_backup to download backup files

Since

1.0.0

Remarks

PHP: list_backups() -> return $this->fetch_results('/api/s/' . $this->site . '/cmd/backup', $payload);

Creates a new Site Management API instance

Turn off site LEDs

Deprecated

This method is deprecated. Use site_leds(false) instead.

Example

// Instead of:
await client.site_ledsoff();

// Use:
await client.site_leds(false);
Copy

Since

1.0.0

Remarks

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

Turn on site LEDs

Deprecated

This method is deprecated. Use site_leds(true) instead.

Example

// Instead of:
await client.site_ledson();

// Use:
await client.site_leds(true);
Copy

Since

1.0.0

Remarks

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

Update site connectivity settings

Updates connectivity-related settings for the site such as uplink monitoring, internet connectivity checks, and related network connectivity configurations.

Throws

When connectivity_id is empty or invalid

Throws

When connectivity settings update fails

Example

// Update connectivity monitoring settings
await client.set_site_connectivity('connectivity', {
  uplink_connectivity_monitor_enabled: true,
  internet_connectivity_monitor_enabled: true
});
Copy

Since

1.0.0

Remarks

PHP: set_site_connectivity($connectivity_id, $payload) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/connectivity/' . trim($connectivity_id), $payload);

Update site country settings

Updates country-specific settings for the site including regulatory domain, channel restrictions, and power limitations based on local regulations.

Throws

When country_id is empty or invalid

Throws

When country settings update fails

Example

// Update country settings for US
await client.set_site_country('country', {
  code: 'US',
  name: 'United States'
});
Copy

Since

1.0.0

Remarks

PHP: set_site_country($country_id, $payload) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/country/' . trim($country_id), $payload);

Update site guest access settings

Updates guest network access settings including portal configuration, authentication methods, bandwidth limits, and access restrictions.

Throws

When guest_access_id is empty or invalid

Throws

When guest access settings update fails

Example

// Update guest portal settings
await client.set_site_guest_access('guest_access', {
  portal_enabled: true,
  portal_customized: false,
  redirect_enabled: false
});
Copy

Since

1.0.0

Remarks

PHP: set_site_guest_access($guest_access_id, $payload) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/guest_access/' . trim($guest_access_id), $payload);

Update site locale settings

Updates locale-specific settings for the site including language, timezone, date/time formats, and regional preferences.

Throws

When locale_id is empty or invalid

Throws

When locale settings update fails

Example

// Update timezone settings
await client.set_site_locale('locale', {
  timezone: 'America/New_York'
});
Copy

Since

1.0.0

Remarks

PHP: set_site_locale($locale_id, $payload) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/locale/' . trim($locale_id), $payload);

Update site management settings

Updates general management settings for the site including LED control, SSH access, SNMP settings, and other administrative configurations.

Throws

When mgmt_id is empty or invalid

Throws

When management settings update fails

Example

// Update LED settings
await client.set_site_mgmt('mgmt', {
  led_enabled: true,
  x_ssh_enabled: false
});
Copy

Since

1.0.0

Remarks

PHP: set_site_mgmt($mgmt_id, $payload) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/mgmt/' . trim($mgmt_id), $payload);

Update site NTP settings

Updates Network Time Protocol (NTP) settings for the site including NTP servers, time synchronization preferences, and related time settings.

Throws

When ntp_id is empty or invalid

Throws

When NTP settings update fails

Example

// Update NTP server settings
await client.set_site_ntp('ntp', {
  ntp_server_1: 'pool.ntp.org',
  ntp_server_2: 'time.google.com'
});
Copy

Since

1.0.0

Remarks

PHP: set_site_ntp($ntp_id, $payload) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/ntp/' . trim($ntp_id), $payload);

Update site SNMP settings

Updates Simple Network Management Protocol (SNMP) settings for the site including SNMP community strings, access controls, and monitoring configuration.

Throws

When snmp_id is empty or invalid

Throws

When SNMP settings update fails

Example

// Update SNMP community settings
await client.set_site_snmp('snmp', {
  snmp_community: 'public',
  snmp_contact: 'admin@company.com',
  snmp_location: 'Main Office'
});
Copy

Since

1.0.0

Remarks

PHP: set_site_snmp($snmp_id, $payload) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/snmp/' . trim($snmp_id), $payload);

Enable or disable site LEDs

Controls the LED status for all devices in the site. This is useful for identifying devices in a physical location or reducing light pollution.

Throws

When LED control fails

Example

// Turn on all site LEDs
await client.site_leds(true);

// Turn off all site LEDs
await client.site_leds(false);

// Toggle LEDs based on time of day
const isNightTime = new Date().getHours() > 22 || new Date().getHours() < 6;
await client.site_leds(!isNightTime);
Copy

See

• site_ledson for turning LEDs on (deprecated)
• site_ledsoff for turning LEDs off (deprecated)

Since

1.0.0

Remarks

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

Create a new site

Creates a new site in the UniFi Controller with the specified description. Sites are used to organize and manage different network locations or segments.

Throws

When description is empty or invalid

Throws

When site creation fails

Example

// Create a new site
const newSite = await client.create_site('Branch Office - Seattle');
console.log(`Created site: ${newSite.name}`);

// Create site with error handling
try {
  await client.create_site('Remote Office');
  console.log('Site created successfully');
} catch (error) {
  console.error('Failed to create site:', error.message);
}
Copy

See

• list_sites to view all sites
• delete_site to remove a site
• set_site_name to update site name

Since

1.0.0

Remarks

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

Delete a site

Permanently removes a site and all its associated data from the UniFi Controller. This operation cannot be undone and will remove all devices, clients, settings, and historical data associated with the site.

Throws

When site_id is empty or invalid

Throws

When site deletion fails or site doesn't exist

Example

// Delete a site by ID
await client.delete_site('default');

// Find and delete site by description
const sites = await client.list_sites();
const oldSite = sites.find(site => site.desc === 'Old Branch Office');
if (oldSite) {
  await client.delete_site(oldSite.name);
}
Copy

Warning

This operation is irreversible and removes all site data

See

• list_sites to get site IDs
• create_site to create a new site

Since

1.0.0

Remarks

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

List all accessible sites

Retrieves a list of all sites that the current user has access to. Each site object contains information about the site including its name, description, and various configuration details.

Throws

When site listing fails

Example

// Get all accessible sites
const sites = await client.list_sites();
console.log(`Found ${sites.length} sites`);

// Find a specific site by description
const mainSite = sites.find(site => site.desc === 'Main Office');
if (mainSite) {
  console.log(`Main site ID: ${mainSite.name}`);
}

// List site names and descriptions
sites.forEach(site => {
  console.log(`${site.name}: ${site.desc}`);
});
Copy

See

• create_site to create a new site
• delete_site to remove a site
• set_site to switch to a different site

Since

1.0.0

Remarks

PHP: list_sites() -> return $this->fetch_results('/api/self/sites');

Set current site for API operations

Sets the current site context for subsequent API calls. This method is used to switch between different sites when managing multiple locations. Note: This is a client-side operation that affects which site subsequent API calls will target.

Throws

When site name is empty or invalid

Example

// Switch to default site
client.set_site('default');

// Switch to branch office site
client.set_site('branch-office');

// Get current site after switching
const currentSite = client.set_site('new-site');
console.log(`Now using site: ${currentSite}`);

// Switch sites for different operations
client.set_site('site1');
const site1Devices = await client.list_devices();

client.set_site('site2');
const site2Devices = await client.list_devices();
Copy

See

• list_sites to get available site names
• create_site to create a new site

Since

1.0.0

Remarks

PHP: set_site($site) -> $this->site = trim($site); return $this->site; Note: This method sets the current site for subsequent API calls

Update site name

Updates the display name/description of the current site. This changes how the site appears in the controller interface.

Throws

When site_name is empty or invalid

Throws

When site name update fails

Example

// Update site display name
await client.set_site_name('Main Office - New York');

// Update with descriptive name
await client.set_site_name('Branch Office - Los Angeles');
Copy

See

• list_sites to see current site names
• create_site to create a new site with a name

Since

1.0.0

Remarks

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

List site settings

Retrieves all configuration settings for the current site including management settings, connectivity options, locale preferences, and other site-specific configuration parameters.

Throws

When settings retrieval fails

Example

// Get all site settings
const settings = await client.list_settings();

// Find specific setting by key
const mgmtSettings = settings.find(setting => setting.key === 'mgmt');
if (mgmtSettings) {
  console.log('Management settings:', mgmtSettings);
}

// Display all setting keys
settings.forEach(setting => {
  console.log(`Setting: ${setting.key}`);
});
Copy

See

• set_site_mgmt to update management settings
• set_site_locale to update locale settings
• set_site_connectivity to update connectivity settings

Since

1.0.0

Remarks

PHP: list_settings() -> return $this->fetch_results('/api/s/' . $this->site . '/get/setting');

List self information

Retrieves information about the current user/admin session including permissions, roles, and access levels for the current site context.

Throws

When self information retrieval fails

Example

// Get current user information
const selfInfo = await client.list_self();
console.log('Current user:', selfInfo.name);
console.log('Admin level:', selfInfo.admin_level);

// Check user permissions
if (selfInfo.is_super) {
  console.log('User has super admin privileges');
}

// Display user details
console.log('User Details:', {
  name: selfInfo.name,
  email: selfInfo.email,
  role: selfInfo.role,
  lastLogin: new Date(selfInfo.last_login * 1000).toLocaleString()
});
Copy

Since

1.0.0

Remarks

PHP: list_self() -> return $this->fetch_results('/api/s/' . $this->site . '/self');

Set super identity settings base

Updates super administrator identity settings including authentication methods, identity providers, and related security configurations. This affects controller-wide identity management settings.

Throws

When identity settings update fails

Example

// Update identity provider settings
await client.set_super_identity_settings_base({
  auth_method: 'local',
  enable_sso: false
});

// Configure LDAP authentication
await client.set_super_identity_settings_base({
  auth_method: 'ldap',
  ldap_server: 'ldap.company.com',
  ldap_port: 389,
  ldap_bind_dn: 'cn=admin,dc=company,dc=com'
});
Copy

Warning

This affects controller-wide authentication settings

Since

1.0.0

Remarks

PHP: set_super_identity_settings_base($payload) -> return $this->fetch_results_boolean('/api/set/setting/super_identity', $payload);

Set super management settings base

Updates super administrator management settings including system-wide management preferences, access controls, and administrative configurations. This affects controller-wide management settings.

Throws

When management settings update fails

Example

// Update system management settings
await client.set_super_mgmt_settings_base({
  auto_upgrade: true,
  ssh_enabled: false,
  analytics_enabled: true
});

// Configure backup settings
await client.set_super_mgmt_settings_base({
  auto_backup: true,
  backup_retention_days: 30,
  backup_location: '/data/backups'
});
Copy

Warning

This affects controller-wide management settings

Since

1.0.0

Remarks

PHP: set_super_mgmt_settings_base($payload) -> return $this->fetch_results_boolean('/api/set/setting/super_mgmt', $payload);

Set super SMTP settings base

Updates super administrator SMTP settings including email server configuration, authentication credentials, and notification preferences for system-wide email communications.

Throws

When SMTP settings update fails

Example

// Configure SMTP server settings
await client.set_super_smtp_settings_base({
  smtp_server: 'smtp.gmail.com',
  smtp_port: 587,
  smtp_use_tls: true,
  smtp_username: 'notifications@company.com',
  smtp_password: 'app-password'
});

// Update email notification settings
await client.set_super_smtp_settings_base({
  smtp_enabled: true,
  from_email: 'unifi@company.com',
  from_name: 'UniFi Controller',
  enable_notifications: true
});
Copy

Warning

This affects controller-wide email settings

Since

1.0.0

Remarks

PHP: set_super_smtp_settings_base($payload) -> return $this->fetch_results_boolean('/api/set/setting/super_smtp', $payload);

Fetch 5-minute site statistics

Retrieves detailed 5-minute interval statistics for the site including bandwidth usage, client counts, and other network metrics over time.

Throws

When statistics retrieval fails

Example

// Get last 12 hours of 5-minute stats
const stats = await client.stat_5minutes_site();

// Get stats for specific time range
const start = Date.now() - (24 * 60 * 60 * 1000); // 24 hours ago
const end = Date.now();
const stats = await client.stat_5minutes_site(start, end);

// Get specific attributes only
const stats = await client.stat_5minutes_site(
  undefined, 
  undefined, 
  ['bytes', 'num_sta']
);
Copy

See

• stat_hourly_site for hourly statistics
• stat_daily_site for daily statistics
• stat_monthly_site for monthly statistics

Since

1.0.0

Remarks

PHP: stat_5minutes_site($start = null, $end = null, $attribs = null) -> return $this->fetch_results('/api/s/' . $this->site . '/stat/report/5minutes.site', $payload);

Fetch daily site statistics

Retrieves daily aggregated statistics for the site including bandwidth usage, client counts, and other network metrics over time.

Throws

When statistics retrieval fails

Example

// Get last 7 days of daily stats
const stats = await client.stat_daily_site();

// Get stats for specific month
const start = new Date('2023-01-01').getTime();
const end = new Date('2023-02-01').getTime();
const stats = await client.stat_daily_site(start, end);
Copy

See

• stat_5minutes_site for 5-minute statistics
• stat_hourly_site for hourly statistics
• stat_monthly_site for monthly statistics

Since

1.0.0

Remarks

PHP: stat_daily_site($start = null, $end = null, $attribs = null) -> return $this->fetch_results('/api/s/' . $this->site . '/stat/report/daily.site', $payload);

Fetch hourly site statistics

Retrieves hourly aggregated statistics for the site including bandwidth usage, client counts, and other network metrics over time.

Throws

When statistics retrieval fails

Example

// Get last 7 days of hourly stats
const stats = await client.stat_hourly_site();

// Get stats for specific day
const start = new Date('2023-01-01').getTime();
const end = new Date('2023-01-02').getTime();
const stats = await client.stat_hourly_site(start, end);
Copy

See

• stat_5minutes_site for 5-minute statistics
• stat_daily_site for daily statistics
• stat_monthly_site for monthly statistics

Since

1.0.0

Remarks

PHP: stat_hourly_site($start = null, $end = null, $attribs = null) -> return $this->fetch_results('/api/s/' . $this->site . '/stat/report/hourly.site', $payload);

Fetch monthly site statistics

Retrieves monthly aggregated statistics for the site including bandwidth usage, client counts, and other network metrics over time.

Throws

When statistics retrieval fails

Example

// Get last 12 months of monthly stats
const stats = await client.stat_monthly_site();

// Get stats for specific year
const start = new Date('2023-01-01').getTime();
const end = new Date('2024-01-01').getTime();
const stats = await client.stat_monthly_site(start, end);
Copy

See

• stat_5minutes_site for 5-minute statistics
• stat_hourly_site for hourly statistics
• stat_daily_site for daily statistics

Since

1.0.0

Remarks

PHP: stat_monthly_site($start = null, $end = null, $attribs = null) -> return $this->fetch_results('/api/s/' . $this->site . '/stat/report/monthly.site', $payload);

Fetch sites statistics

Retrieves statistics and information for all accessible sites. This provides an overview of all sites managed by the controller.

Throws

When sites statistics retrieval fails

Example

// Get statistics for all sites
const sitesStats = await client.stat_sites();

// Find site with most clients
const busiestSite = sitesStats.reduce((prev, current) => 
  (prev.num_sta > current.num_sta) ? prev : current
);
console.log(`Busiest site: ${busiestSite.desc} with ${busiestSite.num_sta} clients`);
Copy

See

• list_sites to get basic site information
• stat_5minutes_site for detailed site statistics

Since

1.0.0

Remarks

PHP: stat_sites() -> return $this->fetch_results('/api/stat/sites');

Update OS console

Initiates an update of the UniFi OS console/controller software. This command triggers the controller to check for and install available updates. The update process runs asynchronously and may cause temporary service interruption.

Throws

When OS update initiation fails

Example

// Check for updates first
const updateInfo = await client.get_update_os_console();
if (updateInfo.update_available) {
  console.log(`Update available: ${updateInfo.version}`);
  
  // Initiate the update
  await client.update_os_console();
  console.log('OS update started - controller may restart');
}

// Update with error handling
try {
  await client.update_os_console();
  console.log('OS update initiated successfully');
  console.log('Controller may be unavailable during update process');
} catch (error) {
  console.error('Failed to start OS update:', error.message);
}
Copy

Warning

This operation may cause controller restart and temporary service interruption

See

get_update_os_console to check for available updates

Since

1.0.0

Remarks

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

Get OS console update information

Retrieves information about available OS console/controller updates including version numbers, release notes, and update availability status.

Throws

When update information retrieval fails

Example

// Check for available updates
const updateInfo = await client.get_update_os_console();

if (updateInfo.update_available) {
  console.log(`Update available: ${updateInfo.version}`);
  console.log(`Current version: ${updateInfo.current_version}`);
  console.log(`Release notes: ${updateInfo.release_notes}`);
} else {
  console.log('No updates available');
}

// Display detailed update information
console.log('Update Status:', {
  available: updateInfo.update_available,
  currentVersion: updateInfo.current_version,
  latestVersion: updateInfo.version,
  releaseDate: updateInfo.release_date,
  downloadSize: updateInfo.download_size
});

// Check update status with error handling
try {
  const updateInfo = await client.get_update_os_console();
  if (updateInfo.update_available) {
    console.log('Update check completed - update available');
  } else {
    console.log('Update check completed - system is up to date');
  }
} catch (error) {
  console.error('Failed to check for updates:', error.message);
}
Copy

See

update_os_console to initiate OS update

Since

1.0.0

Remarks

PHP: get_update_os_console() -> return $this->fetch_results('/api/s/' . $this->site . '/stat/fwupdate/latest-version');