A New PHP Client for the Official UniFi Network Application API

We’ve released a new open-source PHP UniFi API library for Ubiquiti’s official UniFi Network Application API — the one they document and support themselves. It’s built on Saloon v3, uses API key authentication, and requires PHP 8.1 or higher.

For years, our legacy PHP API client has been the go-to solution for developers building integrations with UniFi networks. With close to 400,000 downloads and 1,300 stars on GitHub, it’s clearly filled a real need. But it has always relied on an unofficial, undocumented API. That changes today.

A PHP client for the official UniFi API

We’ve just released a PHP API client for the official UniFi Network Application API — the API that Ubiquiti themselves maintain, document, and support. You’ll find the documentation built right into your controller under Settings → Integrations or, on the latest versions, directly under Integrations.

This is also our first major open-source project built with Claude Code, Anthropic’s agentic coding tool. It’s been an interesting experience — more on that in a future post.

How the official API client differs from the legacy client

The most obvious difference is authentication. The legacy client uses a username and password to log in, just like you would through the browser. The new client uses an API key, which you generate directly in the UniFi Network Application under Settings → Integrations. No session management, no cookie handling — just a key in the header of every request.

The underlying technology is also different. The new client is built on Saloon v3, a well-maintained PHP HTTP client library that handles the heavy lifting of request construction, response parsing, and error handling. This gives us a much cleaner foundation than the cURL-based approach in the legacy client.

Here’s what that looks like in practice:

use ArtOfWiFi\UnifiNetworkApplicationApi\UnifiClient;

$client = new UnifiClient(
    baseUrl: 'https://192.168.1.1',
    apiKey: 'your-api-key-here',
    verifySsl: false
);

// List all sites
$sites = $client->sites()->list()->json();

// Set a site and start working
$client->setSiteId('550e8400-e29b-41d4-a716-446655440000');

$devices  = $client->devices()->listAdopted();
$clients  = $client->clients()->list();
$networks = $client->networks()->list();

Not a lot of ceremony. You initialize the client, optionally set a site ID (a UUID you get from the sites list), and start making calls.

Type-safe filter builders

One feature we’re particularly happy with is the filter builder system. The official API supports a filtering syntax on most list endpoints, and rather than asking you to write raw filter strings, we’ve built a set of fluent, type-safe filter classes that give you IDE autocomplete and catch mistakes at development time rather than at runtime.

use ArtOfWiFi\UnifiNetworkApplicationApi\Filters\Devices\DeviceFilter;
use ArtOfWiFi\UnifiNetworkApplicationApi\Filters\Clients\ClientFilter;

// Find all access points by model prefix
$aps = $client->devices()->listAdopted(
    filter: DeviceFilter::model()->like('U6*')
);

// Wireless guest clients only
$guests = $client->clients()->list(
    filter: ClientFilter::wirelessGuests()
);

// Devices with available firmware updates
$updatable = $client->devices()->listAdopted(
    filter: DeviceFilter::and(
        DeviceFilter::firmwareUpdatable()->equals(true),
        DeviceFilter::supported()->equals(true)
    )
);

Filter builders exist for devices, clients, networks, firewall policies, DNS policies, and more. Each one exposes only the properties that the API actually supports filtering on, so you’re not guessing. If you prefer, you can also pass raw filter strings as documented in Ubiquiti’s API documentation directly.

What the client covers

The official API has grown significantly and now covers the most important management areas:

• Sites — list and inspect sites

• Devices — list adopted devices, get statistics, restart, adopt, remove

• Clients — list connected clients, authorize guest access

• Networks — create, update, and delete VLANs and network configurations

• WiFi broadcasts — manage SSIDs

• Hotspot vouchers — create and manage guest access vouchers

• Firewall — zones, policies, policy ordering

• ACL rules — create and order access control rules

• DNS policies — A, AAAA, CNAME, MX, TXT, SRV, and forward domain records

• Supporting resources — WAN interfaces, DPI categories, countries, RADIUS profiles, VPN tunnels, device tags

Should I use the official or legacy UniFi API client?

This is a question we know will come up, so let’s be direct about it.

If the endpoints you need are available in the official API, use the new client. It’s built on a stable, documented foundation, uses API key authentication (which is simpler and safer than storing a username and password), and will be easier to maintain over time.

If you need endpoints that aren’t yet in the official API — and there are quite a few — the legacy client remains the better choice for now. It still covers significantly more of the UniFi API surface. We’ll keep maintaining it.

We expect the coverage gap to narrow over time as Ubiquiti continues to expand the official API.

Installation

composer require art-of-wifi/unifi-network-application-api-client

Requires PHP 8.1 or higher and Composer. The package is available on Packagist.

What’s next

The examples/ directory in the repository covers all the main use cases, and we’ll be publishing additional blog posts and videos covering specific topics like guest authorization, firewall automation, and more. We’ve also posted an announcement in the Ubiquiti Community.

The GitHub repository is at github.com/Art-of-WiFi/unifi-network-application-api-client. Stars and feedback are welcome — and if you run into issues or have suggestions, the GitHub issue tracker is the right place for those.