@spec adopt(Req.Request.t(), String.t(), map(), keyword()) ::
  {:ok, term()} | {:error, UnifiApi.Error.t()}

Adopts a new device into the site.

Examples

{:ok, _} = UnifiApi.Network.Devices.adopt(client, site_id, %{mac: "aa:bb:cc:dd:ee:ff"})

@spec execute_action(Req.Request.t(), String.t(), String.t(), map()) ::
  {:ok, term()} | {:error, UnifiApi.Error.t()}

Executes an action on a device (e.g. restart, locate).

Examples

{:ok, _} = UnifiApi.Network.Devices.execute_action(client, site_id, device_id, %{action: "restart"})
{:ok, _} = UnifiApi.Network.Devices.execute_action(client, site_id, device_id, %{action: "locate"})

@spec execute_port_action(
  Req.Request.t(),
  String.t(),
  String.t(),
  non_neg_integer(),
  map()
) ::
  {:ok, term()} | {:error, UnifiApi.Error.t()}

Executes an action on a specific device port (e.g. PoE cycle).

Examples

# Cycle PoE on port 3
{:ok, _} = UnifiApi.Network.Devices.execute_port_action(client, site_id, device_id, 3, %{action: "cycle"})

@spec get(Req.Request.t(), String.t(), String.t()) ::
  {:ok, term()} | {:error, UnifiApi.Error.t()}

Gets a specific device by ID.

Examples

{:ok, device} = UnifiApi.Network.Devices.get(client, site_id, "device-uuid")
device["name"]   # => "US-24-250W"
device["state"]  # => "CONNECTED"

@spec get_statistics(Req.Request.t(), String.t(), String.t()) ::
  {:ok, term()} | {:error, UnifiApi.Error.t()}

Gets the latest statistics for a device.

Examples

{:ok, stats} = UnifiApi.Network.Devices.get_statistics(client, site_id, device_id)

@spec list(Req.Request.t(), String.t(), keyword()) ::
  {:ok, term()} | {:error, UnifiApi.Error.t()}

Lists all devices on a site.

Options

Supports pagination: :offset, :limit, :filter.

Examples

{:ok, devices} = UnifiApi.Network.Devices.list(client, site_id)
{:ok, devices} = UnifiApi.Network.Devices.list(client, site_id, limit: 100)

@spec list_pending(
  Req.Request.t(),
  keyword()
) :: {:ok, term()} | {:error, UnifiApi.Error.t()}

Lists devices pending adoption (not site-scoped).

Options

Supports pagination: :offset, :limit, :filter.

Examples

{:ok, pending} = UnifiApi.Network.Devices.list_pending(client)

@spec remove(Req.Request.t(), String.t(), String.t()) ::
  {:ok, term()} | {:error, UnifiApi.Error.t()}

Removes a device from the site.

Examples

{:ok, _} = UnifiApi.Network.Devices.remove(client, site_id, device_id)

@spec stream(Req.Request.t(), String.t(), keyword()) :: Enumerable.t()

Returns a lazy stream that auto-paginates through all devices on a site.

Error contract

A mid-stream error does not raise by default: the stream halts and yields {:error, %UnifiApi.StreamError{}, last_offset} as its final element, so the enumerable is heterogeneous. Match the tail:

case Enum.to_list(stream) do
  items when is_list(items) ->
    case List.last(items) do
      {:error, error, cursor} -> {:error, error, cursor}
      _ -> {:ok, items}
    end
end

Pass raise_errors: true to raise UnifiApi.StreamError instead.

Options

• :limit — items per page (default: 200)
• :filter — UniFi filter expression
• :max_pages — halt after this many successful pages (default: unbounded).
• :max_items — halt once this many items have been yielded (default: unbounded).
• :raise_errors — raise UnifiApi.StreamError on error instead of yielding the error tuple (default: false).

Examples

UnifiApi.Network.Devices.stream(client, site_id, raise_errors: true)
|> Stream.filter(& &1["state"] == "CONNECTED")
|> Enum.to_list()

@spec stream_pending(
  Req.Request.t(),
  keyword()
) :: Enumerable.t()

Returns a lazy stream that auto-paginates through pending devices.

Error contract

A mid-stream error does not raise by default: the stream halts and yields {:error, %UnifiApi.StreamError{}, last_offset} as its final element, so the enumerable is heterogeneous. Match the tail:

case Enum.to_list(stream) do
  items when is_list(items) ->
    case List.last(items) do
      {:error, error, cursor} -> {:error, error, cursor}
      _ -> {:ok, items}
    end
end

Pass raise_errors: true to raise UnifiApi.StreamError instead.

Options

• :max_pages — halt after this many successful pages (default: unbounded).
• :max_items — halt once this many items have been yielded (default: unbounded).
• :raise_errors — raise UnifiApi.StreamError on error instead of yielding the error tuple (default: false).

Examples

UnifiApi.Network.Devices.stream_pending(client)
|> Enum.to_list()