UnifiClient

What it is

UnifiClient is an Elixir client for the two applications that run on a UniFi OS console, UniFi Network and UniFi Protect, and for Ubiquiti's cloud Site Manager API.

Network and Protect share a console and a login, so one authenticated client serves both.

• Network: sites, devices (including PoE), clients, wireless and LAN configuration, firewall rules and port forwards, traffic statistics, and live events over WebSocket.
• Protect: cameras and snapshots, recorded events with thumbnails and heatmaps, MP4 export of recorded video, and live updates over Protect's binary WebSocket.
• Cloud: hosts, sites, devices and clients through the Site Manager API, authenticated with an API key rather than a console login.

It talks to UDM Pro and other UniFi OS consoles, to self-hosted controllers (Network only, since Protect requires UniFi OS), and to Ubiquiti's cloud API.

Example

{:ok, client} =
  UnifiClient.Client.new(
    host: "192.168.1.1",
    username: "admin",
    password: "secret",
    verify_ssl: false
  )

{:ok, client} = UnifiClient.Auth.login(client)

{:ok, sites} = UnifiClient.API.Sites.list(client)
{:ok, devices} = UnifiClient.API.Devices.list(client, "default")
{:ok, active} = UnifiClient.API.Clients.list_active(client, "default")

:ok = UnifiClient.Auth.logout(client)

The same client reaches Protect, for example to take a camera snapshot or export a minute of recorded video to disk:

{:ok, cameras} = UnifiClient.Protect.Cameras.list(client)
porch = Enum.find(cameras, &(&1["name"] == "Porch"))

{:ok, jpeg} = UnifiClient.Protect.Cameras.snapshot(client, porch["id"], w: 640)

start = ~U[2026-09-17 08:00:00Z]
finish = DateTime.add(start, 60, :second)
{:ok, "porch.mp4"} = UnifiClient.Protect.Video.export(client, porch["id"], start, finish, "porch.mp4")

Design notes

• Local first. The console is a device on your LAN, and nothing goes through Ubiquiti's cloud except the Cloud modules.
• Quiet session renewal. When the console expires a session, the client logs in again and retries the call once, without the caller seeing it. Concurrent callers share a single renewal instead of each starting its own login.
• Live updates that resume. Protect events arrive as {:unifi_protect_event, ...} messages, and the subscription resumes from the last update id across reconnects, so events do not repeat.
• Responses as sent. The console's API is undocumented and varies by firmware, so responses are returned as the console sends them, as maps with string keys, rather than remodelled into structs.
• Clear about TLS. Consoles ship a self-signed certificate, so verify_ssl: false is the usual setting on a home or office LAN. The documentation is explicit that this should be considered before pointing the client at anything other than your own network.

You need a local console account (not a Ubiquiti SSO login) without MFA, ideally with the least role that does what you need. The library requires Elixir 1.20 or newer.

The repository includes twelve runnable example scripts, one per public area. Each takes --help and exits with a clear reason when a console cannot be reached.

Status

UnifiClient is published on Hex. Network and Protect are implemented and covered by the test suite, but by its author's own account the library is immature and may have bugs. Treat it as early software, and report issues on GitHub. MIT licensed.