Repository navigation
Migration
Upgrade guide between eero-api major and preference-affecting minor releases.
What broke: Pydantic models were deleted (eero.models no longer exists) and every API
method now returns the raw Eero Cloud API envelope β {"meta": {...}, "data": {...}} β instead
of a typed object. There is no field renaming (wan_ip is no longer surfaced as public_ip)
and no status normalization.
| Before (v1.x) | After (v2.0.0+) |
|---|---|
from eero.models import Network |
(module does not exist β delete the import) |
network.name |
response["data"]["name"] |
network.public_ip |
response["data"]["wan_ip"] |
for network in await client.get_networks(): |
data = response.get("data") or {} / networks = data if isinstance(data, list) else (data.get("networks") or data.get("data") or []) β see Raw Response Format
|
# Before
networks = await client.get_networks()
for network in networks:
print(network.name, network.status)
# After
response = await client.get_networks()
data = response.get("data") or {}
networks = data if isinstance(data, list) else (data.get("networks") or data.get("data") or [])
for network in networks:
print(network["name"], network["status"])See Raw Response Format β the
data["networks"]value is not guaranteed to be a list, so use the shape-tolerant extraction above instead of indexing["data"]["networks"]directly.
Note:
EeroNetworkStatusandEeroDeviceStatusstill exist ineero.const, but they are no longer exported from top-leveleero(__all__) and the SDK no longer normalizes any field into them β the raw string comes straight from the API.
Checklist:
- Delete every
from eero.models import ...line β the module is gone. - Replace all attribute access on API results (
x.foo) with dict access (x["data"]["foo"]). - Replace
for x in await client.get_X()withfor x in (await client.get_X())["data"][...]β iterating the raw return value directly walks the envelope's top-level keys ("meta","data"), not your records. - Search for any renamed-field assumptions (e.g.
public_ip) and switch to the raw upstream name (wan_ip). - Confirm your exception handling already used the
*Exceptionsuffix (EeroAuthenticationException,EeroAPIException, etc.) β this SDK has never shipped*Error-suffixed exception classes, so no rename is needed here.
What broke: Credential storage was simplified β AuthCredentials no longer stores redundant
legacy fields. If you have an older cookies.json on disk, the storage backends
(KeyringStorage.load / FileStorage.load, via the module-level _parse_stored_record)
transparently upgrade any legacy user_token field to session_id when the record is next
loaded.
Note: This is a backward-compatible read-side migration, not a forced re-authentication. Existing stored sessions keep working; you do not need to call
login()/verify()again purely because of this version bump.
Checklist:
- If you serialize/inspect
cookies.jsonyourself (rather than only reading it throughFileStorage/KeyringStorage), stop looking for auser_tokenkey β readsession_idinstead. - No code changes required if you only ever go through
AuthAPI/EeroClient/CredentialStorageβ the migration is internal to the storage backends'load().
What broke: preferred_network_id is no longer part of credential storage.
AuthCredentials dropped the field, AuthAPI dropped the property/setter and
save_preferred_network(), and cookies.json now contains only session_id, refresh_token,
and session_expiry (as of v8.0.0 the record is {"session_id": β¦, "schema_version": 2} only β
see The credential record). Preferred-network selection moved to in-memory state on EeroAPI /
EeroClient β nothing about it is persisted by the SDK anymore.
| Before (v3.x) | After (v4.0.0+) |
|---|---|
auth_api.preferred_network_id (persisted to cookies.json) |
client.preferred_network_id (in-memory only, per EeroClient instance) |
await auth_api.save_preferred_network(id) |
(method removed β no persistence layer in the SDK) |
# Before: relied on the SDK to remember your network choice across runs
async with EeroClient() as client:
print(client.preferred_network_id) # loaded from cookies.json
# After: the SDK only remembers it for the lifetime of this EeroClient instance;
# your application owns persistence if it wants any
async with EeroClient() as client:
client.set_preferred_network("123456")
... # persist "123456" yourself if you need it on the next runChecklist:
- Stop expecting
preferred_network_idto survive process restarts β it won't. - If your application needs a durable "last used network" setting, store it in your own
config file (this is exactly what
eeroctldoes β the CLI ownsconfig.json, the SDK does not). - Remove any code calling
save_preferred_network()onAuthAPIβ it's gone.
What broke: EeroAPI.set_preferred_network() and EeroAPI.preferred_network_id β deprecated
since v4.7.0 β were removed. They never actually wired through to any domain API call, so
removing them changes no runtime behavior other than making the AttributeError explicit
instead of the calls being silently ineffective.
Note: This ONLY affects
EeroAPI.EeroClient.set_preferred_network()andEeroClient.preferred_network_idare unaffected and remain the supported way to set a default network for a client session.
| Before (v4.x, broken no-op on EeroAPI) | After (v5.0.0+) |
|---|---|
api.set_preferred_network("123456") |
EeroClient.set_preferred_network("123456") or pass network_id="123456" to every EeroAPI/domain method call |
api.preferred_network_id |
(removed β read it back from EeroClient, or track it yourself) |
# Before (v4.x) β looked like it worked, did nothing
api = EeroAPI()
api.set_preferred_network("123456")
await api.networks.get_networks() # network_id was never actually consulted here
# After (v5.0.0+) β explicit network_id on every call
api = EeroAPI()
await api.networks.get_network("123456")
# Or use EeroClient, which resolves network_id for you
async with EeroClient() as client:
client.set_preferred_network("123456")
await client.get_network() # resolves to "123456" automaticallyChecklist:
- Grep for
.set_preferred_network(and.preferred_network_idcalls on anyEeroAPIinstance (notEeroClient) β these now raiseAttributeError. - Switch to
EeroClientif you want automatic network resolution, or passnetwork_id=explicitly on every domain API call if you stay on the low-levelEeroAPI.
What broke: Two independent changes landed together.
-
InsightsAPI.get_insights/EeroClient.get_insightsnow require keyword-only parameters. The Eero Cloud API always requiredstart,end,insight_type, andcadenceas query parameters β calling without them previously returned an unusable400. The SDK now enforces this at the Python level via keyword-only arguments, so a caller who was already only passingnetwork_id(the only way the old signature worked) sees no regression in practice β that call was already 100% broken. -
ActivityAPIis deprecated. Every/networks/{id}/activity*endpoint has been removed upstream and now returns404. AllActivityAPImethods, and the correspondingEeroClient.get_activity*wrappers, are retained for one release cycle with aDeprecationWarningbefore removal.
# Before (v5.x) β only worked because it was already broken
await client.get_insights(network_id) # HTTP 400 either way
# After (v6.0.0+) β required keyword arguments
await client.get_insights(
network_id,
start="2026-07-01T00:00:00Z",
end="2026-07-21T00:00:00Z",
insight_type="blocked",
cadence="daily", # optional, defaults to "daily"
)InsightsAPI.get_insights required parameters (verified in src/eero/api/insights.py):
| Parameter | Required | Notes |
|---|---|---|
network_id |
yes (positional) |
EeroClient.get_insights differs here: network_id defaults to None and is resolved like other EeroClient methods |
start |
yes (keyword-only) | ISO 8601 timestamp |
end |
yes (keyword-only) | ISO 8601 timestamp |
insight_type |
yes (keyword-only) | e.g. "adblock", "blocked", "inspected"
|
cadence |
no (keyword-only) | "hourly" |
Checklist:
- Add
start=,end=, andinsight_type=to everyget_insightscall β they are keyword-only and mandatory; omitting any of them still raises via the upstream400. - Replace any
ActivityAPI/client.get_activity*usage withInsightsAPI.get_insights(category / adblock / inspected breakdowns) orDataUsageAPI.get_data_usage(bandwidth per client or node) βActivityAPIwas removed outright in v8.0.0, see Migration#v7x--v800.
Read this one even if you think you don't use DNS.
What broke: the DNS write methods did nothing at all before this release, and now they work.
DnsAPI was sending a custom_dns field (and dns_caching) that does not exist in the Eero
Cloud API. The backend accepts unrecognised keys with HTTP 200 and silently discards them, so
these four methods returned a success response while changing nothing on the network β in every
release from v4.1.3 through v6.2.0:
set_custom_dnsclear_custom_dns-
set_dns_mode(every mode) set_dns_caching
The practical consequence: if your code calls any of them, it has been a no-op. After upgrading it will alter real network configuration. Review those call sites before you upgrade, particularly anything that runs unattended.
Everything in the "Before" column describes what the SDK attempted. Because the field it wrote did not exist, none of it reached your network β the calls were no-ops. Your stored configuration was never altered by this SDK.
| Before (v6.x) β intended, but a no-op | After (v7.0.0) |
|---|---|
set_custom_dns([a, b, c]) silently dropped everything past the second entry before sending |
Raises EeroValidationException; the cap is now 2 per address family
|
set_dns_mode("auto") built an empty server list, which would have erased your servers had the write worked |
Switches the mode selector to automatic and retains the stored servers |
An unrecognised mode returned a locally fabricated {"meta": {"code": 400}}
|
Raises EeroValidationException
|
set_dns_mode("cloudflare"/"google"/"opendns") resolved a hardcoded server list |
Removed β read the API's own catalogue instead (below) |
Malformed IP literals, addresses of the wrong family, and zone-scoped addresses are now also rejected locally, before any request.
set_dns_mode no longer accepts "cloudflare", "google" or "opendns". Those resolved a
server list hardcoded in the SDK, duplicating data the API already serves β and the copy was
incomplete, omitting Quad9. Read the authoritative list instead:
data = (await client.get_dns_settings())["data"]
chosen = next(p for p in data["dns"]["default_test_servers"] if p["name"] == "Cloudflare")
await client.set_custom_dns(chosen["ipv4"] + chosen["ipv6"])Each entry has name, ipv4 and ipv6. This is the SDK's raw-JSON contract applied
consistently: values come from the API or from you, never invented in between.
IPv6 DNS servers are now supported. Each address family has an independent mode selector and server list, matching the four slots in the eero app:
# All four slots β the list is split by family.
await client.set_custom_dns([
"1.1.1.1", "1.0.0.1",
"2606:4700:4700::1111", "2606:4700:4700::1001",
])
# Or one family at a time, leaving the other alone.
await client.set_custom_dns_ipv4(["8.8.8.8", "8.8.4.4"])
await client.set_custom_dns_ipv6(["2001:4860:4860::8888"])
await client.clear_custom_dns(family="ipv6")
# Re-enable the stored servers without resupplying them.
await client.set_dns_mode("custom")set_dns_mode("custom") with no custom_servers used to be a usage error. It now re-enables
whatever the network already stores β the inverse of clear_custom_dns, and the same thing
the app's radio does.
clear_custom_dns, set_custom_dns_ipv4, set_custom_dns_ipv6 and set_ipv6_dns are now on
EeroClient, so client._api.dns is no longer needed for them.
β οΈ set_ipv6_dns()does not set IPv6 DNS servers β it togglesipv6_upstream, the IPv6 connectivity setting, and always has. Useset_custom_dns_ipv6()instead. See #125.
get_dns_settings never changed, but if you were reading the fields the old docstring named,
they do not exist. The real paths:
data = (await client.get_dns_settings())["data"]
data["dns"]["mode"] # "custom" | "automatic"
data["dns"]["custom"]["ips"] # IPv4 servers
data["dns"]["caching"] # bool
data["ipv6"]["name_servers"]["mode"] # "custom" | "automatic"
data["ipv6"]["name_servers"]["custom"] # IPv6 servers, fully expandedNote the asymmetry (custom.ips vs custom), and that IPv6 addresses read back expanded β
2606:4700:4700::1111 becomes 2606:4700:4700:0:0:0:0:1111. Compare with
ipaddress.IPv6Address, not string equality.
- Audit every call to
set_custom_dns,set_dns_mode,clear_custom_dnsandset_dns_cachingβ they now take effect. - Wrap DNS writes in
except EeroValidationExceptionif you pass user-supplied input. - Replace any call passing more than 2 servers for one family.
- Replace
set_dns_mode("cloudflare"/"google"/"opendns")with addresses read fromdns.default_test_servers. - Replace reads of
custom_dns/dns_caching/dns_serverswith the real paths above. - Replace
set_ipv6_dnswithset_custom_dns_ipv6if you wanted IPv6 DNS servers. - Drop any
client._api.dnsreach-through forclear_custom_dns/set_ipv6_dns.
What broke: Five groups of changes landed together. First, ten symbols that either never
worked against the current API, or that the API stopped serving outright, are gone (this
section). Second, the session transport, refresh flow, credential record, retry policy, and
error model (new exception classes, envelope / error_code) changed β see
Session transport and authentication and the
subsections that follow it, in particular Error classes and attributes. Third, get_data_usage and get_ouicheck now take the
parameters the API actually requires β see get_data_usage
and get_ouicheck. Fourth, every domain method resolves its URL through the
links the API publishes, and a further set of writes were re-pointed to the request forms the
API declares β several of them replacing methods that could never have worked; see
Resource links and parent= and
Writes now use the forms the API declares. Fifth,
fourteen new domain modules were added β additive, but the section
New families and what they replace notes where they take
over from a removed method.
There is no deprecation window for this release β every removed call now raises
AttributeError (or, for a removed keyword such as configure_security(thread=...) or
set_guest_network(password=...), TypeError) instead of the previous no-op or 404.
| Removed | If you called it | Do this instead |
|---|---|---|
DevicesAPI.set_device_priority / EeroClient.set_device_priority
|
Remove the call β it never changed anything server-side | Use SQM: client.set_sqm(True) (a single on/off toggle β the API declares no bandwidth fields) |
ActivityAPI (module) / client.get_activity* (all five methods) |
Remove the call β it always raised EeroAPIException (404) |
Use client.get_insights(start=..., end=..., insight_type=...) for category/adblock/inspected data, or client.get_data_usage(...) for bandwidth per client or node |
DnsAPI.set_ipv6_dns / EeroClient.set_ipv6_dns
|
Replace with the method matching what you actually wanted | For the IPv6 connectivity toggle: client.set_ipv6(enabled). For IPv6 DNS servers: client.set_custom_dns_ipv6(servers)
|
InsightsAPI.run_insights |
Remove the call β the API has no such operation | None |
OUICheckAPI.run_ouicheck |
Remove the call β the API has no such operation | None |
SecurityAPI.set_thread, configure_security(thread=...)
|
Remove the call/argument β the API does not accept a thread field on the settings write |
client.set_thread_enabled(enabled) β same facade name, now a JSON {"enabled": bool} PUT to networks/{id}/thread via ThreadAPI (unverified write); also update_thread(...) and regenerate_thread_credentials()
|
SettingsAPI (module) / EeroClient.get_settings
|
Replace with a network read |
client.get_network() β the same fields live on the network envelope |
PasswordAPI (module) / EeroClient.get_password
|
Replace with a network read |
client.get_network() β the network envelope carries the same fields |
BurstReportersAPI.get_burst_reporters / EeroClient.get_burst_reporters
|
Remove the call β the endpoint returns 404 | None; the resource is POST-only β client.create_burst_reporter() (added in v8.4.0; earlier 8.x releases had only the domain method BurstReportersAPI.create_burst_reporter) |
# Before (v7.x) β silent no-op
await client.set_device_priority(device_id, prioritized=True)
# After (v8.0.0+) β use SQM (read first; this is a settings-class write)
sqm = (await client.get_sqm_settings())["data"].get("sqm")
if sqm is not True:
await client.set_sqm(True)# Before (v7.x) β always raised EeroAPIException (404)
await client.get_activity_history(period="week")
# After (v8.0.0+)
await client.get_insights(
start="2026-07-01T00:00:00Z",
end="2026-07-21T00:00:00Z",
insight_type="blocked",
cadence="daily",
)# Before (v7.x) β toggled ipv6_upstream, not DNS servers
await client.set_ipv6_dns(True)
# After (v8.0.0+) β pick the one you actually meant
await client.set_ipv6(True) # IPv6 connectivity toggle
await client.set_custom_dns_ipv6(["2001:4860:4860::8888"]) # IPv6 DNS serversChecklist:
- Grep for
set_device_priority(β remove it, switch to SQM if bandwidth control was the goal. - Grep for
get_activity,get_activity_clients,get_activity_for_device,get_activity_history,get_activity_categories, andclient._api.activityβ replace withget_insightsorget_data_usage. - Grep for
set_ipv6_dns(andclient._api.dns.set_ipv6_dnsβ split intoset_ipv6and/orset_custom_dns_ipv6depending on intent. - Grep for
run_insights(andrun_ouicheck(β remove; no replacement exists. - Grep for
set_thread(andconfigure_security(calls passingthread=β remove the argument.client.set_thread_enabled(still exists but is now a different, unverified write to the Thread resource; readget_thread()first and skip when unchanged. - Grep for
get_settings(andclient._api.settingsβ replace withget_network(). - Grep for
get_password(andclient._api.passwordβ replace withget_network(). - Grep for
get_burst_reporters(andclient._api.burst_reporters.get_burst_reportersβ remove;create_burst_reporteris unaffected (callclient.create_burst_reporter()from v8.4.0).
Every domain method now resolves its URL through the links the API publishes rather than a hardcoded path. Two things follow for callers:
-
Every resource argument is polymorphic. Wherever a method took a bare
network_id/eero_id/device_id/profile_id, it now also accepts the resource's API path (theurlvalue from its envelope, e.g./2.2/networks/<network-id>) or that path joined onto the API host. Existing bare-ID calls keep working unchanged. A URL on any other host or scheme raisesEeroValidationExceptionbefore a request is made. -
Every domain method gained a keyword-only
parent=. Pass the envelope you already hold and the method uses the link the API published on it (resources.settings,resources.led_action, the resource's ownurl, β¦) instead of a template.EeroClientpasses its cached network / eero / device envelopes automatically, so facade callers get this without changing anything.
Because parent= is keyword-only and optional, no existing positional call breaks. The one
behavioural difference you may notice: through EeroClient, a network-scoped call made while a
fresh get_network() result is cached goes to the link the API published for that network,
which can be on a different version than before (routing is served on 2.3, for example).
Two EeroClient reads changed shape to match: get_devices() gained keyword-only
thread= / proxied_node= filters (sent as query parameters; a filtered call bypasses the
cache), and delete_reservation() gained keyword-only delete_forwards=.
The helpers are exported from the package root β resolve_link, self_url, resource_url,
sub_resource_url, join_api_path β and eero.const gained api_endpoint(version),
API_VERSION_DEFAULT, API_VERSION_DEVICE_WRITES, API_VERSION_MULTISTATICIP, and
API_VERSION_SECONDARY_WAN (API_VERSION, API_ENDPOINT, DEVICE_UPDATE_ENDPOINT remain as
aliases). Full description: Network Targeting.
A set of existing writes were re-pointed to the path, encoding, and field names the API
declares for the operation. Several of the old writes could not have applied β the API accepts
unrecognised JSON keys with a 200 and discards them β so "it returned 200 before" is not
evidence that your call site worked. Every re-pointed write not marked "verified" below is
unverified against a live network and logs one WARNING before the request; the live-verified
ones (set_led, set_led_brightness, set_guest_network, set_guest_password,
clear_guest_password, reboot_eero, run_speed_test, unblock_device) do not. See
Writes and safety for the discipline this implies.
| Write | Before (v7.x) | After (v8.0.0) |
|---|---|---|
set_led(eero_id, enabled) |
JSON {"led_on": bool} PUT to the eero's own URL β verified to change nothing. Any caller who "successfully" set the LED through the SDK never did |
Form-encoded `led_on=true |
set_led_brightness(eero_id, brightness) |
JSON PUT to the eero's own URL | Form-encoded led_brightness=<int> PUT to the led_action link. Verified live on 2026-09-20 (brightness changed and read back, no reboot) |
set_location(eero_id, location) |
(new on EeroClient) |
Form-encoded location= PUT to the eero's own URL. Unverified |
set_network_name(name) |
JSON {"name": ...} PUT to settings
|
Form-encoded name= PUT to the network's settings link. Disconnects clients while it takes effect; the form shape is unverified |
set_network_password(password) / clear_network_password()
|
(new) | Form-encoded password= PUT / DELETE on the network's password link. Disconnects clients; unverified |
set_guest_network(enabled, name=, password=) |
One JSON PUT carrying the password |
set_guest_network(*, enabled, name=None) β form-encoded PUT to the guestnetwork link with enabled and, when given, name. password= is gone β use set_guest_password(password) / clear_guest_password() (form PUT / DELETE on the guest network's password link). All three verified live on 2026-09-20 |
block_device(device_id, blocked) |
One method toggling both directions |
block_device(mac) sends a form-encoded mac to POST networks/{id}/blacklist; unblock_device(mac) is a separate DELETE networks/{id}/blacklist/{mac}. The form encoding is unverified (a JSON body was verified in the past); the DELETE is verified |
set_sqm_enabled / configure_sqm / set_sqm_bandwidth / set_sqm_auto
|
JSON bodies with bandwidth / mode fields the API never declared |
Removed. set_sqm(enabled) β PUT with no body to the settings link, value in the sqm query parameter. Settings-class: may reboot the mesh |
reboot_network() (domain API only until v8.4.0; client.reboot_network() since), reboot_eero(), run_speed_test(), apply_update()
|
A different body encoding |
POST with the two-character JSON-string body "" to the published reboot / speedtest / updates link. reboot_eero and run_speed_test are verified live on 2026-09-20 (only the targeted node rebooted; the speed test result appeared in get_speed_tests about a minute later). apply_update is new on EeroClient and reboots every node |
set_nightlight(...) |
JSON PUT to the eero's own URL with brightness, schedule_enabled, schedule_on, schedule_off, ambient_light_enabled
|
JSON PUT to the nightlight sub-resource (data.nightlight.url) with only enabled, brightness_percentage, schedule β the fields the API declares. set_nightlight_schedule(schedule) forwards the schedule object unchanged; set_nightlight_brightness(brightness_percentage). Raises EeroFeatureUnavailableException on an eero without a nightlight |
run_diagnostics() |
Empty POST | JSON POST with whichever of device= / symptom= you supply (an empty object otherwise). Additive |
| Thread writes |
SecurityAPI.set_thread wrote a thread field the settings endpoint ignores |
set_thread_enabled(enabled) (JSON {"enabled": bool}), update_thread(*, thread_enable=, enable_credential_syncing=), regenerate_thread_credentials() ("" POST) β all to the literal networks/{id}/thread path |
get_backup_network / get_backup_status / set_backup_network / configure_backup_network
|
Fields (phone_number) the API never declared |
Removed. get_backup_internet(), set_backup_internet(enabled) (JSON {"backup_internet_enabled": bool}), get_cellular_backup_usage(), get_cellular_backup_events()
|
get_profile_schedule / set_profile_schedule(time_blocks)
|
Wrote a schedule array onto the profile β not a profile field |
Removed. Schedules are sub-resources: get_schedules(profile_id), create_schedule(profile_id, *, name, days, start, end, enabled=True), update_schedule(schedule, *, ...), delete_schedule(schedule) (both take the pause's own path/URL or envelope), clear_profile_schedule(profile_id) (one DELETE per pause, returns a list of responses). enable_bedtime / set_weekday_bedtime / set_weekend_bedtime now create one pause each |
update_profile_content_filter / update_profile_block_list / get_blocked_applications / set_blocked_applications
|
Wrote fields a profile does not have β silent no-ops | Removed. Use the DNS-policies family (below) |
DevicesAPI.*(network_id, device_id, ...) |
Parameter named device_id
|
Parameter named mac; positional calls unaffected. EeroClient wrappers keep device_id
|
set_device_nickname / pause_device
|
2.3 JSON PUT (verified) | Unchanged β still the verified 2.3 write. New alongside it: update_device_via_link(device_id, *, nickname=, paused=, profile=) β a JSON PUT of those fields to the device's own URL on the default version, unverified; prefer the two verified methods for nickname/pause |
update_reservation(reservation_id, data) / update_forward(forward_id, data)
|
Built the URL from network_id + ID |
Domain signatures are now update_reservation(reservation, data, *, network=None) / update_forward(forward, data, *, network=None) β reservation / forward may be a bare ID (then network= is required), the resource's path/URL, or its envelope. EeroClient wrappers keep (id, data, network_id=None)
|
Added on EeroClient in the same change, all unverified writes unless marked: set_device_type
(verified 2026-09-20: the value persists and reads back), get_device_labels (read),
set_device_labels (labels go as query parameters on the PUT; verified 2026-09-20 to return 200
without applying the value, so treat it as a no-op until the API changes),
get_connections (read), get_speed_tests(*, limit=, start_time=, end_time=) (read),
get_guest_network (read), get_devices_insights / get_device_insights /
get_profiles_insights / get_profile_insights / get_profile_devices_insights (verified
reads), create_profile(name, *, devices=None, paused=None) (additive keywords).
# Before (v7.x)
await client.set_guest_network(enabled=True, name="Guest", password="<new-password>")
await client.block_device("<mac>", blocked=True)
await client.block_device("<mac>", blocked=False)
await client.set_profile_schedule("<profile-id>", time_blocks=[...])
await client.set_nightlight("<eero-id>", brightness=30, schedule_on="22:00", schedule_off="06:00")
# After (v8.0.0+)
await client.set_guest_network(enabled=True, name="Guest")
await client.set_guest_password("<new-password>")
await client.block_device("<mac>")
await client.unblock_device("<mac>")
await client.create_schedule("<profile-id>", name="Bedtime", days=["monday"], start="22:00", end="06:00")
await client.set_nightlight("<eero-id>", brightness_percentage=30, schedule={...})Fourteen domain modules were added (each with EeroClient wrappers): entitlements, events,
permissions, notifications, dns_policies, members, account, dhcp, wpa3,
power_saving, ddns, backup_access_points, subnets, wan; plus node/port actions, LED
cycle, nightlight override and eero support reads on EerosAPI, and MLO / fast transition /
Passpoint / proxied nodes on SecurityAPI. They are additive except where noted in the table
above. The one you are most likely to need during migration is DNS policies, which replaces the
removed profile content-filter methods:
# Before (v7.x) β never persisted
await client._api.profiles.update_profile_block_list("<network-id>", "<profile-id>", ["example.com"])
await client.set_blocked_applications("<profile-id>", ["<app-id>"])
# After (v8.0.0+) β the DNS-policies resource family (premium feature)
await client.block_domain_for_profiles("example.com", profiles=["<profile-id>"])
await client.block_domain_for_profiles("example.com", profiles=["<profile-id>"], is_delete=True) # remove
await client.set_profile_blocked_applications("<profile-id>", ["<app-id>"])
apps = await client.get_dns_policy_applications("<profile-id>")Every method in every new family is listed with verb, path, and verified/unverified status in the API Reference, with usage in Python API.
Checklist (links and writes):
- Grep for
set_sqm_enabled(,configure_sqm(,set_sqm_bandwidth(,set_sqm_auto(β replace withset_sqm(enabled)behind a read-compare-skip. - Grep for
get_backup_network(,get_backup_status(,set_backup_network(,configure_backup_network(β replace with the*_backup_internet/cellular_backupmethods; dropphone_number. - Grep for
set_guest_network(calls passingpassword=β split intoset_guest_network+set_guest_password. - Grep for
block_device(calls passingblocked=or a second positional β split intoblock_device(mac)/unblock_device(mac). - Grep for
set_profile_schedule(,get_profile_schedule(,time_blocksβ move to the schedules sub-resource methods. - Grep for
update_profile_content_filter(,update_profile_block_list(,get_blocked_applications(,set_blocked_applications(β move to the DNS-policies family. - Grep for
set_nightlight(/set_nightlight_schedule(β switch tobrightness_percentage=/schedule=; dropschedule_enabled,schedule_on,schedule_off,ambient_light_enabled,on_time,off_time. - Grep for
set_led(/set_led_brightness(β audit: the old write did nothing, so any logic that assumed the LED state was changed has never been exercised. - Grep for
device_id=passed by keyword to aDevicesAPImethod (notEeroClient) β rename tomac=. - Grep for
update_reservation(/update_forward(on the domain APIs β the network is now keyword-onlynetwork=and only needed for a bare ID. - Any automation issuing a settings-class write (
set_sqm,set_dhcp,set_connection_mode,set_nat_port_randomization,set_mlo_mode,set_wpa3_per_band,set_fast_transition,set_power_saving,set_subnets_config,set_multistaticip, secondary WAN, the DNS writes) must read, compare, and skip β a write may reboot the whole mesh.
What changes for a caller: usually nothing. login(), verify(), logout(),
set_session_token(), clear_session_token(), and is_authenticated keep their signatures,
and a stored session from 7.x keeps working after the credential record is migrated (below).
What changed is underneath:
| Before (v7.x) | After (v8.0.0) |
|---|---|
Session token stored in the shared aiohttp cookie jar and sent as the s= cookie |
Sent as the X-User-Token header on every request to the API host over https, and never to any other host or scheme. The legacy s= cookie is still sent per request (not via the jar) while send_legacy_cookie=True (default) |
login / verify / logout sent JSON bodies |
They send application/x-www-form-urlencoded bodies (login=, code=, and a field named Cookie carrying s=<token> respectively). resend sends {}; refresh sends the JSON string ""
|
User-Agent and Content-Type: application/json on every request (DEFAULT_HEADERS) |
Accept: application/json, User-Agent (DEFAULT_USER_AGENT), and X-Accept-Language (constructor option accept_language, default en-US) on every request; Content-Type set per request by the body encoding |
Redirects refused (allow_redirects=False) |
Still refused, and now allow_redirects=True raises EeroValidationException β it cannot be re-enabled |
Two things that will break if you relied on them:
-
If you passed your own
aiohttp.ClientSessionand read the session token back out of its cookie jar, that jar is now empty β the SDK never writes the credential into it. Useclient._api.auth.get_auth_token()if you need the token value. -
If you called
BaseAPI.get/post/β¦ directly with aheaders=dict containingX-User-Token,Cookie, orAuthorization, the call now raisesEeroValidationException. Drop those headers β the transport attaches the credential itself.
AuthCredentials lost is_session_expired(), has_valid_session(), and clear_session()
along with the refresh_token and session_expiry fields. There is no client-side expiry any
more: is_authenticated means a session token is present, nothing else. Any "days
remaining" logic built on session_expiry has nothing to read and must go β the server is the
only authority on whether a token is still valid, and it says so with a 401.
The persisted record (keyring entry or cookie_file) is now:
{"session_id": "β¦", "schema_version": 2}A record written by 7.x (or earlier) β one with no schema_version, possibly carrying
refresh_token, session_expiry, or the pre-v3.0.0 user_token key β is migrated in place
the first time it is loaded: only the token is kept, the other fields are dropped, and the
record is re-saved in the shape above. This happens once, is idempotent, and logs no values.
No re-authentication is needed.
If you serialise or parse the credential file yourself, stop reading
session_expiryandrefresh_token. They are no longer written, and any copy left in an old file is removed on first load. Readsession_idonly. If you write the file yourself, write the shape above includingschema_version: 2β a record without the marker is treated as legacy and rewritten.
In 7.x refresh_session() looked for a refresh_token that the API never issues, so a
server-driven refresh signal could not succeed. In v8.0.0 refresh is
POST /2.2/login/refresh authenticated by the session token itself, with the JSON body "":
| Behaviour | v8.0.0 |
|---|---|
| Credential used | The current session token β there is no refresh token |
| Endpoint |
/2.2/login/refresh only; the account/refresh fallback is gone |
| Concurrency | Coalesced: one refresh in flight, concurrent callers wait for its result, then their original request is replayed once |
| Return value |
True on HTTP 200, False on any API error from the refresh endpoint (401, 429, 5xx, β¦); a network or timeout failure still raises |
| Stored credentials | Cleared when the refresh endpoint answers 401 with any string outside the VERIFICATION / SESSION_REFRESH groups β including error.session.expired / .invalid / .revoked, any other recognised group, and an unrecognised/absent error_code. Kept only for a VERIFICATION string (e.g. error.verification.required) or error.session.refresh
|
| Token in the refresh response | Deliberately ignored β the current token stays in use |
For a daemon, exporter, or scheduled job this is the practical change: the process can now
hold one token indefinitely. When the server asks for a refresh (a 401 carrying
error.session.refresh), the SDK refreshes and replays the request transparently; the only
EeroAuthenticationException you will see is a terminal one (session expired / invalid /
revoked), after which the stored credential is already cleared and you need to re-seed a token
or run the OTP flow. Catch it, re-authenticate, continue β do not add your own periodic
refresh_session() calls.
The SDK now classifies every error response against the API's closed catalogue of
meta.error strings (eero.errors, matched case-insensitively): a 401 always wins; otherwise
a string in one of the status-independent groups (premium / feature-unavailable /
client-blocked / rate-limit) picks the class regardless of status; otherwise the HTTP status
picks the class, and an unrecognised or free-text string never changes it. Every EeroException carries envelope (the raw, unmodified JSON
response body, or None) and error_code (meta.error, or None). The exception
message no longer contains the response body β it is the status plus the recognised
catalogue string, or the fixed label unrecognised error string β and MAX_ERROR_BODY_CHARS
(with its ... [truncated, N chars total] suffix) is gone.
Class changes (all still subclasses of EeroException, so broad handlers keep working):
| Response | Before (v7.x) | After (v8.0.0) |
|---|---|---|
| Any 404 | EeroAPIException(status_code=404) |
EeroNotFoundException β a subclass of EeroAPIException, so except EeroAPIException still catches it |
403 with error.access.denied
|
EeroAPIException(status_code=403) |
EeroAccessDeniedException (subclass of EeroAPIException); is_auth_error() is False, credentials kept |
400 with a form-error string (error.form.errors, error.form.email.malformed, β¦) |
EeroAPIException(status_code=400) |
EeroValidationException with field == "request" and the envelope attached. Not a subclass of EeroAPIException β it derives from EeroException only, because it is also the SDK's client-side validation error. Handlers that catch only EeroAPIException will not see it.
|
Premium strings (error.premium.user_not_subscribed, error.partner.unavailable), any status |
EeroAPIException |
EeroPremiumRequiredException (now a subclass of EeroAPIException) |
Feature-unavailable strings (error.eero.offline, error.network.unavailable, β¦), any status |
EeroAPIException |
EeroFeatureUnavailableException (now a subclass of EeroAPIException) |
error.app.version.blocked, any status |
EeroAPIException |
EeroClientBlockedException (new; subclass of EeroAPIException) |
error.rate.limit on a non-429 status |
EeroAPIException |
EeroRateLimitException |
| Any 401 | EeroAuthenticationException |
Unchanged β always EeroAuthenticationException. Stored credentials are cleared for any 401 from the refresh endpoint except one carrying a VERIFICATION or error.session.refresh string β those never clear them |
| Everything else (including every recognised domain string) | EeroAPIException |
Unchanged β EeroAPIException with error_code set |
EeroNotFoundException, EeroPremiumRequiredException, and EeroFeatureUnavailableException
were previously defined but never raised; they are now raised by the transport and importable
from the package root. Their legacy constructors (EeroNotFoundException(resource_type, resource_id), etc.) still work; each also has a from_response(...) classmethod. is_auth_error()
is True only for EeroAuthenticationException.
Matching on the message no longer works. If you followed the eeroctl-style pattern of
matching a substring of str(exc), switch to error_code:
# Before (v7.x) β the body was pasted (truncated) into the message
except EeroAPIException as err:
if "error.session.expired" in str(err): ...
if err.status_code == 404: ...
# After (v8.0.0+) β the class and error_code carry the meaning
except EeroNotFoundException:
...
except EeroAuthenticationException as err:
if err.error_code == "error.session.expired": ...
except EeroValidationException as err: # API 400 form errors land here now
print(err.error_code, err.envelope)
except EeroAPIException as err:
if err.error_code == "error.assignment.ip.unavailable": ...
print(err.status_code, err.envelope) # the API's own envelope, unmodifiedfrom eero import ErrorGroup, classify_error_code gives you the catalogue group of any
error_code if you want to branch by meaning rather than by exact string. The full group
list is in Error Handling.
Writes (POST/PUT/DELETE/PATCH) are never retried by the SDK, for any reason. An
opt-in bounded retry exists for GETs that fail with a transport error or a 5xx:
EeroClient(
send_legacy_cookie=True, # default; False sends only the X-User-Token header
accept_language="en-US", # default; X-Accept-Language header, printable ASCII only
get_retries=0, # default; additional GET attempts on transport error / 5xx
)All three are keyword-only and also accepted by EeroAPI and AuthAPI. 4xx and 429 are
never retried whatever get_retries is set to. The 401 refresh-and-replay is not a retry and
is not affected by this option.
The data-usage endpoints accept query parameters only and reject a request body. The old
payload dict and free-form resource argument are gone; start, end, and cadence
("daily" or "hourly") are required keyword-only arguments, timezone is optional:
# Before (v7.x)
await client.get_data_usage(payload={"resource": "network"})
# After (v8.0.0+)
await client.get_data_usage(
start="2026-07-01T00:00:00Z",
end="2026-07-21T00:00:00Z",
cadence="daily",
timezone="UTC", # optional IANA name
)Each former resource value is now an explicit method, on EeroClient (trailing
network_id=None, no auto-discovery) and on DataUsageAPI (network_id first), with the same
keyword-only window arguments:
Old resource intent |
EeroClient |
DataUsageAPI |
|---|---|---|
| breakdown | get_data_usage_breakdown(network_id=None, *, start, end, cadence=None, timezone=None) |
get_breakdown(network_id, *, β¦) |
| per-device list | get_devices_data_usage(network_id=None, *, start, end, cadence=None, timezone=None, profile_id=None) |
get_devices_usage(network_id, *, β¦) |
| one device | get_device_data_usage(device_mac, network_id=None, *, start, end, cadence, timezone=None) |
get_device_usage(network_id, device_mac, *, β¦) |
| eeros summary | get_eeros_data_usage_summary(network_id=None, *, start, end, cadence, timezone=None) |
get_eeros_summary(network_id, *, β¦) |
| one eero | get_eero_data_usage(eero_id, network_id=None, *, start, end, cadence, timezone=None) |
get_eero_usage(network_id, eero_id, *, β¦) |
| one profile | get_profile_data_usage(profile_id, network_id=None, *, start, end, cadence, timezone=None) |
get_profile_usage(network_id, profile_id, *, β¦) |
| unprofiled devices | get_unprofiled_devices_data_usage(network_id=None, *, start, end, cadence=None, timezone=None) |
get_unprofiled_devices(network_id, *, β¦) |
| unprofiled summary | get_unprofiled_data_usage_summary(network_id=None, *, start, end, cadence, timezone=None) |
get_unprofiled_summary(network_id, *, β¦) |
| report settings (read) | get_data_usage_report_settings(network_id=None) |
get_report_settings(network_id) |
| report settings (write) |
set_data_usage_report_settings(*, cadence, notification_day, network_id=None) β invalidates that network's cache entry |
set_report_settings(network_id, *, cadence, notification_day) |
The report-settings write is unverified: read first, write only on a difference, never retry.
An invalid cadence raises EeroValidationException before any request.
The API returns 404 for GET /networks/{id}/ouicheck unless both serial and version
query parameters are present, so the old one-argument call never returned data. Both are now
required keyword-only arguments, taken from an eero envelope:
# Before (v7.x) β always EeroAPIException (404)
await client.get_ouicheck()
# After (v8.0.0+) β both values come from the eero's own envelope (get_eeros / get_eero)
await client.get_ouicheck(serial="<eero-serial>", version="<eero-version>")Removed from eero.const
|
Use instead |
|---|---|
DEFAULT_HEADERS |
DEFAULT_USER_AGENT for the UA string; headers are built per request by eero.api.base.build_request_headers
|
REFRESH_ENDPOINTS, ACCOUNT_REFRESH_ENDPOINT
|
LOGIN_REFRESH_ENDPOINT β the only refresh path |
SESSION_TOKEN_KEY, REFRESH_TOKEN_KEY
|
Nothing β the record shape is {"session_id", "schema_version"}; CREDENTIAL_SCHEMA_VERSION is the only storage constant |
MAX_ERROR_BODY_CHARS |
Nothing β error bodies are no longer embedded; read err.envelope
|
New: API_HOST, API_VERSION, DEFAULT_USER_AGENT, DEFAULT_ACCEPT_LANGUAGE,
GET_RETRY_DELAY_SECONDS, CREDENTIAL_SCHEMA_VERSION, LOGIN_RESEND_ENDPOINT,
LOGOUT_COOKIE_FIELD_NAME, SESSION_COOKIE_PREFIX, api_endpoint(version),
API_VERSION_DEFAULT, API_VERSION_DEVICE_WRITES, API_VERSION_MULTISTATICIP,
API_VERSION_SECONDARY_WAN. eero.api.base additionally exports RequestEncoding and
build_request_headers; eero.api.links (re-exported from eero) adds resolve_link,
self_url, resource_url, sub_resource_url, join_api_path.
Checklist (transport, auth, errors, parameters):
- Grep for
session_expiry,refresh_token,is_session_expired,has_valid_session, andclear_session(β remove; there is no client-side expiry and no refresh token. - If anything outside the SDK reads or writes the credential file, read
session_idonly and write{"session_id": ..., "schema_version": 2}. - Grep for
str(err)/err.message/in str(exc)parsing of API error bodies β switch toerr.error_code/err.envelopeor the new exception classes. - Grep for
except EeroAPIExceptionβ addexcept EeroValidationExceptionwherever an API 400 form error must be handled; checkstatus_code == 404/== 403branches, which can becomeexcept EeroNotFoundException/except EeroAccessDeniedException. - Grep for
from eero.exceptions import EeroNotFoundException(etc.) β still works, but these classes are now raised for real and importable fromeerodirectly. - Grep for
X-User-Token,"Cookie", orAuthorizationin anyheaders=you pass to the transport β remove them. - Grep for
allow_redirectsβ remove; it cannot be set. - Grep for
from eero.const importofDEFAULT_HEADERS,REFRESH_ENDPOINTS,ACCOUNT_REFRESH_ENDPOINT,SESSION_TOKEN_KEY,REFRESH_TOKEN_KEY, orMAX_ERROR_BODY_CHARSβ replace per the table above. - Grep for
get_data_usage(β passstart=,end=,cadence=; droppayload/resource; move per-resource reads to the explicitDataUsageAPImethods. - Grep for
get_ouicheck(β passserial=andversion=. - Long-running processes: remove any home-grown periodic refresh; handle a terminal
EeroAuthenticationExceptionby re-seeding a token or re-running the OTP flow.
What broke: nothing. This minor release is additive; no existing call changes behaviour except the two noted under "Changed behaviour" below.
Each one wraps the same-named domain method. Calls that previously had to go through the domain APIs no longer do.
| New method | Notes |
|---|---|
create_burst_reporter() |
Requests a live-usage burst (POST ""); the device list's usage.down_mbps / usage.up_mbps refresh about 12 seconds later. At most one per minute per network |
reboot_network() |
Reboots every eero. Never retry it in a loop |
resend_verification_code() |
Needs a pending login()
|
clear_auth_data() |
Removes every stored credential record from every backend without contacting the API |
add_to_blacklist(mac) / remove_from_blacklist(mac_or_device_id)
|
Direct forms; block_device / unblock_device are the aliases |
set_weekday_bedtime(...) / set_weekend_bedtime(...)
|
Each call creates a new schedule; see Python API |
request_support(request_data) |
Body forwarded unchanged; callers own validation |
set_ipv6_upstream(enabled) |
Writes ipv6_upstream only; set_ipv6 writes both upstream and downstream |
get_eeros_data_usage(*, start, end, cadence) |
Read-only |
set_network_ad_block(enabled, *, profiles=None) / set_network_block_malware(enabled)
|
Premium; unverified writes |
-
create_burst_reporternow sends the""body, like the other parameterless POSTs. Thereporter_dataargument ofBurstReportersAPI.create_burst_reporteris deprecated: it emitsDeprecationWarningand is removed in 9.0.0. While it lasts, a supplied non-empty value is still forwarded as the JSON body. Drop the argument; see Deprecations. -
set_thread_enabledis now an alias ofupdate_thread(thread_enable=enabled). The body is{"thread_enable": bool}; theenabledkey it sent before is not in the observed spec. The write is still unverified.
- Replace any reach-through into the domain APIs for burst reporters, network reboot,
resending the verification code, clearing auth data, weekday/weekend bedtime and support
requests with the
EeroClientmethods above. - Grep for
reporter_dataand stop passing it. - If you relied on
set_weekday_bedtime/set_weekend_bedtimereplacing an existing schedule, note that they only ever created one; delete the old pause first.
-
Pin your version (
eero-api==7.0.0or a narrow range) rather thaneero-api>=...β this is a fast-moving SDK tracking an undocumented, reverse-engineered API, and breaking changes ship as major versions on purpose. -
Read
CHANGELOG.mdfor every major version between your current pin and your target β don't skip versions when judging blast radius. -
Find breakage fast by grepping your codebase for:
-
eero.modelsorfrom eero.modelsβ removed in v2.0.0. -
Error)/except eero.*Errorβ this SDK has only ever used*Exceptionsuffixes; if you see*Error, it's a bug in your code, not a rename to chase. - Attribute access on anything returned by an
eero-apicall (result.name,result.status) β since v2.0.0 every result is a rawdict. - Positional
network_idarguments passed anywhere other than first onEeroClientmethods, or first onEeroAPI/domain-API methods βnetwork_idis always a required leading positional on the low-level APIs and an optional trailing keyword onEeroClient. -
set_preferred_network(/preferred_network_idon anEeroAPIinstance β removed in v5.0.0, see above. -
get_insights(calls missingstart=/end=/insight_type=β required since v6.0.0. -
set_custom_dns(/set_dns_mode(/clear_custom_dns(/set_dns_caching(β these were no-ops before v7.0.0 and now take effect. Also grep forcustom_dns,dns_cachinganddns_serversas response keys: none of them exist in the API. -
set_device_priority(,get_activity,set_ipv6_dns(,run_insights(,run_ouicheck(,set_thread(,get_settings(,get_password(, andget_burst_reporters(β all removed outright in v8.0.0, see above. -
set_sqm_enabled(,configure_sqm(,set_sqm_bandwidth(,set_sqm_auto(,get_backup_network(,get_backup_status(,set_backup_network(,configure_backup_network(,get_profile_schedule(,set_profile_schedule(,update_profile_content_filter(,update_profile_block_list(,get_blocked_applications(,set_blocked_applications(β removed in v8.0.0 with the write re-pointing, see above. -
set_guest_network(withpassword=,block_device(withblocked=,set_nightlight(withbrightness=/schedule_enabled=/schedule_on=/schedule_off=/ambient_light_enabled=,set_nightlight_schedule(withon_time=/off_time=, anddevice_id=by keyword on aDevicesAPImethod β re-signatured in v8.0.0, see above. -
session_expiry,refresh_token,MAX_ERROR_BODY_CHARS,DEFAULT_HEADERS,REFRESH_ENDPOINTSβ removed in v8.0.0 with the transport/auth changes, see above. -
get_data_usage(withoutstart=/end=/cadence=, andget_ouicheck(withoutserial=/version=β signatures changed in v8.0.0, see above. -
set_led(/set_led_brightness(β not a signature change, but the pre-v8.0.0 write was verified to change nothing; any behaviour built on it has never actually run.
-
- Deprecations β surface that still exists but should not be used
-
Raw Response Format β the
{"meta": ..., "data": ...}envelope -
Error Handling β the
EeroExceptionhierarchy -
Network Targeting β passing
network_idcorrectly - API Reference β every domain API and method signature
eero-api β unofficial async Python client for the Eero cloud API. Not affiliated with or endorsed by Eero.
This wiki is generated from wiki/ in the main repository β edit there, not here. Β· MIT License