The unificontrol API

Interaction with Unifi controllers is done by creating an instance of unificontrol.UnifiClient. The methods of this class represent calls to the various APIs exposed by the controller.

Data types

Most of the data types used in the API are fairly self-explanitory. There are however a few cases where some explaination is necessary.

ID values

In many of the API calls various entities such as networks, user groups, managed devices or other items are referred to by an ID value. In most cases these are 24 character unique hexadecimal strings which bear no relation to the visible names of these objects. In these cases you will need to use the various list_... methods to get lists of the available objects and use the _id attribute from the object you need.

Settings dictionaries

Many of the set_site_... calls take a settings dictionary. In these case the list_settings method can be used to find the current settings object and thus determine the keys expected in the settings dictionary.

Note

The settings dictionary should NOT contain an entry with the key _id as this will be automatically assigned. You should also remove the entry with the key key as this will be set to internally to refect the type of site setting to be set.

The UnifiClient class

class UnifiClient(host='localhost', port=8443, username='admin', password=None, site='default', cert='FETCH_CERT')

An abstract interface to the Unifi controller

Parameters:
  • host (str) – hostname of Unifi controller
  • port (int) – port on which controller is to be accessed
  • username (str) – user name for admin account
  • password (str) – password for admin account
  • site (str) – identifier of site to be managed
  • cert (str or bytes) – Server SSL certificate to pin for secure access. Pass None to use regular certificate verification or the constant FETCH_CERT to use the current certificate of the server and pin that cert for future accesses.
host

Host name of contoller

Type:str
port

Port for accessing controller

Type:str
site

Identifier of site being managed

Type:str
login(username=None, password=None)

Log in to Unifi controller

Parameters:
  • username (str) – optional user name for admin account
  • password (str) – optional password for admin account

The username and password arguments are optional if they were provided when the client was created.

logout()

Log out from Unifi controller

authorize_guest(mac, minutes, up=None, down=None, MBytes=None, ap_mac=None)

Authorize a client device

Parameters:
  • mac (str) – MAC address of the guest client to be authorized
  • minutes (int) – duration for which the client is authorised
  • up (int) – optional upstream bandwidth limit in Kb/sec
  • down (int) – optional downstream bandwidth limit in Kb/sec
  • MBytes (int) – optional total data volume limit in megabytes
  • ap_mac (str) – optional MAC address of the access point to which the client will attach
unauthorize_guest(mac)

Unauthorize a guest client device

Parameters:mac (str) – MAC address of guest client to unauthorize
reconnect_client(mac)

Force reconnection of a client device

Parameters:mac (str) – MAC address of guest client to reconnect
block_client(mac)

Block a client device

Parameters:mac (str) – MAC address of guest client to block
unblock_client(mac)

Unblock a client device

Parameters:mac (str) – MAC address of guest client to unblock
forget_client(macs)

Forget a client device

Parameters:mac (str) – One or a litst of MAC addresses of guest clients to forget

Note

Requires version 5.9 of the controller or later.

create_client(mac, usergroup_id, name=None, note=None)

Creat a new user/client device

Parameters:
  • mac (str) – MAC address of new client
  • usergroup_id (str) – _id value for the user group for the client
  • name (str) – optional name for the new client
  • note (str) – optional note to attach to the new client
set_client_note(user_id, note)

Add, modify or remove a note on a client device

Parameters:
  • user_id (str) – _id value of the user for which the note is set
  • note (str) – Note to attach, or None to remove note
set_client_name(user_id, name)

Add, modify or remove a name of a client device

Parameters:
  • user_id (str) – _id value of the user for which the name is set
  • name (str) – name to attach, or None to remove name
set_client_fixed_ip(user_id, fixed_ip, network_id)

Add, modify or remove a fixed ip of a client device

Parameters:
  • user_id (str) – _id value of the user for which the name is set
  • fixed_ip (str) – IP to attach, or None to remove IP
  • network_id (str) – network to attach
stat_5minutes_site(start=None, end=None, attrs=['bytes', 'wan-tx_bytes', 'wan-rx_bytes', 'wlan_bytes', 'num_sta', 'lan-num_sta', 'wlan-num_sta', 'time'])

Fetch site statistics with 5 minute granularity

Parameters:
  • start (int) – optional start of reporting period, as seconds in the Unix epoch. If not present defaults to 12 hours before the end time
  • end (int) – optional end of reporting period, as seconds in the Unix epoch. If not present defaults to the current time.
  • attrs (list) – optional list of statistics to return
Returns:

List of dictionaries of statistics

stat_hourly_site(start=None, end=None, attrs=['bytes', 'wan-tx_bytes', 'wan-rx_bytes', 'wlan_bytes', 'num_sta', 'lan-num_sta', 'wlan-num_sta', 'time'])

Fetch site statistics with 1 hour granularity

Parameters:
  • start (int) – optional start of reporting period, as seconds in the Unix epoch. If not present defaults to 7 days before the end time
  • end (int) – optional end of reporting period, as seconds in the Unix epoch. If not present defaults to the current time.
  • attrs (list) – optional list of statistics to return
Returns:

List of dictionaries of statistics

stat_daily_site(start=None, end=None, attrs=['bytes', 'wan-tx_bytes', 'wan-rx_bytes', 'wlan_bytes', 'num_sta', 'lan-num_sta', 'wlan-num_sta', 'time'])

Fetch site statistics with 1 day granularity

Parameters:
  • start (int) – optional start of reporting period, as seconds in the Unix epoch. If not present defaults to 1 year before the end time
  • end (int) – optional end of reporting period, as seconds in the Unix epoch. If not present defaults to the current time.
  • attrs (list) – optional list of statistics to return
Returns:

List of dictionaries of statistics

stat_5minutes_aps(mac=None, start=None, end=None, attrs=['bytes', 'num_sta', 'time'])

Fetch access point statistics with 5 minute granularity

Parameters:
  • mac (str) – optional MAC access of single AP for which to fetch statistics
  • start (int) – optional start of reporting period, as seconds in the Unix epoch. If not present defaults to 12 hours before the end time
  • end (int) – optional end of reporting period, as seconds in the Unix epoch. If not present defaults to the current time.
  • attrs (list) – optional list of statistics to return
Returns:

List of dictionaries of statistics

stat_hourly_aps(mac=None, start=None, end=None, attrs=['bytes', 'num_sta', 'time'])

Fetch access point statistics with 1 hour granularity

Parameters:
  • mac (str) – optional MAC access of single AP for which to fetch statistics
  • start (int) – optional start of reporting period, as seconds in the Unix epoch. If not present defaults to 7 yays before the end time
  • end (int) – optional end of reporting period, as seconds in the Unix epoch. If not present defaults to the current time.
  • attrs (list) – optional list of statistics to return
Returns:

List of dictionaries of statistics

stat_daily_aps(mac=None, start=None, end=None, attrs=['bytes', 'num_sta', 'time'])

Fetch access point statistics with 1 day granularity

Parameters:
  • mac (str) – optional MAC access of single AP for which to fetch statistics
  • start (int) – optional start of reporting period, as seconds in the Unix epoch. If not present defaults to 1 year before the end time
  • end (int) – optional end of reporting period, as seconds in the Unix epoch. If not present defaults to the current time.
  • attrs (list) – optional list of statistics to return
Returns:

List of dictionaries of statistics

stat_5minutes_user(mac, start=None, end=None, attrs=['time', 'rx_bytes', 'tx_bytes'])

Fetch client device statistics with 5 minute granularity

Parameters:
  • mac (str) – MAC access of client device for which to fetch statistics
  • start (int) – optional start of reporting period, as seconds in the Unix epoch. If not present defaults to 12 hours before the end time
  • end (int) – optional end of reporting period, as seconds in the Unix epoch. If not present defaults to the current time.
  • attrs (list) – optional list of statistics to return
Returns:

List of dictionaries of statistics

stat_hourly_user(mac, start=None, end=None, attrs=['time', 'rx_bytes', 'tx_bytes'])

Fetch client device statistics with 1 hour granularity

Parameters:
  • mac (str) – MAC access of client device for which to fetch statistics
  • start (int) – optional start of reporting period, as seconds in the Unix epoch. If not present defaults to 7 days before the end time
  • end (int) – optional end of reporting period, as seconds in the Unix epoch. If not present defaults to the current time.
  • attrs (list) – optional list of statistics to return
Returns:

List of dictionaries of statistics

stat_daily_user(mac, start=None, end=None, attrs=['time', 'rx_bytes', 'tx_bytes'])

Fetch client device statistics with 1 day granularity

Parameters:
  • mac (str) – MAC access of client device for which to fetch statistics
  • start (int) – optional start of reporting period, as seconds in the Unix epoch. If not present defaults to 1 year before the end time
  • end (int) – optional end of reporting period, as seconds in the Unix epoch. If not present defaults to the current time.
  • attrs (list) – optional list of statistics to return
Returns:

List of dictionaries of statistics

stat_sessions(mac=None, start=None, end=None, type='all')

Show login sessions

stat_sta_sessions_latest(mac, limit=5)

Show latest ‘n’ login sessions for a single client device

stat_auths(start=None, end=None)

Show all authorizations

list_allusers(type='all', conn='all', within=8760)

List all client devices ever connected to the site

list_guests(within=8760)

List guest devices

list_clients(client_mac=None)

List currently connected client devices, or details on a single MAC address

list_configured_clients(client_mac=None)

List configured client devices, or details on a single MAC address

get_client_details(client_mac)

Get details about a client

list_usergroups()

List user groups

set_usergroup(client_mac, usergroup_id)

Set the user group for a client

edit_usergroup(group_id, site_id, name, qos_rate_max_down=-1, qos_rate_max_up=-1)

Update user group

create_usergroup(name, qos_rate_max_down=-1, qos_rate_max_up=-1)

Create user group

delete_usergroup(group_id)

Delete user group

list_health()

List health metrics

list_dashboard()

List dashboard metrics

list_users()

List knows clients groups

list_devices(device_mac=None)

List details of one or more managed device on this site

Parameters:device_mac (str) – optional MAC address of device on which to fetch details
Returns:list of dictionaries of device details.
list_devices_basic()

List basic information about all managed devices

list_tags()

List known device tags

list_rogueaps(within=24)

List rogue or nearby APs

list_rogueknown()

List rogue or nearby APs

list_sites()

List sites on this controller

stat_sites()

Get stats for sites on this controller

create_site(desc)

Create a site

delete_site(site)

Delete a site

set_site_name(desc)

Change a site’s name

set_site_country(setting=None)

Set site country

set_site_locale(setting=None)

Set site locale

set_site_snmp(setting=None)

Set site snmp

set_site_mgmt(setting=None)

Set site mgmt

set_site_guest_access(setting=None)

Set site guest access

set_site_ntp(setting=None)

Set site ntp

set_site_connectivity(setting=None)

Set site connectivity

list_admins()

List admins

list_all_admins()

List all admins

invite_admin(name, email, readonly=False, enable_sso=True, device_adopt=False, device_restart=False)

Invite a new admin for access to the current site

create_admin(name, email, password, requires_new_password=False, readonly=False, enable_sso=True, device_adopt=False, device_restart=False)

Create a new admin user

revoke_admin(admin)

Revoke an admin user

list_wlan_groups()

List wlan_groups

stat_sysinfo()

Show general system information

stat_status()

Get controller status

list_self()

Get info about the logged in user

list_vouchers(create_time)

List vouchers

stat_payment()

List payments

create_hotspotop(name, password, note)

Create hotspot operator

list_hotspotop()

List hotspot operators

create_voucher(minutes, count=1, quota=0, note=None, up=None, down=None, MBytes=None)

Create voucher(s)

revoke_voucher(voucher_id)

Revoke voucher

extend_guest_validity(guest_id)

Extend guest validity

list_portforward_stats()

List port forwarding configuation and statistics

list_vpn_stats()

List VPN users and statistics

list_dpi_stats()

List deep packet inspection stats

list_current_channels()

List currently available channels

list_country_codes()

List country codes

list_portforwarding()

List port forwarding settings

list_dynamicdns()

List dynamic DNS settings

list_portconf()

List port configurations

list_extension()

List VoIP extensions

list_settings(key=None)

List site settings

enable_portforwarding_rule(pfr_id, enabled)

Enable or disable a port forwarding rule

Parameters:
  • pfr_id (str) – _id value of the portforwarding rule
  • enabled (bool) – true to enable the rule, false to disable the rule
adopt_device(mac)

Adopt a device to the selected site

restart_ap(mac)

Reboot an access point

disable_ap(ap_id, disabled)

Disable/enable an access point

led_override(device_id, led_override)

Override LED mode for a device

locate_ap(mac, enabled)

Toggle flashing LED of an access point for locating purposes

site_leds(led_enabled)

Toggle LEDs of all the access points ON or OFF

set_ap_radiosettings(ap_id, radio_table, channel, ht, tx_power_mode, tx_power)

Update access point radio settings

rename_ap(ap_id, name)

Rename access point

move_device(site, mac)

Move a device to another site

delete_device(mac)

Delete a device from the current site

list_networkconf(network_id=None)

List network settings

create_network(settings=None)

Create a network

set_networksettings(network_id, settings=None)

Update network settings, base

delete_network(network_id)

Delete a network

list_wlanconf(wlan_id=None)

List wireless LAN settings for all or one network

set_wlan_settings(wlan_id, passphrase, ssid=None)

Set wireless LAN password and SSID

enable_wlan(wlan_id, enabled)

Enable or diabble a wireless LAN

set_wlan_mac_filter(wlan_id, enabled, whitelist=False, mac_list=None)

Set wireless LAN MAC filtering policy

delete_wlan(wlan_id)

Delete a wlan

list_events(historyhours=720, start=0, limit=1000)

List events

Parameters:
  • historyhours (int) – how far back to list events
  • start (int) – index of the first event to return
  • limit (int) – maximum number of events to return
list_alarms()

List all alarms

count_alarms()

Count alarms

archive_alarm(alarm_id)

Archive a single alarm

archive_all_alarms()

Archive alarms(s)

upgrade_device(mac)

Upgrade a device to the latest firmware

upgrade_device_external(mac, url)

Upgrade a device to a specific firmware file

start_rolling_upgrade()

Start rolling upgrade

cancel_rolling_upgrade()

Cancel rolling upgrade

power_cycle_switch_port(mac, port_idx)

Power-cycle the PoE output of a switch port

spectrum_scan(mac)

Trigger an RF scan by an AP

spectrum_scan_state(ap_mac)

Check the RF scanning state of an AP

set_device_settings_base(device_id, settings=None)

Update device settings, base

list_radius_profiles(profile_id=None)

List Radius profiles

list_radius_accounts(account_id=None)

List Radius user accounts

create_radius_account(name, password, tunnel_type, tunnel_medium_type, vlan=None)

Create a Radius user account

set_radius_account_base(account_id, account_details=None)

Update Radius account, base

delete_radius_account(account_id)

Delete a Radius account

Constants

class RadiusTunnelType

Values for the tunnel type in RADIUS profiles

PPTP = 1

Point-to-Point Tunneling Protocol

L2F = 2

Layer Two Forwarding

L2TP = 3

Layer Two Tunneling Protocol

ATMP = 4

Ascend Tunnel Management Protocol

VTP = 5

Virtual Tunneling Protocol

AH = 6

IP Authentication Header in the Tunnel-mode

IP_IP = 7

IP-in-IP Encapsulation

MIN_IP_IP = 8

Minimal IP-in-IP Encapsulation

ESP = 9

IP Encapsulating Security Payload in the Tunnel-mode

GRE = 10

Generic Route Encapsulation

DVS = 11

Bay Dial Virtual Services

IP_IP_TUN = 12

IP-in-IP Tunneling

VLAN = 13

Virtual LANs

class RadiusTunnelMediumType

Values for the tunnel medium type in RADIUS profiles

IPv4 = 1

IP version 4

IPv6 = 2

IP version 6

NSAP = 3

NSAP

HDLC = 4

8-bit multidrop

BBN = 5

1822

IEEE_802 = 6

includes all 802 media plus Ethernet “canonical format”

E_163 = 7

E.163 (POTS)

E_164 = 8

E.164 (SMDS, Frame Relay, ATM)

F_69 = 9

F.69 (Telex)

X_121 = 10

X.121 (X.25, Frame Relay)

IPX = 11

IPX

APPLETALK = 12

Appletalk

DECNET = 13

Decnet IV

BANYAN = 14

Banyan Vines

E_164_NSAP = 15

E.164 with NSAP format subaddress