A PHP class that provides access to Ubiquiti's official UniFi Cloud API.
This client provides a modern and convenient way to interact with the official UniFi Cloud API using PHP. It uses Guzzle for HTTP requests and supports various operations to interact with UniFi deployments programmatically.
This client supports the official UniFi Cloud API up to version 0.1.
This is not a replacement for our original API Client which offers more functions and endpoints, but does not support connections through unifi.ui.com: https://github.com/Art-of-WiFi/UniFi-API-client
- a server with:
- PHP 8.1 or higher installed.
- the php-curl module installed and enabled.
- direct network connectivity between this server and https://api.ui.com where the UniFi Cloud API is hosted.
- an API key that can be obtained as follows:
- Sign in to the UniFi Site Manager at https://unifi.ui.com.
- From the left navigation bar, click on API.
- Click Create API Key.
- Copy the key and store it securely, as it will only be displayed once.
- Click Done to ensure the key is hashed and securely stored.
The package needs to be installed using Composer/packagist for easy inclusion in your projects by executing the following command from your project directory:
composer require art-of-wifi/unifi-cloud-api-clientFollow these installation instructions if you don't have Composer installed already.
Below is a basic example of how to use the UniFi Cloud API Client:
<?php
require 'vendor/autoload.php';
use UniFiCloudApiClient\Client\UniFiClient;
$apiKey = 'your_api_key_here';
try {
// Initialize the UniFi Cloud API client, optionally you can pass a different base URI
$unifiClient = UniFiClient::getInstance($apiKey);
// Enable debug mode, optional
$unifiClient->setDebug(true);
// Set a custom timeout to override the default value of 10 seconds, optional
$unifiClient->setTimeout(5);
// Fetch and echo the version
echo 'UniFi Cloud API client version: ' . $unifiClient->getVersion() . PHP_EOL;
// List all hosts
$hosts = $unifiClient->hosts->list();
print_r($hosts);
// Get host by ID
$hostId = 'your_host_id_here';
$host = $unifiClient->hosts->get($hostId);
print_r($host);
// List all sites
$sites = $unifiClient->sites->list();
print_r($sites);
// List all devices with optional filter parameters
$devices = $unifiClient->devices->list(
['900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789', '900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:987654321'],
'2024-07-15T07:01:13Z'
);
print_r($devices);
echo 'Effective URI: ' . $unifiClient->getEffectiveUri() . PHP_EOL;
echo 'Transfer time: ' . $unifiClient->getTransferTime() . ' seconds' . PHP_EOL;
echo 'Response status: ' . $unifiClient->getResponseStatusCode() . PHP_EOL;
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}There are several getter and setter methods available to interact with the UniFi Cloud API client:
| Method | Description |
|---|---|
setTimeout($timeout) |
Sets the timeout for the HTTP requests in seconds, default is 10 seconds. |
getTimeout() |
Returns the timeout for the HTTP requests in seconds. |
setDebug($debug) |
Enables or disables debug mode, false by default. |
getDebug() |
Returns the debug mode status. |
getVersion() |
Returns the version of the UniFi Cloud API client. |
getEffectiveUri() |
Returns the effective URI of the last request. |
getTransferTime() |
Returns the transfer time of the last request in seconds. |
getResponseStatusCode() |
Returns the response status code of the last request. |
getHandlerStats() |
Returns the Guzzle handler statistics of the last request. |
getHandlerErrorData() |
Returns the Guzzle handler errors of the last request. |
GET /ea/hosts
Retrieve a list of all hosts associated with the UI account making the API call.
$hosts = $unifiClient->hosts->list();[
"data" => [
[
"hardwareId" => "eae0f123-0000-5111-b111-f833f56eade5",
"id" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
"ipAddress" => "192.168.220.114",
"isBlocked" => false,
"lastConnectionStateChange" => "2024-06-23T03:59:52Z",
"latestBackupTime" => "2024-06-22T11:55:10Z",
"owner" => true,
"registrationTime" => "2024-04-17T07:27:14Z",
"reportedState" => [...], // Replace [...] with actual data structure
"type" => "console",
"userData" => [...], // Replace [...] with actual data structure
]
],
"httpStatusCode" => 200,
"traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]GET /ea/hosts/{id}
Retrieve detailed information about a specific host by ID.
$hostId = 'your_host_id_here';
$host = $unifiClient->hosts->get($hostId);[
"data" => [
"hardwareId" => "eae0f123-0000-5111-b111-f833f56eade5",
"id" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
"ipAddress" => "192.168.220.114",
"isBlocked" => false,
"lastConnectionStateChange" => "2024-06-23T03:59:52Z",
"latestBackupTime" => "2024-06-22T11:55:10Z",
"owner" => true,
"registrationTime" => "2024-04-17T07:27:14Z",
"reportedState" => [...], // Replace [...] with actual data structure
"type" => "console",
"userData" => [...], // Replace [...] with actual data structure
],
"httpStatusCode" => 200,
"traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]GET /ea/sites
List sites associated with the UI account making the API call.
$sites = $unifiClient->sites->list();[
"data" => [
[
"hostId" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
"isOwner" => true,
"meta" => [
"desc" => "Default",
"gatewayMac" => "f4:e2:c6:c2:3f:13",
"name" => "default",
"timezone" => "Europe/Riga"
],
"permission" => "admin",
"siteId" => "661900ae6aec8f548d49fd54",
"statistics" => [...], // Replace [...] with actual data structure
"subscriptionEndTime" => "2024-06-27T13:09:46Z"
]
],
"httpStatusCode" => 200,
"traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]GET /ea/devices
List UniFi devices that are associated with the UI account making the API call, grouped by host.
$devices = $unifiClient->devices->list(
['900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789', '900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:987654321'],
'2024-07-15T07:01:13Z'
);hostIds[](array, optional): List of host IDs.time(string, optional): Last processed timestamp of devices.
[
"data" => [
[
"devices" => [
[
"adoptionTime" => null,
"firmwareStatus" => "upToDate",
"id" => "F4E2C6C23F13",
"ip" => "192.168.1.226",
"isConsole" => true,
"isManaged" => true,
"mac" => "F4E2C6C23F13",
"model" => "UDM SE",
"name" => "unifi.yourdomain.com",
"note" => null,
"productLine" => "network",
"shortname" => "UDMPROSE",
"startupTime" => "2024-06-19T13:41:43Z",
"status" => "online",
"uidb" => [
"guid" => "0fd8c390-a0e8-4cb2-b93a-7b3051c83c46",
"id" => "e85485da-54c3-4906-8f19-3cef4116ff02",
"images" => [
"default" => "3008400039c483c496f4ad820242c447",
"nopadding" => "67b553529d0e523ca9dd4826076c5f3f",
"topology" => "8371ecdda1f00f1636a2eefadf0d7d47"
]
],
"updateAvailable" => null,
"version" => "4.0.6"
]
],
"hostId" => "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
"hostName" => "unifi.yourdomain.com",
"updatedAt" => "2024-07-15T07:01:13Z"
]
],
"httpStatusCode" => 200,
"traceId" => "a7dc15e0eb4527142d7823515b15f87d"
]The API rate limit is set to 100 requests per minute. If you exceed this limit, the server will respond with a 429 Too Many Requests status code. The client will throw an Exception if this happens.
When encountering issues with the official UniFi Cloud API using other libraries, cURL or Postman, please do not open an Issue here. Such Issues will be closed immediately. Please use the Discussions section instead.
If you would like to contribute to this repository, please open an issue and include your code there or else create a pull request.
This class is based on the documentation provided by Ubiquiti for their UniFi Cloud API: https://developer.ui.com/unifi-api/
This PHP class is provided "as is" without any guarantees or warranties. Use at your own risk. The author is not responsible for any damage or losses of any kind caused by the use or misuse of this class.