# Docs

- [go-unifi](/docs): A Go client for the UniFi Network controller API — type-safe access to networks, clients, devices, firewall, and more.
- Getting Started
  - [Introduction](/docs/getting-started): What go-unifi is, its two API surfaces, the /v2 module, and the controller versions it requires.
  - [Installation](/docs/getting-started/installation): Add the go-unifi v2 module, learn its import paths, and verify the install with a tiny program.
  - [Authentication](/docs/getting-started/authentication): go-unifi authenticates with an API key only — how to create one and which controller versions support it.
  - [Quickstart](/docs/getting-started/quickstart): Connect to a UniFi controller and list its networks in one runnable Go program.
  - [Connecting](/docs/getting-started/connecting): Build the client — the controller URL, TLS for self-signed certs, timeouts, and startup behavior.
- Guides
  - [Guides](/docs/guides): Task-oriented recipes for go-unifi — surfaces, pagination, sites, networks, devices, firewall, and more.
  - [Choosing a surface](/docs/guides/choosing-a-surface): Internal vs Official — what each API surface is, how to reach it, the capability gate, and which to pick.
  - [Using the Official API](/docs/guides/official-api): Reach the Official UniFi OpenAPI through c.Official() — fluent per-group accessors, uniform method shapes, and site UUIDs.
  - [Pagination & filtering](/docs/guides/pagination-and-filtering): Page through Official API results — bounded pages with ListPage, lazy streaming with ListAll and Collect, and the filter DSL.
  - [Sites](/docs/guides/sites): List sites on both surfaces and bridge the site-name (Internal) vs UUID (Official) identifier gap.
  - [Networks](/docs/guides/networks): Create, read, update and delete UniFi networks (VLANs, LANs, WANs) and their related routing, DHCP, DNS and port-forward resources.
  - [Devices](/docs/guides/devices): List, inspect, adopt and forget UniFi devices (APs, switches, gateways), and read their connection state.
  - [Clients & users](/docs/guides/clients-and-users): Manage UniFi client stations — list, create, block, kick and forget by MAC — plus user groups and RADIUS accounts.
  - [Firewall](/docs/guides/firewall): Manage firewall groups and rules, zone-based firewall policies, and content filtering on the Internal API.
  - [Wireless](/docs/guides/wireless): Manage WLANs, AP and WLAN groups, RADIUS profiles, channel plans, and the guest hotspot — including Official-API vouchers and broadcasts.
  - [Settings](/docs/guides/settings): Read and write site-level controller settings — the typed per-setting pairs and the generic key-based GetSetting/SetSetting.
  - [Feature Flags](/docs/guides/feature-flags): Check whether a UniFi controller supports and enables a capability before you rely on it, using IsFeatureEnabled, GetFeature, and ListFeatures.
  - [File Uploads](/docs/guides/file-uploads): Upload Hotspot portal files to a UniFi controller from a path on disk or any io.Reader with UploadPortalFile and UploadPortalFileFromReader.
  - [Traffic Flows](/docs/guides/traffic-flows): Query the UniFi controller's traffic-flow log with GetTrafficFlows — a filtered, paginated view of allowed and blocked connections.
  - [Error Handling](/docs/guides/error-handling): React to UniFi controller failures with the ErrNotFound, Official-API, and old-style sentinels, the rich ServerError, and client-side ValidationError.
  - [Testing](/docs/guides/testing): Test code that talks to a UniFi controller without a controller, using the generated unifi.ClientMock and the per-group Official API mocks.
- Advanced
  - [Advanced](/docs/advanced): Fine-tune the client beyond the basics — configuration, raw HTTP calls, interceptors, logging, validation, concurrency, and more.
  - [Configuration](/docs/advanced/configuration): Tune ClientConfig beyond URL and APIKey — timeouts, User-Agent, custom HTTP transports, error handling, and custom validators.
  - [Raw HTTP calls](/docs/advanced/raw-http): Reach UniFi endpoints that have no generated method using Do/Get/Post/Put/Patch/Delete, with correct path resolution.
  - [Interceptors](/docs/advanced/interceptors): Hook into every request and response with ClientInterceptor — for logging, metrics, or header injection — and avoid the response body-read hazard.
  - [Logging](/docs/advanced/logging): Configure the client's Logger — the built-in slog logger, levels, wrapping your own *slog.Logger, or a fully custom implementation.
  - [Validation](/docs/advanced/validation): Control request-body validation modes (soft, hard, disabled), inspect ValidationError, and register custom regex validators.
  - [Concurrency](/docs/advanced/concurrency): The UniFi client is safe for concurrent use — share one client across goroutines instead of creating many.
  - [Compatibility](/docs/advanced/compatibility): Which UniFi controller versions each go-unifi release supports, plus a changelog of breaking compatibility changes.
  - [Troubleshooting](/docs/advanced/troubleshooting): Common symptoms — TLS failures, version mismatches, JSON decode errors and validation rejections — and how to fix them.
- Reference
  - [Reference](/docs/reference): Curated reference for the go-unifi exported API — client, configuration, errors, resources, and the Official OpenAPI surface.
  - [Client](/docs/reference/client): NewClient and the Client interface — the transport and lifecycle methods plus the Internal and Official surface accessors.
  - [Configuration types](/docs/reference/configuration-types): Every ClientConfig field with its type and default, plus the ValidationMode, APIStyle, and logging enums.
  - [Errors](/docs/reference/errors): The go-unifi error model — ServerError, ValidationError, and the Err sentinels you match with errors.Is and errors.As.
  - [Surface Coverage](/docs/reference/coverage): Which UniFi resources are reachable through the Internal API, the Official API, or both.

  - **API surfaces**
  - Official API
    - [Official API](/docs/reference/official-api): The c.Official() surface — the controller's own integration/v1 OpenAPI, addressed by site UUID - fluent per-group clients, the uniform method shape, and the ListOptions / Page / Collect pagination primitives.
    - OpenAPI Spec
      - [UniFi API (OpenAPI)](/docs/reference/official-api/api): Overview of the Official UniFi Network API (integration/v1) — base path, API-key auth, the filter DSL, and the error model.
      - Access control (acl rules)
        - [Create ACL Rule](/docs/reference/official-api/api/access-control-\(acl-rules\)/createAclRule): Create a new user defined ACL rule on a site.
        - [Delete ACL Rule](/docs/reference/official-api/api/access-control-\(acl-rules\)/deleteAclRule): Delete an existing user defined ACL rule on a site.
        - [Get ACL Rule](/docs/reference/official-api/api/access-control-\(acl-rules\)/getAclRule)
        - [Get User-Defined ACL Rule Ordering](/docs/reference/official-api/api/access-control-\(acl-rules\)/getAclRuleOrdering): Retrieve user-defined ACL rule ordering on a site.
        - [List ACL Rules](/docs/reference/official-api/api/access-control-\(acl-rules\)/getAclRulePage): Retrieve a paginated list of all ACL rules on a site.
        - [Update ACL Rule](/docs/reference/official-api/api/access-control-\(acl-rules\)/updateAclRule): Update an existing user defined ACL rule on a site.
        - [Reorder User-Defined ACL Rules](/docs/reference/official-api/api/access-control-\(acl-rules\)/updateAclRuleOrdering): Reorder user-defined ACL rules on a site.
      - Application info
        - [Get Application Info](/docs/reference/official-api/api/application-info/getInfo): Retrieve general information about the UniFi Network application.
      - Clients
        - [Execute Client Action](/docs/reference/official-api/api/clients/executeConnectedClientAction): Perform an action on a specific connected client. The request body must include the action name and any applicable input arguments.
        - [Get Connected Client Details](/docs/reference/official-api/api/clients/getConnectedClientDetails): Retrieve detailed information about a specific connected client, including name, IP address, MAC address, connection type and access information.
        - [List Connected Clients](/docs/reference/official-api/api/clients/getConnectedClientOverviewPage): Retrieve a paginated list of all connected clients on a site, including physical devices (computers, smartphones) and active VPN connections.
      - Dns policies
        - [Create DNS Policy](/docs/reference/official-api/api/dns-policies/createDnsPolicy): Create a new DNS policy on a site.
        - [Delete DNS Policy](/docs/reference/official-api/api/dns-policies/deleteDnsPolicy): Delete an existing DNS policy on a site.
        - [Get DNS Policy](/docs/reference/official-api/api/dns-policies/getDnsPolicy): Retrieve specific DNS policy.
        - [List DNS Policies](/docs/reference/official-api/api/dns-policies/getDnsPolicyPage): Retrieve a paginated list of all DNS policies on a site.
        - [Update DNS Policy](/docs/reference/official-api/api/dns-policies/updateDnsPolicy): Update an existing DNS policy on a site.
      - Firewall
        - [Create Firewall Policy](/docs/reference/official-api/api/firewall/createFirewallPolicy): Create a new firewall policy on a site.
        - [Create Custom Firewall Zone](/docs/reference/official-api/api/firewall/createFirewallZone): Create a new custom firewall zone on a site.
        - [Delete Firewall Policy](/docs/reference/official-api/api/firewall/deleteFirewallPolicy): Delete an existing firewall policy on a site.
        - [Delete Custom Firewall Zone](/docs/reference/official-api/api/firewall/deleteFirewallZone): Delete a custom firewall zone from a site.
        - [List Firewall Policies](/docs/reference/official-api/api/firewall/getFirewallPolicies): Retrieve a list of all firewall policies on a site.
        - [Get Firewall Policy](/docs/reference/official-api/api/firewall/getFirewallPolicy): Retrieve specific firewall policy.
        - [Get User-Defined Firewall Policy Ordering](/docs/reference/official-api/api/firewall/getFirewallPolicyOrdering): Retrieve user-defined firewall policy ordering for a specific source/destination zone pair.
        - [Get Firewall Zone](/docs/reference/official-api/api/firewall/getFirewallZone): Get a firewall zone on a site.
        - [List Firewall Zones](/docs/reference/official-api/api/firewall/getFirewallZones): Retrieve a list of all firewall zones on a site.
        - [Patch Firewall Policy](/docs/reference/official-api/api/firewall/patchFirewallPolicy): Patch an existing firewall policy on a site.
        - [Update Firewall Policy](/docs/reference/official-api/api/firewall/updateFirewallPolicy): Update an existing firewall policy on a site.
        - [Reorder User-Defined Firewall Policies](/docs/reference/official-api/api/firewall/updateFirewallPolicyOrdering): Reorder user-defined firewall policies for a specific source/destination zone pair.
        - [Update Firewall Zone](/docs/reference/official-api/api/firewall/updateFirewallZone): Update a firewall zone on a site.
      - Hotspot
        - [Generate Vouchers](/docs/reference/official-api/api/hotspot/createVouchers): Create one or more Hotspot vouchers.
        - [Delete Voucher](/docs/reference/official-api/api/hotspot/deleteVoucher): Remove a specific Hotspot voucher.
        - [Delete Vouchers](/docs/reference/official-api/api/hotspot/deleteVouchers): Remove Hotspot vouchers based on the specified filter criteria.
        - [Get Voucher Details](/docs/reference/official-api/api/hotspot/getVoucher): Retrieve details of a specific Hotspot voucher.
        - [List Vouchers](/docs/reference/official-api/api/hotspot/getVouchers): Retrieve a paginated list of Hotspot vouchers.
      - Networks
        - [Create Network](/docs/reference/official-api/api/networks/createNetwork): Create a new network on a site.
        - [Delete Network](/docs/reference/official-api/api/networks/deleteNetwork): Delete an existing network on a site.
        - [Get Network Details](/docs/reference/official-api/api/networks/getNetworkDetails): Retrieve detailed information about a specific network.
        - [Get Network References](/docs/reference/official-api/api/networks/getNetworkReferences): Retrieve references to a specific network.
        - [List Networks](/docs/reference/official-api/api/networks/getNetworksOverviewPage): Retrieve a paginated list of all Networks on a site.
        - [Update Network](/docs/reference/official-api/api/networks/updateNetwork): Update an existing network on a site.
      - Sites
        - [List Local Sites](/docs/reference/official-api/api/sites/getSiteOverviewPage): Retrieve a paginated list of local sites managed by this Network application.
      - Supporting resources
        - [List Countries](/docs/reference/official-api/api/supporting-resources/getCountries): Returns ISO-standard country codes and names,
        - [List Device Tags](/docs/reference/official-api/api/supporting-resources/getDeviceTagPage): Returns all device tags defined within a site, which can be used for WiFi Broadcast assignments.
        - [List DPI Application Categories](/docs/reference/official-api/api/supporting-resources/getDpiApplicationCategories): Returns predefined Deep Packet Inspection (DPI) application categories used for traffic identification and filtering.
        - [List DPI Applications](/docs/reference/official-api/api/supporting-resources/getDpiApplications): Lists DPI-recognized applications grouped under categories. Useful for firewall or traffic analytics integration.
        - [List Radius Profiles](/docs/reference/official-api/api/supporting-resources/getRadiusProfileOverviewPage): Returns available RADIUS authentication profiles, including configuration origin metadata.
        - [List Site-To-Site VPN Tunnels](/docs/reference/official-api/api/supporting-resources/getSiteToSiteVpnTunnelPage): Retrieve a paginated list of all site-to-site VPN tunnels on a site.
        - [List VPN Servers](/docs/reference/official-api/api/supporting-resources/getVpnServerPage): Retrieve a paginated list of all VPN servers on a site.
        - [List WAN Interfaces](/docs/reference/official-api/api/supporting-resources/getWansOverviewPage): Returns available WAN interface definitions for a given site,
      - Switching
        - [Get LAG Details](/docs/reference/official-api/api/switching/getLag): Retrieve LAG details.
        - [List LAGs](/docs/reference/official-api/api/switching/getLagPage): Retrieve a paginated list of all LAGs (Link Aggregation Groups) on a site.
        - [Get MC-LAG Domain](/docs/reference/official-api/api/switching/getMcLagDomain): Retrieve MC-LAG Domain details.
        - [List MC-LAG Domains](/docs/reference/official-api/api/switching/getMcLagDomainPage): Retrieve a paginated list of all MC-LAG Domains on a site.
        - [Get Switch Stack](/docs/reference/official-api/api/switching/getSwitchStack): Retrieve Switch Stack details.
        - [List Switch Stacks](/docs/reference/official-api/api/switching/getSwitchStackPage): Retrieve a paginated list of all Switch Stacks on a site.
      - Traffic matching lists
        - [Create Traffic Matching List](/docs/reference/official-api/api/traffic-matching-lists/createTrafficMatchingList): Create a new traffic matching list on a site.
        - [Delete Traffic Matching List](/docs/reference/official-api/api/traffic-matching-lists/deleteTrafficMatchingList): Delete an exist traffic matching list on a site.
        - [Get Traffic Matching List](/docs/reference/official-api/api/traffic-matching-lists/getTrafficMatchingList): Get an exist traffic matching list on a site.
        - [List Traffic Matching Lists](/docs/reference/official-api/api/traffic-matching-lists/getTrafficMatchingLists): Retrieve all traffic matching lists on a site.
        - [Update Traffic Matching List](/docs/reference/official-api/api/traffic-matching-lists/updateTrafficMatchingList): Update an exist traffic matching list on a site.
      - Unifi devices
        - [Adopt Devices](/docs/reference/official-api/api/unifi-devices/adoptDevice): Adopt a device to a site.
        - [Execute Adopted Device Action](/docs/reference/official-api/api/unifi-devices/executeAdoptedDeviceAction): Perform an action on an specific adopted device. The request body must include the action name and any applicable input arguments.
        - [Execute Port Action](/docs/reference/official-api/api/unifi-devices/executePortAction): Perform an action on a specific device port. The request body must include the action name and any applicable input arguments.
        - [Get Adopted Device Details](/docs/reference/official-api/api/unifi-devices/getAdoptedDeviceDetails): Retrieve detailed information about a specific adopted device, including firmware versioning, uplink state, details about device features and interfaces (ports, radios) and other key attributes.
        - [Get Latest Adopted Device Statistics](/docs/reference/official-api/api/unifi-devices/getAdoptedDeviceLatestStatistics): Retrieve the latest real-time statistics of a specific adopted device, such as uptime, data transmission rates, CPU and memory utilization.
        - [List Adopted Devices](/docs/reference/official-api/api/unifi-devices/getAdoptedDeviceOverviewPage): Retrieve a paginated list of all adopted devices on a site, including basic device information.
        - [List Devices Pending Adoption](/docs/reference/official-api/api/unifi-devices/getPendingDevicePage): Retrieve a paginated list of devices pending adoption, including basic device information.
        - [Remove (Unadopt) Device](/docs/reference/official-api/api/unifi-devices/removeDevice): Removes (unadopts) an adopted device from the site. If the device is online, it will be reset to factory defaults.
      - Wifi broadcasts
        - [Create Wifi Broadcast](/docs/reference/official-api/api/wifi-broadcasts/createWifiBroadcast): Create a new Wifi Broadcast on the specified site.
        - [Delete Wifi Broadcast](/docs/reference/official-api/api/wifi-broadcasts/deleteWifiBroadcast): Delete an existing Wifi Broadcast from the specified site.
        - [Get Wifi Broadcast Details](/docs/reference/official-api/api/wifi-broadcasts/getWifiBroadcastDetails): Retrieve detailed information about a specific Wifi.
        - [List Wifi Broadcasts](/docs/reference/official-api/api/wifi-broadcasts/getWifiBroadcastPage): Retrieve a paginated list of all Wifi Broadcasts on a site.
        - [Update Wifi Broadcast](/docs/reference/official-api/api/wifi-broadcasts/updateWifiBroadcast): Update an existing Wifi Broadcast on the specified site.
  - Internal API
    - [Internal API](/docs/reference/internal-api): The Internal (legacy) surface — every resource as Verb-Resource methods on the client, addressed by site name.
    - [Resources](/docs/reference/internal-api/resources): A curated map of the Internal (legacy) API resource methods — grouped by domain, with each resource's CRUD verbs and the by-MAC, reorder, and upload extras.
    - [Settings](/docs/reference/internal-api/settings): The controller settings catalogue — the generic GetSetting/SetSetting pair, the typed GetSetting/UpdateSetting methods, and the SettingKey constants.
    - [Feature constants](/docs/reference/internal-api/feature-constants): The features package — string constants naming UniFi controller feature flags, for use with GetFeature / IsFeatureEnabled / ListFeatures.
- Migrating
  - [Migrating](/docs/migrating): Pick the right guide — upgrading go-unifi 1.x to 2.0, or switching from paultyng/go-unifi.
  - [Upgrading from 1.x](/docs/migrating/from-1.x): A task-oriented walkthrough of every breaking change between go-unifi 1.x and 2.0, with before/after code and grep hints.
  - [Breaking changes](/docs/migrating/breaking-changes): The authoritative 2.0.0 changelog — every public-API behavior and signature change, its impact and provenance, plus what's deferred to 3.0.0.
  - [From paultyng/go-unifi](/docs/migrating/from-paultyng): Switch from the upstream paultyng/go-unifi to filipowm/go-unifi — only client construction and authentication differ.
- For Library Developers
  - [Architecture](/docs/developers): How go-unifi is built — generated resource code vs. the hand-written client layer, the Client interface, and the one-way unifi → official dependency.
  - [Code Generation](/docs/developers/code-generation): The two-pass codegen pipeline — the legacy Internal API and the Official OpenAPI surface — and the two independent version axes that pin them.
  - [Customizations](/docs/developers/customizations): Steer the Internal-API code generator with customizations.yml — field type/name/tag overrides, exclude predicates, custom client functions, and JSON unmarshalers.
  - [Regenerating](/docs/developers/regenerating): The exact commands to regenerate go-unifi — resources, the DeviceState stringer, the moq mock — plus how to refresh a frozen version snapshot.
  - [Testing](/docs/developers/testing): go-unifi's test strategy — testify, table-driven cases, httptest controller fixtures, golden/determinism tests, and the generated mocks.
  - [Release Process](/docs/developers/release-process): How go-unifi ships — tag-driven goreleaser, automated CHANGELOG, the version markers, the daily regeneration CI, and the docs deploy.
  - [Contributing](/docs/developers/contributing): Conventions for contributing to go-unifi — formatting, context-first methods, error wrapping, the generated-vs-hand-written rule, and the pre-push gate.