Skip to content

AdvancedApi

Get all registered decentral webhooks.

GET /api/decentralWebhook

Returns:

Type Description
List[Dict[str, Any]]

List of webhook objects.
Source code in nukiwebapi/advanced_api.py 
11
12
13
14
15
16
17
18
19
20
def list_decentral_webhooks(self) -> List[Dict[str, Any]]:
    """
    Get all registered decentral webhooks.

    GET /api/decentralWebhook

    Returns:
        List of webhook objects.
    """
    return self.client._request("GET", "/api/decentralWebhook").json()

Create a new decentral webhook.

PUT /api/decentralWebhook

Parameters:

Name Type Description Default
webhook_url str

The HTTPS URL to receive webhooks.

 required
webhook_features List[str]

Features to trigger webhooks. Must be subset of: ["DEVICE_STATUS", "DEVICE_MASTERDATA", "DEVICE_CONFIG", "DEVICE_LOGS", "DEVICE_AUTHS", "ACCOUNT_USER"]

 required

Returns:

Type Description
Dict[str, Any]

API response dict.
Source code in nukiwebapi/advanced_api.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def create_decentral_webhook(self, webhook_url: str, webhook_features: List[str]) -> Dict[str, Any]:
    """
    Create a new decentral webhook.

    PUT /api/decentralWebhook

    Args:
        webhook_url (str): The HTTPS URL to receive webhooks.
        webhook_features (List[str]): Features to trigger webhooks. Must be subset of:
            ["DEVICE_STATUS", "DEVICE_MASTERDATA", "DEVICE_CONFIG",
             "DEVICE_LOGS", "DEVICE_AUTHS", "ACCOUNT_USER"]

    Returns:
        API response dict.
    """
    if not webhook_url.startswith("https://"):
        raise ValueError("webhook_url must start with https://")

    allowed_features = {
        "DEVICE_STATUS", "DEVICE_MASTERDATA", "DEVICE_CONFIG",
        "DEVICE_LOGS", "DEVICE_AUTHS", "ACCOUNT_USER"
    }

    if not isinstance(webhook_features, list) or not all(f in allowed_features for f in webhook_features):
        raise ValueError(f"webhook_features must be a list containing only allowed values: {allowed_features}")

    payload = {
        "webhookUrl": webhook_url,
        "webhookFeatures": list(set(webhook_features))  # ensure uniqueness
    }

    return self.client._request("PUT", "/api/decentralWebhook", json=payload).json()

Unregister a decentral webhook.

DELETE /api/decentralWebhook/{id}

Parameters:

Name Type Description Default
webhook_id int

ID of the webhook to delete.

 required

Returns:

Type Description
Dict[str, Any]

API response dict.
Source code in nukiwebapi/advanced_api.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def delete_decentral_webhook(self, webhook_id: int) -> Dict[str, Any]:
    """
    Unregister a decentral webhook.

    DELETE /api/decentralWebhook/{id}

    Args:
        webhook_id (int): ID of the webhook to delete.

    Returns:
        API response dict.
    """
    if not isinstance(webhook_id, int):
        raise ValueError("webhook_id must be an integer")
    return self.client._request("DELETE", f"/api/decentralWebhook/{webhook_id}").json()

Get a list of webhook logs for a given API key (descending order).

GET /api/key/{apiKeyId}/webhook/logs

Parameters:

Name Type Description Default
api_key_id int

API key ID.

 required
id str

Filter for older logs.

 None
limit int

Maximum number of logs (max 100, default 50).

 50

Returns:

Type Description
List[Dict[str, Any]]

List of webhook logs.
Source code in nukiwebapi/advanced_api.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
def get_webhook_logs(self, api_key_id: int, id: Optional[str] = None, limit: int = 50) -> List[Dict[str, Any]]:
    """
    Get a list of webhook logs for a given API key (descending order).

    GET /api/key/{apiKeyId}/webhook/logs

    Args:
        api_key_id (int): API key ID.
        id (str, optional): Filter for older logs.
        limit (int): Maximum number of logs (max 100, default 50).

    Returns:
        List of webhook logs.
    """
    if not isinstance(api_key_id, int):
        raise ValueError("api_key_id must be an integer")
    if limit > 100 or limit < 1:
        raise ValueError("limit must be between 1 and 100")

    params: Dict[str, Any] = {"limit": limit}
    if id:
        params["id"] = id

    return self.client._request(
        "GET",
        f"/api/key/{api_key_id}/webhook/logs",
        params=params
    ).json()

Create asynchronous smartlock authorizations.

PUT /smartlock/auth/advanced

Parameters:

Name Type Description Default
auth_data dict

Smartlock authorization creation payload.

 required

Returns:

Type Description
Dict[str, Any]

API response dict.
Source code in nukiwebapi/advanced_api.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
def create_smartlock_auth_advanced(self, auth_data: Dict[str, Any]) -> Dict[str, Any]:
    """
    Create asynchronous smartlock authorizations.

    PUT /smartlock/auth/advanced

    Args:
        auth_data (dict): Smartlock authorization creation payload.

    Returns:
        API response dict.
    """
    return self.client._request("PUT", "/smartlock/auth/advanced", json=auth_data).json()

Execute a smartlock action with callback.

POST /smartlock/{smartlockId}/action/advanced

Parameters:

Name Type Description Default
smartlock_id str

Smartlock ID.

 required
action_data dict

Smartlock action payload.

 required

Returns:

Type Description
Dict[str, Any]

API response dict.
Source code in nukiwebapi/advanced_api.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
def action_smartlock_advanced(self, smartlock_id: str, action_data: Dict[str, Any]) -> Dict[str, Any]:
    """
    Execute a smartlock action with callback.

    POST /smartlock/{smartlockId}/action/advanced

    Args:
        smartlock_id (str): Smartlock ID.
        action_data (dict): Smartlock action payload.

    Returns:
        API response dict.
    """
    return self.client._request(
        "POST", f"/smartlock/{smartlock_id}/action/advanced", json=action_data
    ).json()

Lock a smartlock (advanced).

POST /smartlock/{smartlockId}/action/lock/advanced

Parameters:

Name Type Description Default
smartlock_id str

Smartlock ID.

 required
lock_data dict

Optional payload.

 None

Returns:

Type Description
Dict[str, Any]

API response dict.
Source code in nukiwebapi/advanced_api.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def lock_smartlock_advanced(self, smartlock_id: str, lock_data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
    """
    Lock a smartlock (advanced).

    POST /smartlock/{smartlockId}/action/lock/advanced

    Args:
        smartlock_id (str): Smartlock ID.
        lock_data (dict, optional): Optional payload.

    Returns:
        API response dict.
    """
    return self.client._request(
        "POST", f"/smartlock/{smartlock_id}/action/lock/advanced", json=lock_data or {}
    ).json()

Unlock a smartlock (advanced).

POST /smartlock/{smartlockId}/action/unlock/advanced

Parameters:

Name Type Description Default
smartlock_id str

Smartlock ID.

 required
unlock_data dict

Optional payload.

 None

Returns:

Type Description
Dict[str, Any]

API response dict.
Source code in nukiwebapi/advanced_api.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
def unlock_smartlock_advanced(self, smartlock_id: str, unlock_data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
    """
    Unlock a smartlock (advanced).

    POST /smartlock/{smartlockId}/action/unlock/advanced

    Args:
        smartlock_id (str): Smartlock ID.
        unlock_data (dict, optional): Optional payload.

    Returns:
        API response dict.
    """
    return self.client._request(
        "POST", f"/smartlock/{smartlock_id}/action/unlock/advanced", json=unlock_data or {}
    ).json()