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 constantFETCH_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 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 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
- user_id (str) –
-
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
- user_id (str) –
-
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
- user_id (str) –
-
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 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
- pfr_id (str) –
-
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
-