Repository navigation
Rust API
Full reference for rusteero's public surface, ported from the Python
eero-api library at v8.4.1. Method names are
the Python names verbatim, in snake_case (including the get_ prefix) — deliberate, so a
method can be searched for across both libraries by name. Every endpoint method returns
Result<Envelope, rusteero::Error> over the raw {"meta": …, "data": …} wire payload
(clear_profile_schedule returns one envelope per deleted pause, Vec<Envelope>); nothing is
transformed on the way through.
See PARITY.md in the
repository for the exhaustive method-by-method table, and the crate's own rustdoc for every
signature and its # Errors contract.
use rusteero::{Client, Session};
#[tokio::main]
async fn main() -> Result<(), rusteero::Error> {
let client = Client::builder()
.session(Some(Session::from_env("RUSTEERO_SESSION_TOKEN")?))
.build()
.await?;
let account = client.get_account(false).await?;
println!("{}", account.into_value()); // exact wire JSON
Ok(())
}ClientBuilder::build() is async — it may need to load a session from a configured
CredentialStore — so every example on this page .awaits it.
Client cache, network-id resolution, cached parent envelopes (eero-api: EeroClient)
└─ EeroApi one accessor per domain module (37), one shared Transport (eero-api: EeroAPI)
└─ Transport headers, credential placement, status → Error, GET retry, refresh-and-replay
| Layer | Reach it via | When to use it |
|---|---|---|
Client |
Client::builder() |
The default. Optional network_id, cached reads, cache invalidation on writes, cached envelopes passed as parent for you |
EeroApi |
client.api() or EeroApi::new(transport)
|
You already know the network id and want no cache. Network-scoped methods take network_id: &str first; methods whose Python signature has parent= take parent: Option<&Value> last |
Transport |
client.api().transport() or Transport::builder()
|
A raw call to a URL you resolved yourself: Transport::request(method, url, query, body) with a RequestBody, or request_with_timeout(method, url, query, body, Some(RequestTimeout)) to replace the default timeout for that one call (resource_with_timeout / nested_with_timeout do the same for a route constant) |
use rusteero::transport::RequestBody;
use rusteero::{resolve_link, EeroApi};
// EeroApi: no cache, explicit network id, explicit parent.
let net = client.api().networks().get_network("<network-id>", None).await?;
let eeros = client.api().eeros().get_eeros("<network-id>", Some(net.as_value())).await?;
// Transport: follow a link the API published, by hand.
let host = client.api().transport().api_host();
if let Some(url) = resolve_link(host, net.as_value(), "eeros")? {
let raw = client
.api()
.transport()
.request(reqwest::Method::GET, url, &[], RequestBody::None)
.await?;
}RequestBody is None, Json(Value), Form(Vec<(String, String)>) or EmptyJsonString
(the literal two-byte body "" several POST actions require).
use rusteero::storage::MemoryStore;
use rusteero::transport::StorageFailures;
use rusteero::{Client, Session};
use std::sync::Arc;
use std::time::Duration;
let client = Client::builder()
.session(Some(session)) // Option<Session>; omit to load from the store
.store(Some(Arc::new(MemoryStore::new()))) // Option<Arc<dyn CredentialStore>>; None = no persistence
.storage_failures(StorageFailures::Warn) // Warn (default) | Fatal
.cache_ttl(Duration::from_secs(60)) // default 60 s; Duration::ZERO disables caching
.user_agent(None) // None = consts::DEFAULT_USER_AGENT
.accept_language("en-US") // X-Accept-Language; default consts::DEFAULT_ACCEPT_LANGUAGE
.send_legacy_cookie(true) // also send Cookie: s=<token>; default true
.get_retries(0) // extra GET attempts on transport error / 5xx; default 0
.base_url("http://127.0.0.1:8080") // tests only: derives /2.2 and /2.3 from one root
.http_builder(reqwest::Client::builder()) // optional custom HTTP client builder (see warning)
.build()
.await?;| Option | Type | Default | Notes |
|---|---|---|---|
session |
Option<Session> |
None |
An explicit session wins over whatever the store holds; the store is still installed for later persistence |
store |
Option<Arc<dyn CredentialStore>> |
None |
Loaded once at build() when no explicit session was given |
storage_failures |
StorageFailures |
Warn |
Fatal turns any store failure (including the initial load) into Error::Storage
|
cache_ttl |
Duration |
60 s | TTL of the eight cached getters; Duration::ZERO disables caching (the getters keep no entries) |
user_agent |
Option<String> |
eero-ios/2026.8.1 (iPhone; iOS 18.5) (consts::DEFAULT_USER_AGENT) |
Printable ASCII only (field "User-Agent"). The API reads it as the app version and advertises more capabilities to this string than to consts::LEGACY_USER_AGENT (eero/3.0 (iPhone; iOS 17.0), the previous default), which you can pass to keep the old behaviour. The session refresh carries it too; LoginFlow builds its own transport (see Configuration — The User-Agent) |
accept_language |
impl Into<String> |
en-US |
Printable ASCII only (field "X-Accept-Language"), validated at build()
|
send_legacy_cookie |
bool |
true |
false sends only the X-User-Token header |
get_retries |
u32 |
0 |
Retries a GET on a network error, a timeout or any non-rate-limit error with status >= 500; never applies to writes, never to 4xx/429 or a 5xx carrying error.rate.limit; distinct from the one-shot 401 refresh-and-replay |
base_url |
impl Into<String> |
real Eero hosts |
Error::Validation { field: "base_url" } at build() if it is not an absolute URL with a scheme and a host ("" included), carries userinfo, or has an authority that cannot be parsed |
http_builder |
reqwest::ClientBuilder |
built by the crate | Redirect refusal is always applied on top. The crate's own 30 s / 10 s defaults are skipped: set timeouts on the builder yourself. A per-call RequestTimeout still replaces the builder's total timeout, but not a read_timeout set on it |
Every setter takes self by value and returns Self; build() is the only fallible and only
async step. build() validates base_url, then X-Accept-Language, then User-Agent before
it reads a configured credential store, so a bad configuration never reaches a keyring prompt or
a file read. ClientBuilder has no timeout setters; see
Configuration — Transport options.
There is no close(): dropping the Client releases its HTTP connection pool, and there is no
closed state to re-enter.
The one-time-code handshake is a type-state pair, LoginFlow → PendingLogin → Session, and
needs neither a Client nor a CredentialStore:
use rusteero::auth::flow::LoginFlow;
let pending = LoginFlow::new(None)?.start("you@example.com").await?; // email or phone; form-encoded
pending.resend().await?; // optional: ask for a new code
let session = pending.verify("123456").await?; // consumes `pending` → SessionLoginFlow::new(None) builds a transport against the real Eero cloud hosts; pass
Some(reqwest::ClientBuilder) to supply your own, or use LoginFlow::with_transport(transport) to
point it at a test server. There is no Client::login/Client::verify — an unverified login
token can never reach an authenticated endpoint by construction, since only
PendingLogin::verify can produce a Session. The login token itself becomes the session
token; the verify response body is not consulted.
use rusteero::Session;
let session = Session::from_token("<token>"); // no validation, no expiry
let session = Session::from_env("RUSTEERO_SESSION_TOKEN")?; // validated: non-empty, printable ASCII
let client = Client::builder().session(Some(session)).build().await?;A Session is nothing more than a token: there is no client-side expiry. is_valid() is a
token-presence check and the server is the sole authority on whether the token still works,
signalled by a 401.
client.is_authenticated(); // local: a non-empty token is configured
client.session(); // Option<Session>; the token stays a SecretString
client.credentials_persisted(); // false after a save the store did not keep
client.logout().await?; // -> bool; POST logout, then clears session, store and cache
client.set_session_token("<token>").await?; // validate + install + persist; resets the cache
client.clear_session_token().await?; // clear in memory and in the store; resets the cache
client.clear_auth_data().await?; // as clear_session_token, and also drops an explicit preferred network
client.api().auth().refresh_session().await?; // -> bool; POST login/refresh with the current token
client.api().auth().ensure_authenticated().await?; // Err(Error::Authentication) when no token
client.api().auth().clear_auth_data().await?; // same as AuthApi::clear_session_tokenset_session_token, clear_session_token and clear_auth_data are async. set_session_token
first validates the token (non-empty, printable ASCII, no CR/LF; field: "token"); then each of
them replaces the in-memory session before the first .await yields, so every other task already
sees the change, and runs the credential-store write on Tokio's blocking pool, where dropping the
future no longer cancels it. When several changes overlap, the last one applied wins in memory
and in the store. They need a Tokio runtime (current-thread or multi-thread).
credentials_persisted() (also on EeroApi, AuthApi and Transport) is true until a save
fails, and again after a later successful save, a clear, or when no store is configured. Under
the default StorageFailures::Warn a failed save is otherwise only a log line, so this is how a
caller learns that the session works now but will not survive a restart. A save the store
accepted but did not keep (StorageError::NotRetained) counts as failed.
logout() returns Ok(false) with no network call when no session is configured, and
otherwise Ok(true) regardless of the network outcome (a 401 is logged at DEBUG, any other
failure at WARN as Logout API call failed: …); the session is destroyed locally and in the
store either way. Under StorageFailures::Fatal a failed store clear surfaces as
Error::Storage.
Every session change resets the Client: set_session_token and clear_session_token empty
the cache and forget a preferred network that auto-discovery chose, so the next call without a
network_id rediscovers the new account's network instead of targeting the previous one's.
logout() always empties the cache, and forgets a discovered network unless it returned
Ok(false) (there was no session to end). A network you chose with set_preferred_network
survives all of them; clear_auth_data drops it too. The reset also runs when the store write
fails under StorageFailures::Fatal, since the in-memory session has already changed by then,
but not when the token is rejected as invalid.
You never need to call refresh_session() yourself. When a request answers 401 with
meta.error == "error.session.refresh", the transport refreshes once (concurrent callers share
a single in-flight refresh) and replays the request once. A terminal 401 — error.session.expired,
.invalid, .revoked, or any string outside the verification/refresh groups — from the refresh
endpoint clears the stored credential; see Troubleshooting.
Most Client methods take network_id: Option<&str> and resolve it in this order:
- The explicit
network_id, if non-empty (an empty string counts asNone). -
client.preferred_network_id(), set viaclient.set_preferred_network("<id>")— in-memory only, lost on restart, never synced with the server — or populated as a side effect of the firstget_networks()call when it was unset. The two are kept apart: an explicit network (set_preferred_network) survivesset_session_token,clear_session_tokenandlogout; a discovered one is forgotten by them;clear_auth_datadrops both. Aget_networks()that was already in flight when the session changed still returns its answer but never sets the preferred network. A networkidthe API returns as a JSON integer is used as its decimal string. -
Only for the 24 methods below, auto-discovery: the first entry of
get_networks(false). - Otherwise
Error::MissingNetworkId.
Methods that auto-discover: get_network, get_eeros, get_eero, reboot_eero,
set_guest_network, run_speed_test, get_devices, get_device, set_device_nickname,
block_device, unblock_device, pause_device, update_device_via_link, set_device_type,
get_device_labels, set_device_labels, get_profiles, get_profile, get_profile_devices,
create_profile, rename_profile, delete_profile, pause_profile, set_profile_devices.
Everything else — every settings-class read or write, get_device_priority, the data-usage,
insights, DNS, security, SQM, thread, members, notifications, DHCP, WPA3, power-saving, subnets,
WAN, DDNS and backup families, and every wrapper new in 3.0.0 — goes straight to
Error::MissingNetworkId when neither step 1 nor 2 yields an id. The cheap fix: call
get_networks(false) once, early.
Parameter position. network_id is the last parameter of almost every wrapper. The
exceptions, where it comes first because the method has no leading resource argument, are the
cached list getters (get_network, get_eeros, get_devices, get_profiles),
get_speed_tests, run_diagnostics, get_transfer_stats, set_power_saving,
create_power_saving_schedule and (after schedule_id) update_power_saving_schedule; the
single-item getters get_eero, get_device and get_profile take
(id, network_id, refresh_cache). The
wrappers new in 3.0.0 that mirror a Python method with both arguments take
(own args…, network_id, parent): parent: Option<&Value> comes after network_id
(add_to_blacklist, remove_from_blacklist, set_network_ad_block,
set_network_block_malware, set_ipv6_upstream, request_support, set_weekday_bedtime,
set_weekend_bedtime, and reboot_network(network_id, parent) /
create_burst_reporter(network_id, parent), which have no other arguments).
client.set_preferred_network("<network-id>");
let net = client.get_network(None, false).await?; // network_id first here
let devices = client.get_devices(None, false, None, None).await?; // (network_id, refresh_cache, thread, proxied_node)
let device = client.get_device("<device-id>", None, false).await?; // resource first, network_id second
client.set_upnp(true, Some("<network-id>")).await?; // value first, network_id lastEeroApi has no preferred-network concept: network_id: &str is required and comes first on
every network-scoped domain method (update_forward/update_reservation take an optional
network after the item). The eero methods and set_pppoe take the eero's id or serial first
instead, update_schedule/delete_schedule the pause, query_invite the invite code, and the
account-level methods (account(), get_networks, set_push_settings,
get_premium_customer) no identifier at all.
Wherever a method takes a network_id, eero_id, device_id/mac, profile_id, forward,
reservation or invite_id, you may pass:
| Form | Example | What the crate does |
|---|---|---|
| Bare id | "<network-id>" |
Substituted into the method's template on that family's API version. Must match [A-Za-z0-9][A-Za-z0-9._:-]* with no .. (field "id") |
| API path | "/2.2/networks/<network-id>" |
Must name exactly one resource of the method's own family (/<version>/networks/<id> where a network is expected), then joined onto the configured API host, keeping the version the path carries (field "id_or_url") |
| Absolute URL | "https://api-user.e2ro.com/2.2/networks/<network-id>" |
Must pass the origin rule below (field "url") and the same family check (field "id_or_url"), then used as-is |
A schedule (update_schedule, delete_schedule) is the one exception: a bare schedule id is
refused (field: "schedule"), since a pause lives under a network and a profile these methods
are not given; pass the pause's own path or URL, which must be exactly
/<version>/networks/{id}/profiles/{id}/schedules/{id}, or its envelope as parent.
Every path or URL a caller supplies must be a plain path: no whitespace or control character
(must not contain whitespace or control characters), no query or fragment (must not carry a query or fragment), no ./.. segment or percent-encoded dot (must not contain dot segments), and no backslash (must not contain a backslash, stricter than Python). A path or
URL of another resource family is refused with must be a path under <family> on the API host,
so /2.2/account passed where a network is expected, or a network path passed to
reboot_eero, never reaches the request line. A link the API published, read from a parent
envelope, is only shape-checked (field "link"): it is never confined to a family or a version.
The origin rule. An absolute URL is accepted only on the configured API host's origin
(Transport::api_host()): the same scheme and host (case-insensitive) and the same effective
port (an explicit default port equals none), with no userinfo at all. Another host,
http:// against an https:// host, another port, a userinfo trick
(https://api-user.e2ro.com@evil.example/…) or a suffix trick
(https://api-user.e2ro.com.evil.example/…) is Error::Validation { field: "url" } with the
fixed message must be an absolute <scheme> URL on <host> with no userinfo and no other port,
before any request is sent; a @, %, backslash or non-ASCII character in the raw authority
fails it too. Transport::request itself refuses a URL that carries userinfo
(field: "url", must not carry userinfo), since reqwest would send it as Basic credentials.
The session credential is additionally withheld from any request whose URL is not on the
configured scheme, host and port.
A child argument given as a path or URL (a profile, a MAC, an invite, a reservation or forward
on delete_*) must also belong to the addressed network:
/<version>/networks/<that network>/<family>/<id> with a single-segment id and nothing after
it, else Error::Validation { field: "child", .. } (must be a path under … for the wrong shape,
must belong to the addressed network for another network).
Every EeroApi method whose Python counterpart has parent= takes parent: Option<&Value>
(last) — the envelope of the resource you already hold (a full {"meta", "data"} response or
just its data object); so do update_forward, update_reservation, update_schedule and
delete_schedule, whose Python versions accept the item's envelope in place of its id. When supplied,
the URL is resolved from that envelope's published link (resources.settings,
resources.led_action, resources.schedules, the resource's own url, …) instead of a template,
so the request follows the version the API actually serves the resource on. The envelope is only
ever read; the raw-response contract is untouched.
Version pins. A few methods override the version after resolving the URL, whatever form the network takes and whatever version the link names:
| Pinned to | Methods | Why |
|---|---|---|
2.2 |
get_support, get_forwards, get_routing
|
Under the current User-Agent the API publishes these links on 2.3; support has a different shape there (a contacts array instead of a flat object), so all three keep their 2.2 shape |
2.3 |
set_device_nickname, pause_device
|
The same PUT on 2.2 answers 200 and is silently dropped |
2.3 |
get_multistaticip, set_multistaticip, set_secondary_wan_config, set_device_secondary_wan_access
|
The multi-static-IP and secondary-WAN endpoints are on 2.3; a 2.2 network path would otherwise carry its own version into the request (get_multistaticip is re-pinned even when it follows a published link) |
request_support, create_forward, update_forward and delete_forward are not pinned. The
data-usage family resolves the network through the parent's own url (used verbatim, never
confined to a family) plus a literal suffix, since no envelope publishes a link for it.
let net = client.api().networks().get_network("<network-id>", None).await?;
// Uses net.data.resources.settings rather than the template.
client.api().sqm().set_sqm("<network-id>", true, Some(net.as_value())).await?;
// The guest-network password write wants the *guest network's* envelope.
let guest = client.api().networks().get_guest_network("<network-id>", Some(net.as_value())).await?;
client.api().networks().set_guest_password("<network-id>", "<new-password>", Some(guest.as_value())).await?;Client does this for you. When a fresh cached envelope exists — the network from
get_network(), the eero from a cached get_eeros() list, the device from a cached
get_device() — the wrapper passes it as parent automatically. update_schedule and
delete_schedule take parent explicitly (the pause's own envelope) since they have no
network_id at all. The wrappers that take parent themselves forward yours unchanged when you
supply it and fall back to the cached network envelope otherwise; set_weekday_bedtime and
set_weekend_bedtime take the profile's envelope and have no cache fallback.
Exported from the crate root; none performs I/O or mutates an envelope. Each takes the API host
as an explicit &Url (client.api().transport().api_host()).
| Helper | Returns |
|---|---|
resolve_link(host, parent, name) |
Ok(Some(Url)) for parent["resources"][name] (or parent["data"]["resources"][name]), Ok(None) when absent |
self_url(host, parent) |
The envelope's own url, or Ok(None)
|
resource_url(host, id_or_url, template, version) |
Absolute URL from a bare id, a path or an absolute URL; template must hold exactly one {id}, and a path or URL must name one resource of the template's family (the text before {id}) |
sub_resource_url(host, id_or_url, template, link, parent, version) |
resolve_link when it yields a URL, otherwise resource_url
|
join_api_path(host, path) |
Host + a host-relative path, version prefix preserved |
rewrite_version(url, version) |
url with its leading version segment replaced (/2.3/… → /2.2/…); anything without one is returned unchanged |
rusteero::links::require_family_path(url, family, suffix, field) |
Ok(ids) when url's path is exactly /<version>/<family><suffix> (each {id} one segment, one trailing / tolerated), else Error::Validation { field, .. }. Not re-exported at the crate root |
rusteero::util::id_from_url(id_or_url) |
Trailing path segment of a URL, or the bare id unchanged |
version is rusteero::routes::ApiVersion::V2_2 or V2_3. The per-family versions live in
rusteero::consts (API_VERSION_DEFAULT, API_VERSION_DEVICE_WRITES,
API_VERSION_MULTISTATICIP, API_VERSION_SECONDARY_WAN).
Exactly eight Client methods read the cache: get_account, get_networks, get_network,
get_eeros, get_devices, get_device, get_profiles, get_profile. Each takes a
refresh_cache: bool: true skips the cache read but still writes the fresh response back.
get_eero accepts refresh_cache for signature parity but is always a live call, and a
get_devices call with a thread or proxied_node filter never reads or writes the cache.
Rules inherited from eero-api and reproduced deliberately:
- A cached envelope whose value is JSON
null,false,0,"",[]or{}is treated as a miss and refetched. -
get_networks()falls back toGET /account(throughAccountApi::get_account) and synthesisesdata.networksfrom it when/networkscomes back empty. If that/accountread fails,get_networks()returns its error, caches nothing in either entry and selects no preferred network; the next call tries again. - Auto-discovery always calls
get_networks(false), so a cached "zero networks" answer can keep discovery failing for one TTL window. -
clear_cache()drops every entry;logout(),set_session_token(),clear_session_token()andclear_auth_data()call it for you (see Check / refresh / logout for what else a session change resets).
Reads in flight during a write. Every invalidation, including clear_cache(), advances one
cache-wide generation counter. A cached getter snapshots it just before its request and stores
the response only if no invalidation ran while the request was in flight. The caller always gets
its response; a read that started before a write and finished after it simply cannot put the
pre-write answer back in the cache for everyone else. The counter is cache-wide, so a write can
also block the fill of an unrelated read that was in flight, which costs at most one extra fetch.
Device keys. A device's entry is keyed by the last path segment of the id you pass, and a
12-hex-digit MAC in any spelling (colons, dashes, dots or none, any case) is reduced to lowercase
hex, so get_device("AA:BB:CC:11:22:33", ..) and a write through "aabbcc112233" or the
device's URL hit the same entry. Only the cache key is canonicalised: requests carry your
spelling. An empty id is Error::Validation { field: "id_or_url" } before any request.
Expired entries are removed when a read finds them, so a long-lived client does not keep
devices and profiles it will never serve again; an entry that is never read again stays until a
write or clear_cache() drops it.
Writes invalidate the entries they affect and nothing else:
| Write family | Invalidated on success |
|---|---|
set_account_name, verify_account_email, verify_account_phone, set_account_consents
|
account |
Network writes (set_network_name, set_network_password, clear_network_password, guest network, run_speed_test, set_hide_5g), DNS, security (including set_ipv6_upstream), SQM, thread, DHCP (set_dhcp, set_connection_mode, set_nat_port_randomization), DDNS, WPA3, WAN config, set_subnets_config, delete_subnet, set_backup_internet, set_notification_settings, set_power_saving, apply_update, set_preferred_update_hour, set_data_usage_report_settings, set_network_block_malware, the network-level DNS-policy writes |
network[<nid>] |
set_network_ad_block |
network[<nid>], plus every profiles entry of the network when profiles is Some (even empty) |
reboot_network |
network[<nid>], eeros[<nid>] and devices[<nid>] (the list only) |
reboot_eero, set_location, set_led, set_led_brightness, set_nightlight, node_action, port_action, nightlight_override
|
eeros[<nid>] |
Device writes (set_device_nickname, pause_device, block_device, unblock_device, add_to_blacklist, remove_from_blacklist, set_device_type, set_device_labels, set_device_secondary_wan_access) |
devices[<nid>,<did>] (canonical key) and devices[<nid>]
|
create_burst_reporter |
devices[<nid>] only |
update_device_via_link |
as the device writes, plus every profiles entry of the network when profile is Some
|
create_profile, the per-profile DNS-policy writes |
profiles[<nid>] |
rename_profile, delete_profile, pause_profile, set_profile_blocked_applications, set_weekday_bedtime, set_weekend_bedtime
|
profiles[<nid>,<pid>] and profiles[<nid>]
|
set_profile_devices |
profiles[<nid>,<pid>] and profiles[<nid>], plus each named device's entry and devices[<nid>]
|
Other schedules (profile and power-saving), reservations, forwards, members, backup access points, set_subnet_content_filters, set_pppoe, set_nightlight_brightness, set_nightlight_schedule, led_cycle, mark_notifications_read, set_push_settings, set_account_email, set_account_phone, request_support
|
nothing |
account and networks are never invalidated by any network-scoped write; pass
refresh_cache = true when you need them fresh.
Signatures below are the Client wrappers. Every one returns Result<Envelope, Error> unless
noted; nid abbreviates network_id: Option<&str>.
client.get_account(refresh_cache) // GET /2.2/account via AccountApi::get_account
client.get_networks(refresh_cache)
client.set_account_name(name) client.set_account_email(email) client.verify_account_email(code)
client.set_account_phone(phone) client.verify_account_phone(code) client.set_account_consents(marketing_emails)
client.get_sms_countries() client.get_premium_customer() client.set_push_settings(&[("networkOffline", true)])
client.query_invite(invite_code)client.get_network(nid, refresh_cache)
client.get_premium_status(nid)
client.get_guest_network(nid)
client.set_guest_network(enabled, name: Option<&str>, nid) // verified live; no password here
client.set_guest_password(password, nid) // verified live
client.clear_guest_password(nid) // verified live
client.run_speed_test(nid) // verified live; result lands in get_speed_tests ~1 min later
client.get_speed_tests(nid, limit: Option<u32>, start_time: Option<&str>, end_time: Option<&str>)
client.set_network_name(name, nid) // form-encoded; disconnects clients
client.set_network_password(password, nid) // disconnects clients
client.clear_network_password(nid)
client.set_hide_5g(enabled, nid) // PUT {"value": true} / DELETE networks/{id}/temporary_flags/hide_5g
client.reboot_network(nid, parent: Option<&Value>) // POST "" to the network's reboot link; every eero restartsAn empty name or password (set_network_name, set_network_password,
set_guest_password, and set_guest_network with Some("")) is
Error::Validation { field: "name" | "password", message: "must be a non-empty string" } before
the network is resolved or anything is sent. set_hide_5g temporarily hides the 5 GHz band
(the API expires the flag itself; the network's temporary_flags.hide_5g shows it), disconnects
5 GHz clients while it takes effect, is unverified, and takes no parent because no envelope
publishes a link to it. reboot_network never auto-discovers and is unverified.
client.get_eeros(nid, refresh_cache)
client.get_eero(eero_id, nid, refresh_cache) // never cached
client.reboot_eero(eero_id, nid) // verified live: only the targeted node reboots
client.set_location(eero_id, location, nid)
client.get_connections(eero_id, nid)
client.get_led_status(eero_id, nid)
client.set_led(eero_id, enabled, nid) // verified live
client.set_led_brightness(eero_id, brightness: i32, nid) // verified live; 0–100
client.get_nightlight(eero_id, nid)
client.set_nightlight(eero_id, enabled: Option<bool>, brightness_percentage: Option<i32>, schedule: Option<Value>, nid)
client.set_nightlight_brightness(eero_id, brightness_percentage: i32, nid)
client.set_nightlight_schedule(eero_id, schedule: Value, nid)
client.node_action(eero_id, action, nid) // "POWER_CYCLE_ALL_PORTS" | "POWER_CYCLE_ALL_PORTS_AND_REBOOT"
client.port_action(eero_id, interface_number: u32, action, nid)
client.led_cycle(eero_serial, colors: &[String], duration: u32, time_per_color: u32)
client.nightlight_override(eero_id, brightness_percentage: i32, nid)
client.get_eero_support(eero_serial)client.get_devices(nid, refresh_cache, thread: Option<bool>, proxied_node: Option<bool>)
client.get_device(device_id, nid, refresh_cache)
client.get_device_priority(device_id, nid) // uncached read; never auto-discovers
client.set_device_nickname(device_id, nickname, nid) // verified; JSON PUT, always on API 2.3
client.pause_device(device_id, paused, nid) // verified; JSON PUT, always on API 2.3
client.block_device(device_id, nid) // verified; POST /blacklist with form mac=<device_id>: pass the MAC
client.unblock_device(device_id, nid) // verified; DELETE /blacklist/{mac}
client.update_device_via_link(device_id, nickname: Option<&str>, paused: Option<bool>, profile: Option<&str>, nid)
client.set_device_type(device_id, device_type, nid) // verified live
client.get_device_labels(device_id, nid)
client.set_device_labels(device_id, make_label, model_label, version_label, type_label, nid) // verified NO-OP upstream
client.get_blacklist(nid)
client.add_to_blacklist(mac, nid, parent: Option<&Value>) // verified; POST /blacklist, form mac=<mac>
client.remove_from_blacklist(mac_or_device_id, nid, parent: Option<&Value>) // verified; DELETE /blacklist/{mac_or_device_id}
client.create_burst_reporter(nid, parent: Option<&Value>) // verified; POST burst_reporters with the "" bodyblock_device/unblock_device are the device-centric names (they auto-discover the network);
add_to_blacklist/remove_from_blacklist are the direct form for a caller holding a MAC (no
auto-discovery, the network's device_blacklist link preferred). Both pairs send what you pass
as the MAC: block_device/add_to_blacklist post it as the form field mac, and
unblock_device/remove_from_blacklist append it to the block-list URL, so it must be a bare
MAC or block-list id there, never a path or URL. An empty value is Error::Validation before the
write is sent (field: "id_or_url" for the first pair, "id" for the second).
create_burst_reporter asks the network for a live-usage burst: the response carries
data.next_burst, and about 12 seconds later the device list's usage.down_mbps /
usage.up_mbps hold fresh values (zero or stale before; largely decayed again by 30 s). It runs
no speed test and changes no setting; at most one burst per minute per network. Read the
devices with get_devices(nid, true, None, None) about 12 s after the call, and never retry it
in a loop.
client.get_profiles(nid, refresh_cache)
client.get_profile(profile_id, nid, refresh_cache)
client.get_profile_devices(profile_id, nid)
client.create_profile(name, devices: Option<&[&str]>, paused: Option<bool>, nid)
client.rename_profile(profile_id, name, nid)
client.delete_profile(profile_id, nid)
client.pause_profile(profile_id, paused, nid)
client.set_profile_devices(profile_id, device_urls: &[&str], nid)
client.get_schedules(profile_id, nid)
client.create_schedule(profile_id, name, days: &[&str], start, end, enabled, nid)
client.update_schedule(schedule, &UpdateScheduleOptions { .. }, parent: Option<&Value>)
client.delete_schedule(schedule, parent: Option<&Value>)
client.clear_profile_schedule(profile_id, nid) // -> Vec<Envelope>: one DELETE per pause
client.enable_bedtime(profile_id, start_time, end_time, days: Option<&[&str]>, nid)
client.set_weekday_bedtime(profile_id, start_time, end_time, nid, parent: Option<&Value>) // POST schedules {"name": "Bedtime", "days": monday..friday, ..}
client.set_weekend_bedtime(profile_id, start_time, end_time, nid, parent: Option<&Value>) // POST schedules {"name": "Bedtime", "days": saturday, sunday, ..}Schedules are sub-resources of a profile. update_schedule/delete_schedule take the pause's
own path or URL (a bare schedule id is refused) or its envelope as parent, and no
network_id; an envelope's published url is trusted as the API published it.
clear_profile_schedule deletes each pause through its own published url.
enable_bedtime/set_*_bedtime each create one pause on every call, never update an
existing one: a POST to networks/{id}/profiles/{id}/schedules (or the profile's published
schedules link) of {"name": "Bedtime", "days": [..], "start", "end", "enabled": true}, with
the uncharacterised-write warning. parent on the two set_*_bedtime helpers is the profile's
own envelope, used only when you supply it; on success they drop profiles[<nid>,<pid>] and
profiles[<nid>], while enable_bedtime invalidates nothing.
client.get_dns_settings(nid) // the whole network object; read data.dns / data.ipv6
client.set_dns_caching(enabled, nid)
client.set_custom_dns(dns_servers: &[&str], nid) // split by family; max 2 per family
client.set_custom_dns_ipv4(dns_servers, nid)
client.set_custom_dns_ipv6(dns_servers, nid)
client.clear_custom_dns(family: Option<&str>, nid) // None | "ipv4" | "ipv6"
client.set_dns_mode(mode, custom_servers: Option<&[&str]>, nid) // "auto" | "automatic" | "custom"Every DNS write reboots every eero. Provider presets ("cloudflare", "google", …) are not
offered: read the API's own catalogue at data.dns.default_test_servers.
client.get_security_settings(nid)
client.set_wpa3(enabled, nid) client.set_band_steering(enabled, nid)
client.set_upnp(enabled, nid) client.set_ipv6(enabled, nid) // set_ipv6 sends ipv6_upstream and ipv6_downstream
client.set_ipv6_upstream(enabled, nid, parent: Option<&Value>) // PUT {"ipv6_upstream": enabled} only to networks/{id}/settings; not IPv6 DNS
client.configure_security(wpa3: Option<bool>, band_steering: Option<bool>, upnp: Option<bool>, ipv6: Option<bool>, nid)
client.set_mlo_mode(mode, nid) // "disabled" | "multi" | "single"
client.get_fast_transition(nid) client.set_fast_transition(enabled, nid)
client.set_passpoint_enabled(enabled, nid)
client.set_proxied_nodes(enabled, nid)
client.get_wpa3_per_band(nid)
client.set_wpa3_per_band(band_2_4_ghz: Option<&str>, band_5_ghz: Option<&str>, nid) // "WPA2" | "WPA2_WPA3" | "WPA3"
client.get_sqm_settings(nid) client.set_sqm(enabled, nid)
client.get_thread(nid) client.set_thread_enabled(enabled, nid)
client.update_thread(thread_enable: Option<bool>, enable_credential_syncing: Option<bool>, nid)
client.regenerate_thread_credentials(nid)set_thread_enabled(enabled, nid) is an alias of update_thread(Some(enabled), None, nid): a
JSON PUT {"thread_enable": enabled} to networks/{id}/thread, unverified, with
update_thread's warning.
client.set_dhcp(mode: Option<&str>, custom: Option<&Map<String, Value>>, custom_v2: Option<&Map<String, Value>>, nid) // "automatic" | "manual" | "custom"
client.set_connection_mode(mode, nid) // "BRIDGE" | "NAT"
client.set_nat_port_randomization(enabled, nid)
client.set_pppoe(eero_serial_or_id, username, password)
client.get_multistaticip(nid) // API 2.3; NotFound without the feature
client.set_multistaticip(config: Value, nid)
client.set_secondary_wan_config(config: Value, nid)
client.set_device_secondary_wan_access(mac, deny, nid)
client.enable_ddns(nid) client.disable_ddns(nid)
client.get_subnets_config(nid) client.set_subnets_config(config: Value, nid)
client.delete_subnet(subnet_type, nid)
client.get_subnet_content_filters(subnet_id, nid)
client.set_subnet_content_filters(filters: Value, nid)
client.get_backup_internet(nid) client.set_backup_internet(enabled, nid)
client.get_cellular_backup_usage(nid) client.get_cellular_backup_events(nid)
client.list_backup_access_points(nid)
client.add_backup_access_point(ssid, password, uuid: Option<&str>, nid)
client.update_backup_access_point(backup_network_id, &UpdateBackupAccessPointOptions { .. }, nid)
client.delete_backup_access_point(backup_network_id, nid)
client.rearrange_backup_access_points(order: &[&str], nid)
client.discover_backup_ssids(nid) client.start_backup_ssid_discovery(nid)
client.backup_connectivity_check(nid)set_dhcp's "manual" is accepted for backward compatibility and sent as "custom", the value
the API actually accepts (it refuses a literal "manual" with 400). Every DHCP write is
confirmed to restart every eero on the mesh, an outage of about eight minutes. The WAN family
always goes to API 2.3, whatever form nid takes (see Version pins).
client.get_advanced_content_filter(nid)
client.allow_domain(domain, add_cname: Option<bool>, reason_to_allow: Option<i64>, is_delete: Option<bool>, keep_profiles: Option<&[&str]>, nid)
client.allow_cnames(domains: &[&str], nid)
client.block_domain(domain, is_delete: Option<bool>, keep_profiles: Option<&[&str]>, nid)
client.allow_domain_for_profiles(domain, profiles: &[&str], override_: Option<bool>, add_cname: Option<bool>, reason_to_allow: Option<i64>, is_delete: Option<bool>, nid)
client.allow_cnames_for_profiles(domains, profiles, nid)
client.block_domain_for_profiles(domain, profiles, is_delete: Option<bool>, override_: Option<bool>, nid)
client.get_dns_policy_applications(profile_id, nid)
client.set_profile_blocked_applications(profile_id, applications: &[&str], nid)
client.set_network_ad_block(enabled, profiles: Option<&[&str]>, nid, parent: Option<&Value>) // POST networks/{id}/dns_policies/adblock
client.set_network_block_malware(enabled, nid, parent: Option<&Value>) // POST networks/{id}/dns_policies/networkset_network_ad_block sends {"enable": enabled}, plus "profiles" when profiles is Some:
the list replaces the previous one, each entry (id, path or URL) is sent as
/2.2/networks/{nid}/profiles/{pid}, and Some(&[]) is sent as [] (with enabled = true,
network-wide). set_network_block_malware sends {"block_malware": enabled}. Both are
unverified, premium (Error::PremiumRequired otherwise), resolve the network through the
parent's own url (or the template) plus a literal suffix, and log their uncharacterised-write
warning. capable: true in the network's premium_dns block alone does not mean the DNS-policy
subsystem is enabled: read the network's premium_dns block first and write only when the
stored state differs.
use rusteero::RequestTimeout;
client.get_data_usage(start, end, cadence, timezone: Option<&str>, timeout: Option<RequestTimeout>, nid) // cadence: "daily" | "hourly"
client.get_data_usage_breakdown(start, end, cadence: Option<&str>, timezone, timeout, nid)
client.get_devices_data_usage(start, end, cadence: Option<&str>, timezone, profile_id: Option<&str>, timeout, nid)
client.get_device_data_usage(device_mac, start, end, cadence, timezone, timeout, nid)
client.get_eeros_data_usage_summary(start, end, cadence, timezone, timeout, nid)
client.get_eeros_data_usage(start, end, cadence, timezone, timeout, nid) // GET networks/{id}/data_usage/eeros
client.get_eero_data_usage(eero_id, start, end, cadence, timezone, timeout, nid)
client.get_profile_data_usage(profile_id, start, end, cadence, timezone, timeout, nid)
client.get_unprofiled_devices_data_usage(start, end, cadence: Option<&str>, timezone, timeout, nid)
client.get_unprofiled_data_usage_summary(start, end, cadence, timezone, timeout, nid)
client.get_data_usage_report_settings(nid)
client.set_data_usage_report_settings(cadence, notification_day, nid)
client.get_insights(start, end, insight_type, cadence, nid)
client.get_devices_insights(start, end, cadence, insight_type, nid)
client.get_device_insights(device_id, start, end, cadence, insight_type, nid)
client.get_profiles_insights(start, end, cadence, insight_type, nid)
client.get_profile_insights(profile_id, start, end, cadence, insight_type, nid)
client.get_profile_devices_insights(profile_id, start, end, cadence, insight_type, nid)The ten time-windowed data-usage reads take timeout: Option<RequestTimeout> immediately before
nid (on DataUsageApi, immediately before parent). None keeps the transport default
(30 s total, 10 s per read). Some(t) replaces both bounds wholesale for that one request:
a field left None, or set to Duration::ZERO, is unbounded, and never falls back to the
default. A long hourly window is the case it exists for:
use rusteero::RequestTimeout;
use std::time::Duration;
let usage = client
.get_data_usage(
"2026-07-01T00:00:00Z",
"2026-07-21T00:00:00Z",
"hourly",
None,
Some(RequestTimeout::new(Some(Duration::from_secs(120)), Some(Duration::from_secs(30)))),
None,
)
.await?;RequestTimeout::total(d) is a total bound with no read bound. Every attempt of a GET
retry gets the full budget again, and the replay after an error.session.refresh 401 keeps it.
The data-usage reads are never cached and never auto-discover the network. cadence is required
on seven of them and optional on get_data_usage_breakdown, get_devices_data_usage and
get_unprofiled_devices_data_usage.
Note the argument order differs within the insights family (insight_type, cadence on
get_insights; cadence, insight_type on the others), mirroring the Python signatures.
client.get_members(nid) client.get_invites(nid)
client.create_invite(role, nid) // "admin" | "owner"
client.update_invite(invite_id, invite_nickname, nid)
client.delete_invite(invite_id, nid)
client.respond_to_invite(accept, invite_id: Option<&str>, invite_code: Option<&str>, nid)
client.cancel_pending_admin(nid) client.promote_member(member_id, nid)
client.remove_admin(user_id, nid)
client.get_notification_settings(nid)
client.set_notification_settings(settings: &[(&str, bool)], nid)
client.has_unread_notifications(nid) client.mark_notifications_read(nid)
client.get_notification_history(timestamp: Option<&str>, nid)
client.get_app_events(page_size: Option<u32>, timestamp: Option<&str>, nid)
client.get_network_scan(nid)
client.get_channel_utilization(start, end, &GetChannelUtilizationOptions { .. }, nid)
client.get_entitlement_features(nid) client.get_upsell_features(nid)
client.get_model_capabilities(nid) client.get_permissions(nid)client.get_reservations(nid)
client.create_reservation(reservation_data: Value, nid)
client.update_reservation(reservation_id, reservation_data: Value, nid)
client.delete_reservation(reservation_id, delete_forwards: Option<bool>, nid)
client.get_forwards(nid) // always on API 2.2
client.create_forward(forward_data: Value, nid)
client.update_forward(forward_id, forward_data: Value, nid)
client.delete_forward(forward_id, nid)
client.get_diagnostics(nid)
client.run_diagnostics(nid, device: Option<&str>, symptom: Option<&str>)
client.get_routing(nid) client.get_support(nid) // both always on API 2.2
client.request_support(request_data: Value, nid, parent: Option<&Value>) // JSON POST to the support link; invalidates nothing
client.get_updates(nid) client.apply_update(nid) // reboots every node
client.set_preferred_update_hour(hour: i32, nid) // POST {"preferred_update_hour": hour} to networks/{id}/updates/preferred_update_hour; 0..=23
client.get_transfer_stats(nid, device_id: Option<&str>)
client.get_ac_compat(nid)
client.get_ouicheck(serial, version, nid) // both required; 404 without them
client.set_power_saving(nid, enable: Option<bool>, power_saving_schedule_enabled: Option<bool>)
client.get_power_saving_schedules(nid)
client.create_power_saving_schedule(nid, name, days: Value, start_time, end_time, enabled)
client.update_power_saving_schedule(schedule_id, nid, &UpdatePowerSavingScheduleOptions { .. })
client.delete_power_saving_schedule(schedule_id, nid)set_preferred_update_hour sets the hour of day (network time zone) at which firmware updates
are applied; it validates hour first (Error::Validation { field: "hour", message: "must be an int from 0 to 23" }, even before the network is resolved), takes no parent (no envelope
publishes a link to it), is unverified, and drops network[<nid>] since the current value lives
in the network's updates.preferred_update_hour. request_support's body shape is not
documented upstream, so you own it; the request is not version-pinned.
Four methods with many optional fields (three writes and the get_channel_utilization read) take
an options struct instead of a long argument list. All derive Default and Clone, and a field
left None is omitted from the request body (from the query string for
get_channel_utilization):
| Struct | Path | Fields |
|---|---|---|
UpdateScheduleOptions<'a> |
rusteero::endpoints::schedule |
name, days: Option<&[&str]>, start, end, enabled
|
UpdatePowerSavingScheduleOptions<'a> |
rusteero::endpoints::power_saving |
name, days: Option<Value>, start_time, end_time, enabled
|
UpdateBackupAccessPointOptions<'a> |
rusteero::endpoints::backup_access_points |
ssid, password, enabled, uuid, connectivity: Option<Value>, created, last_updated_at
|
GetChannelUtilizationOptions<'a> |
rusteero::endpoints::events |
busy_threshold: Option<u32>, eero_id, band (one of CHANNEL_UTILIZATION_BANDS), granularity: Option<u32>, gap_data_placeholder
|
use rusteero::endpoints::schedule::UpdateScheduleOptions;
// The pause's own path or URL; a bare schedule id is refused.
client
.update_schedule(
"/2.2/networks/<network-id>/profiles/<profile-id>/schedules/<schedule-id>",
&UpdateScheduleOptions { enabled: Some(false), ..Default::default() },
None,
)
.await?;client.api() (or EeroApi::new(transport)) exposes one accessor per Python domain module.
Network-scoped methods take network_id: &str first (except forwards().update_forward and
reservations().update_reservation, which take the item and an optional network), and
parent: Option<&Value> last where they accept one; nothing is cached. A representative method
is shown for each.
| Accessor | Domain | Representative method |
|---|---|---|
account() |
The account record, profile writes and SMS country list |
get_account() (GET /2.2/account), set_name(name), get_sms_countries()
|
ac_compat() |
Legacy AC-compatibility read | get_ac_compat(network_id, parent) |
backup() |
Backup internet toggle and cellular usage/events | get_backup_internet(network_id, parent) |
backup_access_points() |
Backup Wi-Fi access points |
list(network_id, parent), add(network_id, ssid, password, uuid)
|
blacklist() |
Blocked-device list |
get_blacklist(network_id, parent), add_to_blacklist(network_id, mac, parent) (verified), remove_from_blacklist
|
burst_reporters() |
Live-usage bursts (POST-only) |
create_burst_reporter(network_id, None, parent) — sends ""; reporter_data: Option<Value> is deprecated |
data_usage() |
Data-usage time series |
get_data_usage(network_id, start, end, cadence, timezone, timeout, parent), get_breakdown, get_eeros_usage, get_report_settings
|
ddns() |
Dynamic DNS |
enable(network_id, parent), disable(network_id, parent)
|
devices() |
Connected clients |
get_devices(network_id, thread, proxied_node, parent), block_device(network_id, mac)
|
dhcp() |
DHCP, connection mode, NAT randomisation, PPPoE | set_dhcp(network_id, mode, custom, custom_v2, parent) |
diagnostics() |
Diagnostics |
get_diagnostics(network_id, parent), run_diagnostics
|
dns() |
DNS servers, mode and caching |
get_dns_settings(network_id), set_dns_mode(network_id, mode, custom_servers, parent)
|
dns_policies() |
Content filtering (premium) |
get_advanced_content_filter, get_profile_applications, set_profile_blocked_applications, set_network_ad_block(network_id, enabled, profiles, parent), set_network_block_malware(network_id, enabled, parent)
|
eeros() |
Mesh nodes |
get_eero(eero_id, parent), reboot_eero(eero_id, parent), set_led(eero_id, enabled, parent)
|
entitlements() |
Feature entitlements and upsells |
get_features(network_id), get_premium_customer()
|
events() |
App events, network scan, channel utilisation | get_app_events(network_id, page_size, timestamp, parent) |
forwards() |
Port forwards |
get_forwards(network_id, parent) (pinned to 2.2), delete_forward(network_id, forward)
|
insights() |
Insights time series | get_insights(network_id, start, end, insight_type, cadence) |
members() |
Network members and invites |
get_members(network_id, parent), create_invite(network_id, role), query_invite(invite_code)
|
networks() |
Networks, guest network, speed tests, 5 GHz hiding |
get_networks(), get_network(network_id, parent), reboot_network, set_hide_5g(network_id, enabled); get_account() is deprecated in favour of account().get_account()
|
notifications() |
Notification settings, history, push |
get_settings(network_id, parent), set_push_settings(settings)
|
ouicheck() |
OUI check | get_ouicheck(network_id, serial, version, parent) |
permissions() |
Permissions | get_permissions(network_id, parent) |
power_saving() |
Power saving and its schedules |
set_power_saving(network_id, enable, power_saving_schedule_enabled, parent), get_schedules
|
profiles() |
Profiles |
get_profiles(network_id, parent), pause_profile(network_id, profile_id, paused, parent)
|
reservations() |
DHCP reservations |
get_reservations(network_id, parent), create_reservation(network_id, reservation_data, parent)
|
routing() |
Routing (pinned to 2.2) | get_routing(network_id, parent) |
schedule() |
Profile pause schedules |
get_schedules(network_id, profile_id, parent), create_schedule, delete_schedule
|
security() |
WPA3, band steering, UPnP, IPv6, MLO, fast transition, Passpoint, proxied nodes |
get_security_settings(network_id, parent), set_upnp, set_ipv6_upstream(network_id, enabled, parent)
|
sqm() |
Smart Queue Management |
get_sqm_settings(network_id, parent), set_sqm(network_id, enabled, parent)
|
subnets() |
Subnet configuration and content filters |
get_config(network_id, parent), set_config(network_id, config), delete_subnet
|
support() |
Support |
get_support(network_id, parent) (pinned to 2.2), request_support
|
thread() |
Thread network |
get_thread(network_id, parent), update_thread, set_thread_enabled (alias of update_thread), regenerate_thread_credentials
|
transfer() |
Transfer statistics | get_transfer_stats(network_id, device_id, parent) |
updates() |
Firmware updates |
get_updates(network_id, parent), apply_update, set_preferred_update_hour(network_id, hour)
|
wan() |
Multi-static IP and secondary WAN (2.3) |
get_multistaticip(network_id, parent), set_secondary_wan_config
|
wpa3() |
Per-band WPA3 |
get_wpa3_per_band(network_id, parent), set_wpa3_per_band
|
Plus auth() (AuthApi: is_authenticated, session, logout, refresh_session,
ensure_authenticated, the async set_session_token / clear_session_token /
clear_auth_data, and credentials_persisted), credentials_persisted() on EeroApi itself,
and transport() (with Transport::user_agent() for the effective User-Agent). Several
domain methods carry a shorter name than their Client wrapper
(account().set_name vs client.set_account_name, entitlements().get_features vs
client.get_entitlement_features, data_usage().get_breakdown vs
client.get_data_usage_breakdown, data_usage().get_eeros_usage vs
client.get_eeros_data_usage, notifications().get_settings vs
client.get_notification_settings, backup_access_points().list vs
client.list_backup_access_points), exactly as in the Python library.
The API accepts unrecognised JSON keys with 200 OK and discards them, so "it returned 200" is
not evidence a write applied. The crate therefore distinguishes:
-
Verified live writes (no warning):
set_led,set_led_brightness,reboot_eero,run_speed_test,set_guest_network,set_guest_password,clear_guest_password,set_device_nickname,pause_device,set_device_type,add_to_blacklistandblock_device(a form-encodedmac, verified 2026-10-06),remove_from_blacklistandunblock_device, andcreate_burst_reporterwith the""body (verified 2026-10-20). A deprecated non-emptyreporter_databody on the domain method is not covered by that check and still warns. -
Every other write logs one fixed
WARNINGthroughrusteero::links::warn_uncharacterised_writeafter the URL is resolved and the arguments validated, immediately before the request. The message never includes a caller-supplied identifier. DNS writes log it before the URL is resolved, as upstream does, andset_profile_deviceslogs two (set devices for profileandupdate profile). -
Settings-class writes say so in their warning — they may reboot every eero, as the DNS write
path was confirmed to: every DNS write,
set_dhcp,set_connection_mode,set_nat_port_randomization,set_mlo_mode,set_wpa3/set_band_steering/set_upnp/set_ipv6/set_ipv6_upstream/configure_security,set_secondary_wan_config,set_device_secondary_wan_access, andapply_update(reboots every node).set_sqmis a settings-class write too, but its warning (set SQM for network, as upstream) does not say so. Forset_dhcpthe restart is confirmed: about eight minutes of outage per write.reboot_networkrestarts every eero by design, andset_hide_5gdisconnects 5 GHz clients. -
set_device_labelswas verified upstream to return200and change nothing.
The discipline the warning asks for: read the current state, compare, write only on a difference, and never retry a failed write in a loop.
let net = client.get_network(None, false).await?;
if net.data()["upnp"] != serde_json::json!(true) {
client.set_upnp(true, None).await?;
}Error is #[non_exhaustive] and mirrors eero-api's exception hierarchy one-to-one. Every
server-driven variant carries envelope: Option<Value> (the raw parsed response) and
error_code: Option<String> (meta.error), reachable uniformly through Error::envelope(),
Error::error_code() and Error::status(). Messages are fixed labels — the recognised catalogue
string, or "unrecognised error string" — never the response body. A refused redirect's message
names the request path (below), and an Error::Network's text is reqwest's own, which includes
the full request URL.
| Variant | Raised when |
|---|---|
Authentication { message, envelope, error_code, status } |
Every HTTP 401 (after the refresh-and-replay attempt, when applicable), with status: Some(401) — including a 401 carrying error.rate.limit; locally, "Not authenticated" when a call needs a session and none is configured; LoginFlow::start/PendingLogin::verify wrap other API errors as "Login failed: …"/"Verification failed: …". The local and wrapped forms carry status: None; a real 401 from login or verify keeps Some(401)
|
RateLimit { message, retry_after, envelope, error_code, status } |
HTTP 429, or error.rate.limit on any status other than 401; status is the response's own (Some(429), Some(400), Some(503), …). retry_after is the parsed Retry-After header (delta-seconds, or an IMF-fixdate, RFC 850 or asctime date read as UTC), capped at 24 h (consts::RETRY_AFTER_MAX) |
Network(reqwest::Error) |
DNS, TCP, TLS or connect failure |
Timeout |
The request exceeded its total or read bound (the transport default, or a per-call RequestTimeout) |
Api { status, message, envelope, error_code, url } |
Any other non-2xx status, every recognised domain string, an unrecognised string; also client-side, with the response status: a refused redirect (Redirect not followed: <status> at <path> -> <Location host>), a body over 10 MiB, invalid JSON on a 2xx (Invalid JSON response (<n> bytes)), a 2xx whose JSON is not an object (Unexpected JSON response: expected an object), a 2xx body that is not UTF-8 (Response body is not valid UTF-8). A non-2xx body is decoded lossily, so a stray invalid byte never hides its status |
AccessDenied { status, message, envelope, error_code } |
HTTP 403 with error.access.denied. Not an auth error; credentials kept |
ClientBlocked { .. } |
error.app.version.blocked on any status |
NotFound { status, message, envelope, error_code } |
HTTP 404, unless meta.error is in a status-independent group (premium, feature-unavailable, client-blocked, rate-limit) |
PremiumRequired { status: Option<u16>, .. } |
error.premium.user_not_subscribed or error.partner.unavailable on any status |
FeatureUnavailable { status: Option<u16>, .. } |
error.eero.offline, error.network.unavailable, error.eero.not.capable, … on any status |
Validation { field, message, envelope, error_code } |
Locally, before any request (bad id, a path or URL outside the method's family, off-origin or userinfo URL, invalid IP literal, bad cadence/mode/band, empty name, password or token, an hour outside 0..=23, non-ASCII header, unusable base_url); from the API, HTTP 400 with a VALIDATION string (field == "request"). See Troubleshooting for the field names |
MissingNetworkId |
No network_id, no preferred network, and no auto-discovery for this method |
Storage(StorageError) |
A credential-store operation failed (surfaces under StorageFailures::Fatal, or from FileStore/KeyringStore directly) |
Json(serde_json::Error) |
Envelope::data_as::<T>() could not deserialise data into T
|
Classification precedence, ported from eero-api: a 401 always wins; then a string in a
status-independent group (premium, feature-unavailable, client-blocked, rate-limit) picks the
variant regardless of status; then the HTTP status picks it; everything else is Api.
use rusteero::{classify_error_code, Error, ErrorGroup};
match client.create_reservation(serde_json::json!({ /* … */ }), None).await {
Ok(env) => println!("{}", env.data()),
Err(Error::NotFound { .. }) => eprintln!("no such network"),
Err(Error::AccessDenied { .. }) => eprintln!("this account may not do that"),
Err(Error::Validation { field, message, .. }) => eprintln!("{field}: {message}"),
Err(Error::Api { error_code, .. }) if error_code.as_deref() == Some("error.assignment.ip.unavailable") => {
eprintln!("pick another address");
}
Err(e) if e.is_auth_error() => eprintln!("re-authenticate"),
Err(e) => {
eprintln!("{:?}", classify_error_code(e.error_code())); // Option<ErrorGroup>
return Err(e);
}
}ErrorGroup (rusteero::ErrorGroup) has the eleven catalogue groups — Session,
SessionRefresh, Verification, AccessDenied, NotFound, RateLimit, Validation,
Premium, FeatureUnavailable, ClientBlocked, Domain — and the member strings are the
pub const slices in rusteero::errors (SESSION_ERRORS, DOMAIN_ERRORS, …).
Error::is_auth_error() is true for Authentication whatever its status, false for
RateLimit whatever its status, and otherwise true exactly when status() == Some(401); a 403
is deliberately not an auth error.
Every endpoint method returns Envelope, a lossless view over the raw wire JSON:
let env = client.get_account(false).await?;
env.meta().code; // Option<u16>
env.meta().error; // Option<String> — e.g. "error.session.refresh"
env.meta().extra; // any other meta keys, verbatim
env.data(); // &serde_json::Value, or &Value::Null if "data" is absent
env.as_value(); // &Value: the whole envelope, borrowed
env.data_as::<MyAccount>()?; // deserialise `data` into your own serde type
env.into_value(); // the exact JSON value this envelope was built fromdata_as::<T>() is the crate's only source of Error::Json — it means T's shape didn't match
data, not that the response was malformed (a malformed 2xx body is already Error::Api before
an Envelope exists). Envelope's Debug prints only meta.code and the shape of data,
since a cached response can carry a Wi-Fi password.
| Feature | Default | Effect |
|---|---|---|
keyring |
on | Enables KeyringStore (and the keyring rows of create_storage), backed by the OS keyring |
typed |
off | Reserved; currently a no-op. Use Envelope::data_as::<T>() with your own types |