Calling the Integration API

@alchemy-unifi/network-sdk is an Effect SDK for the UniFi Network Integration API (Network 10.6), generated from UniFi’s OpenAPI spec. Use it for scripts, for things the provider doesn’t manage yet, or for reading data such as clients and devices.

Install

npm

npm install @alchemy-unifi/network-sdk effect

pnpm

pnpm add @alchemy-unifi/network-sdk effect

yarn

yarn add @alchemy-unifi/network-sdk effect

List the networks

Each operation is a function returning an Effect, which needs Credentials and an HttpClient:

src/list-networks.ts

import * as Sdk from "@alchemy-unifi/network-sdk";
import * as Effect from "effect/Effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as Layer from "effect/Layer";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";

const credentials = Layer.succeed(
  Sdk.Credentials,
  Effect.succeed({
    baseUrl: "https://192.168.1.1/proxy/network/integration",
    apiKey: Redacted.make("<network api key>"),
  }),
);

export const program = Effect.gen(function* () {
  const [site] = (yield* Sdk.getSiteOverviewPage({})).data;
  if (site === undefined) return;
  // Paginated operations also have `.items(...)` (a Stream of every item) and `.pages(...)`.
  const networks = yield* Stream.runCollect(Sdk.getNetworksOverviewPage.items({ siteId: site.id }));
  for (const network of networks) yield* Effect.log(`${network.name}: VLAN ${network.vlanId}`);
}).pipe(Effect.provide(Layer.mergeAll(credentials, FetchHttpClient.layer)));

Pick the base URL

Console	baseUrl	Key
UniFi OS console, directly	https://<console>/proxy/network/integration	Network API key
Self-hosted controller	https://<host>:8443/integration	Network API key
Any console, through ui.com	https://api.ui.com/v1/connector/consoles/<console id>/proxy/network/integration	Site Manager API key

Consoles use self-signed certificates, which FetchHttpClient rejects. Use a client that trusts the console’s certificate, or the provider, which handles pinning.

Handle errors

• Each operation fails with typed errors for the responses UniFi documents (NotFound, UnprocessableEntity, …). Anything else becomes UnknownUnifiNetworkError, and a response that doesn’t match the schema becomes UnifiNetworkParseError.
• Throttling and transient failures are retried by default. Opt out with Sdk.Retry.none.
• Fields marked sensitive (Wi-Fi passphrases) are Redacted.

Gotchas

• Some fields are unknown, because UniFi’s spec gives them no schema: firewall and ACL sourceFilter/destinationFilter, Wi-Fi radiusConfiguration, a device’s accessPoint, and a few metadata fields.
• The console requires some fields the spec calls optional, depending on others (see the reference). The provider’s types enforce them; the SDK’s don’t.
• Requests can’t carry fields the console doesn’t accept, so a GET response sent back as an update fails until you drop id, metadata and (for networks) default.
• ui.com allows 100 requests a minute per console. The SDK retries 429s, but doesn’t pace itself.