How to use UniFi Controller API for automation and scripting

Sometimes the UniFi dashboard isn’t enough. Maybe you want to schedule Wi-Fi shutoffs, bulk-block clients, or sync device data with another tool. That’s where the UniFi Controller API comes in, it’s your key to automating all the boring (or cool) stuff.

Let’s dive in !!

Before we dive in, please don't self-host your UniFi Controller if you take care of client networks. Sooner or later this will cause issues! It's fine for home users, but definitely not recommended for IT service businesses and MSPs. If you want secure, reliable and a scalable hosting solution check out UniHosted.

What is the UniFi API?

The UniFi API is an unofficial (but widely used) REST-like API that lets you interact with your UniFi Network controller via HTTP requests. It allows you to automate things like:

  • Reading connected clients
  • Creating or disabling SSIDs
  • Managing firewall rules
  • Kicking or blocking users
  • Gathering stats and uptime logs

It’s technically undocumented by Ubiquiti, but the community has reverse-engineered most endpoints, and they’re pretty stable.

Use cases for automation

Some real-world examples:

  • Automatically shut down guest Wi-Fi every night
  • Pull daily client lists into a spreadsheet
  • Block devices based on MAC rules
  • Reboot APs on a schedule
  • Set up alerts or logging integrations

It’s basically your gateway to making UniFi work the way you want it to, instead of clicking through menus every time.

What you need

To start scripting against the UniFi API, you’ll need:

  • A UniFi Controller (self-hosted, Cloud Key, UniFi OS, or hosted like UniHosted)
  • Admin access (local login recommended for scripting)
  • Python installed (we’ll use it in examples)
  • requests module: pip install requests
  • Your controller URL and site name

Step 1: Log in via API

UniFi uses a login system that sets a session cookie. Here’s how to get it in Python:

python
import requests

base_url = 'https://your-controller.com:8443'
site = 'default'  # or your site name

session = requests.Session()

login_data = {
    'username': 'admin',
    'password': 'yourpassword'
}

resp = session.post(f'{base_url}/api/login', json=login_data, verify=False)
print(resp.status_code)

If the login is successful, you now have a session with valid cookies. You’ll use this to make future API calls.

Step 2: Get a list of connected clients

This is a great first test:

python
resp = session.get(f'{base_url}/api/s/{site}/stat/sta', verify=False)
clients = resp.json()['data']

for client in clients:
    print(client['hostname'], client['mac'])

This gives you a list of all connected clients, their MACs, hostnames, IPs, and more.

Step 3: Kick or block a client

Want to disconnect a device?

python
mac = 'aa:bb:cc:dd:ee:ff'

resp = session.post(
    f'{base_url}/api/s/{site}/cmd/stamgr',
    json={"cmd": "kick-sta", "mac": mac},
    verify=False
)

To block:

python
resp = session.post(
    f'{base_url}/api/s/{site}/cmd/stamgr',
    json={"cmd": "block-sta", "mac": mac},
    verify=False
)

Useful for guest network control or automated security actions.

Step 4: Reboot an AP

If you know the device MAC, you can reboot it:

python
ap_mac = '01:23:45:67:89:ab'

resp = session.post(
    f'{base_url}/api/s/{site}/cmd/devmgr',
    json={"cmd": "restart", "mac": ap_mac},
    verify=False
)

This is great for remote troubleshooting. Combine it with a health check to reboot when an AP goes unresponsive.

Step 5: Create a new WLAN (SSID)

Yes, you can create an SSID from a script:

python
wlan_payload = {
    "name": "ScriptedSSID",
    "x_passphrase": "supersecure",
    "enabled": True,
    "security": "wpapsk",
    "hide_ssid": False,
    "vlan_enabled": False
}

resp = session.post(
    f'{base_url}/api/s/{site}/add/wlanconf',
    json=wlan_payload,
    verify=False
)

You can even add VLANs, schedule it, or limit bandwidth through the same method.

Step 6: Pull stats and logs

Want to see WAN throughput or uptime?

python
resp = session.get(f'{base_url}/api/s/{site}/stat/sysinfo', verify=False)
sysinfo = resp.json()['data'][0]

print("Uptime:", sysinfo['uptime'])
print("WAN IP:", sysinfo['wan_ip'])

Or traffic usage:

python
resp = session.get(f'{base_url}/api/s/{site}/stat/health', verify=False)
health = resp.json()['data'][0]

print("Download:", health['speedtest_status']['x_speedtest_dl'])  # in bits per sec

Step 7: Run it on a schedule (cron)

Want to automate daily checks or alerts?

Create a simple script like daily_status.py, then add it to cron:

bash
crontab -e
bash
0 7 * * * /usr/bin/python3 /home/user/scripts/daily_status.py

Now it runs every day at 7 AM and sends you results via email or logs it.

Common pitfalls

  • Login fails: If you're using UI accounts, API login won’t work. Use local-only admin accounts for automation.
  • SSL errors: If using self-signed certs, disable SSL verification in scripts (verify=False), or install the cert.
  • Wrong site name: It’s often not default. Check under Settings > Site for your actual site code.
  • Rate limits: Don’t hammer the controller. Add retries and sleep between API calls if needed.

Useful tools and wrappers

You can use these for quicker dev:

  • UniFi_api (Python)
  • UniFi-API-browser (PHP)
  • Postman: For testing endpoints manually
  • pyunifi: Lightweight Python library

These tools simplify the low-level stuff so you can focus on automation logic.

Security notes

  • Don’t hard-code passwords. Use environment variables or config files.
  • Use read-only or limited accounts when possible.
  • Set up firewall rules so scripts only run from known IPs.
  • If you host your controller, use HTTPS and domain restrictions.

When to use hosted UniFi

If you’re running scripts against multiple client controllers, doing it with self-hosted instances is a nightmare. Different URLs, cert issues, downtime, you name it.

That’s why we built UniHosted. Our controllers are reliable, API-accessible, and standardized across all clients. One script, multiple sites, no surprises. If you want full control with none of the mess, give us a try.

Final thoughts

The UniFi Controller API is one of the most powerful tools for managing your network exactly how you want. Whether you’re kicking off devices, grabbing usage stats, or spinning up new SSIDs on demand, the API gives you a way to do it all, without clicking through menus over and over again.

We’ve built our hosted UniFi platform at UniHosted with API-first operations in mind. Whether you're writing scripts or using external tools, everything is ready to plug in and scale. If you want to skip the hosting headaches and focus on automation, check us out at UniHosted.