docs: refresh Overkiz End-User RESTful API mirror (2026.2.1)

[iMicknl]

Refreshes docs/api/ from a fresh save of the upstream Overkiz End-User RESTful API doc page. Local <link>/<script> paths were flattened (from ./API Documentation - End-User RESTful API_files/) to match the existing layout.

Only two files actually change:

• docs/api/index.html — the doc content.
• docs/api/jquery-ui.min.js — not a version bump. Same jQuery UI 1.13.2 build; the previously committed copy contained a mojibake double-encoded U+FFFD (C3 AF C2 BD C2 BD) where the fresh save has a correct one (EF BF BD). 3 bytes smaller.

jquery.min.js and apiDocStyle.css were byte-identical. apiDocDyn.js differed only in trailing whitespace, which the repo's pre-commit hooks strip, so it nets to no change.

Newest upstream version marker in the page is 2026.2.1 (previous mirror topped out at 2021.6). Operation count: 495 → 504.

Verified by serving docs/api/ locally: all five files return 200, the HTML parses, and the operation count is stable after the whitespace pre-commit hooks run.

---

✅ Verified against the live Somfy Europe API

Probed with a real Somfy account (read-only: GETs, an event listener, and non-mutating state refreshes). Gateway firmware 2026.3.3-7, i.e. newer than this doc's 2026.2.1 marker — so the server is at or beyond the documented version, and anything the docs claim that the server doesn't do is a doc bug, not a not-yet-deployed feature.

The event-envelope rename is a documentation artifact — no code change needed

The live event stream (POST /events/{listenerId}/fetch) still uses the old field names:

{"siteOID": "<redacted>", "setupOID": "<redacted>", "gatewayId": "<redacted>",
 "timestamp": 1786543241494, "name": "GatewaySynchronizationStartedEvent"}

Field	Docs claim	Live (2026.3.3)	Verdict
name → type	type	name (5/5 events)	❌ docs wrong
timestamp → eventTime	eventTime	timestamp (5/5 events)	❌ docs wrong
siteOID added	present	present (4/5 events)	✅ real

pyoverkiz/models.py Event is correct as-is. The name/timestamp → type/eventTime rename in the doc's event samples is a generator artifact (the samples appear to be rendered through a Jackson type discriminator that the wire format doesn't use). Same for the knock-on type → placeType rename: live GET /setup/places still returns "type": 200, not placeType.

This retires the blocking concern. No change to event parsing.

eventTime is real — but on executions, not stream events

The rename is genuine for execution objects, where the previous mirror was the wrong one:

{"eventTime": 1786451177935, "executionType": "Immediate execution",
 "type": "Planning - TIME_TRIGGER", "state": "COMPLETED", ...}

GET /history/executions and /history/executions/daily/... return eventTime and executionType, with no timestamp. HistoryExecution in pyoverkiz/models.py:926 already models both as event_time / execution_type, so there's no gap here either.

Confirmed real (live values)

Claim	Live result
siteOID on GET /setup	✅ present (UUID, redacted)
siteOID on events	✅ 4/5 events (absent on DeviceStateChangedEvent)
updateDeferralEnabled on gateway	✅ false
roleName on GET /enduser/setups	✅ FullAccessEndUserTemplate
GET /history/dataRetentionPolicy	✅ {"states": 60, "executions": 90}
GET /setup/localDevices	✅ [] (endpoint exists; account has none)
GET /history/executions/daily/{y}/{m}/{d}	✅ returns {"limitReached": false, "executions": [...]}
GET /config/{gatewayId}/upnpcontrol/sonos/checkActionGroups	✅ gone — No such resource

Not confirmed either way

• relatedDevices / technical on executions — absent from this account's execution history. Plausibly only on technical or multi-device executions.
• Device-level category / localDeviceOID / localDeviceData / mapped — absent from all 12 devices, but the account has zero local devices, so there was nothing to populate them.
• zoneType — the account has no zones.
• commandLess / authenticationRestrictedCommands / partnerId / model on GET /setup — not present here.

The one genuine gap

siteOID is live on both GET /setup and most stream events, and is not modelled anywhere in the library (no site_oid on Setup or Event; unknown keys are silently dropped by the converter). That's the only field this refresh surfaces that we're actually missing.

---

New: Local Devices

New section, replacing the removed UPnP Control protocol section. All at scope enduser/*.

Operation	Description
GET /setup/localDevices	Get all local devices (includeMapped param)
POST /setup/localDevices	Create a new local device
GET /setup/localDevices/{localDeviceOID}	Get a specific local device by OID
DELETE /setup/localDevices/{localDeviceOID}	Delete a local device (forced to allow deleting a mapped device)
PUT /setup/localDevices/{localDeviceOID}/label/{newLabel}	Rename a local device
PUT /setup/localDevices/{localDeviceOID}/localDeviceData	Update local device data
PUT /setup/localDevices/{localDeviceOID}/relocate/{placeOID}	Relocate into an existing place
PUT /setup/devices/{deviceURL}/localDeviceData/{key}	Update one local-device-data key on a regular device

New events: LocalDeviceCreatedEvent, LocalDeviceUpdatedEvent (label/place), LocalDeviceDeletedEvent, LocalDeviceDataUpdatedEvent.

New: history endpoints

Operation	Description
GET /history/dataRetentionPolicy	Retention for executions and states, in days
GET /history/executions/daily/{year}/{month}/{day}	Executions for one day; capped at 200, errors outside the retention window

New: device rename endpoint (+ deprecation)

• Added PUT /setup/devices/{deviceURL}/label/{label} — update the name of a device, with an updateDeviceName param ("If true, device name will also be updated").
• Deprecated PUT /setup/devices/{deviceURL}/{label} — since version 2026.2.1. This is the only newly deprecated operation; the deprecated total goes 73 → 74.

Removed

Operation	Description
GET /config/{gatewayId}/upnpcontrol/sonos/checkActionGroups	Check if action groups are consistent with the topology
POST /config/{gatewayId}/upnpcontrol/sonos/topology/{deviceURL}	Get sonos topology

Along with the whole UPnP Control protocol section (private tag upnpcontrol-config) and its events: SonosGetTopologySuccessEvent, SonosGetTopologyFailedEvent, SonosTopologyChangedEvent.

Net event count: 138 → 139.

New query parameters on existing operations

Param	Where	Values
actionGroupCategory	action group listing	persistent, nonPersistent, any (default any)
executionCategory	execution listing	manual, automation, any (default any)
includeMapped	GET /setup/localDevices	include mapped devices (default false)
forced	DELETE /setup/localDevices/{localDeviceOID}	allow deleting a mapped device
updateDeviceName	PUT /setup/devices/{deviceURL}/label/{label}	also update the device name

New response fields on existing operations

Fields absent from the previous mirror entirely:

Field	Appears on
siteOID	~396 occurrences — events plus most setup/enduser payloads
relatedDevices	execution payloads — "List of devices involved in this execution"
technical	execution payloads
localDeviceOID, localDeviceData, localDevices, mapped	GET /setup, /setup/devices, /setup/devices/hidden, /setup/devices/{deviceURL}
category	device payloads
commandLess, authenticationRestrictedCommands	GET /setup (device definitions)
updateDeferralEnabled	GET /setup, /setup/gateways, /setup/gateways/{gatewayId}
partnerId, model	GET /setup
roleName	GET /enduser/setups, POST /enduser/mainAccount, POST /enduser/secondaryAccounts, POST /enduser/setup, POST /setup/enduser, PUT /enduser/account

executionType is not new but its use widened substantially (11 → 47 occurrences), as did features (1 → 7) and attributes (5 → 11).

Other changes

• Zigbee commissioning-code limit raised from 4 to 127 (Add one or more device commissioning code(s) on given protocol for a future pairing procedure).
• GET /setup/devices/{deviceURL}/states/{name}/history/export now documents a 200 response code.
• One additional rate-limited operation (46 → 47); one fewer restricted operation (30 → 29).
• Access-scope labels shortened throughout — Access scope : Full enduser API access (enduser/*) → Access scope : enduser/*, and Enduser Open API (enduser/o) → enduser/o. Cosmetic; touches nearly every operation and accounts for most of the diff noise.

Not changed

No library code was touched in this PR. Verified follow-ups, in priority order:

• Add site_oid to Setup and Event — confirmed live, currently dropped.
• Consider modelling the Local Devices endpoints (all live; needs an account with local devices to exercise).
• Confirm eventTime / type / siteOID against a real event stream — done; event parsing needs no change.
• Consider relatedDevices / executionType on execution models — execution_type already modelled; relatedDevices unobserved.

[iMicknl]

Verified against the live Somfy Europe API 🔍

Probed a real Somfy account read-only (GETs, an event listener, non-mutating state refreshes). Gateway firmware 2026.3.3-7 — newer than this doc's 2026.2.1 marker, so anything the docs claim that the server doesn't do is a doc bug, not a pending rollout.

The event-envelope rename is a doc artifact — no code change needed. The live stream still sends name + timestamp (5/5 events), not type/eventTime. Same for the knock-on rename: GET /setup/places still returns "type": 200, not placeType. Event in pyoverkiz/models.py is correct as-is.

eventTime is real, but only on executions. GET /history/executions returns eventTime + executionType and no timestamp — there the old mirror was wrong. HistoryExecution already models both, so no gap.

Confirmed live: siteOID (on GET /setup and 4/5 events) · updateDeferralEnabled · roleName · GET /history/dataRetentionPolicy → {"states": 60, "executions": 90} · GET /setup/localDevices → [] · daily-executions endpoint · Sonos checkActionGroups genuinely gone (No such resource).

Unconfirmed: relatedDevices/technical, and the device-level local-device fields — the test account has zero local devices and zero zones, so there was nothing to populate them. Absence isn't evidence against them.

One genuine gap: siteOID is live but modelled nowhere (no site_oid on Setup or Event; the converter drops unknown keys silently). Top follow-up.