Introduction

go-unifi is a Go client library for the UniFi Network controller — the software that manages Ubiquiti's networking gear (gateways, switches, access points). Instead of hand-rolling HTTP requests and parsing JSON, you call typed Go methods like ListNetwork and get back typed Go structs.

The library powers the Terraform provider for UniFi, but it stands alone in any Go program that needs to read or change controller state.

A few terms

• UniFi OS — the operating system that runs on a UniFi console (a Dream Machine, a Cloud Key, or the self-hosted UniFi OS Server). It hosts Ubiquiti's applications — Network, Protect, Access, and others — and carries its own version number (the latest is in the 5.x line).
• UniFi Network Application — the application, packaged inside UniFi OS, that actually manages your network and exposes the API this library targets. It versions independently of UniFi OS (the latest is in the 10.x line). Historically called the "UniFi Network Controller" / "UniFi Controller".
• Controller — throughout these docs, shorthand for the UniFi Network Application you talk to, reachable over HTTPS. Every version number in this documentation — 9.0.114, 10.1.78, and so on — is a UniFi Network Application version, never a UniFi OS version (a console on UniFi OS 5.x may run UniFi Network 10.x). Everything in this library is a request to your controller.
• Site — a controller hosts one or more sites (independent network configurations). A fresh controller has a single site named default.
• API surface — a set of endpoints the controller exposes. go-unifi wraps two of them (below).

Two API surfaces, one client

A single unifi.Client speaks to both of the controller's APIs. You build the client once and choose a surface per call.

Calling a resource method straight on the client is identical to calling it through c.Internal() — the Internal surface is the canonical default in 2.0.0:

nets, _ := c.Internal().ListNetwork(ctx, "default")     // Internal API: site NAME
id, _ := c.Official().Sites().ResolveID(ctx, "default") // Official API: site UUID

Not sure which to use? See Choosing a surface. The short version: start with the Internal API; reach for the Official API when you specifically want endpoints it covers.

The module: /v2

go-unifi 2.0.0 is a new major version, so its import path carries the /v2 suffix required by Go module versioning:

github.com/filipowm/go-unifi/v2

The /v2 is part of the path you go get and the path you import. Code written for go-unifi 1.x keeps working on the old path; upgrading means switching to /v2. See Installation to add it, and the migration guide if you are coming from 1.x.

Requirements at a glance

• Go 1.26 or later.
• A UniFi OS console (new-style) running UniFi Network 9.0.114 or newer. Authentication is API key only (username/password was removed in 2.0.0), and API keys require that minimum Network Application version. Older "classic" standalone controllers — the Network Application running without UniFi OS — are unsupported and fail fast at construction.
• The Official API surface additionally needs UniFi Network 10.1.78 or newer.

Where to next