REST API — scenes
Scenes run sets of commands saved in the installation. REST API lets you start or stop an existing scene. Find the scene number in the mobile application: id must be an integer in the range 0–1999. A valid number range alone does not confirm that the scene exists. The API does not provide a scene list, configuration, or current scene status.
First configure access using Getting started. In the examples, replace SERVER_ADDRESS, PORT, and API_KEY with the installation address, HTTPS port, and key from the panel. The number 12 is fictional; replace it with the number of an existing scene. Method paths are relative to /integrations/api.
Both GET methods described here change the installation state. Call them deliberately as commands. Do not use their addresses for status polling or automatic refresh. The effects of retries and lost responses are described below.
Start: GET /scene/start
Runs the commands saved in the scene. Query parameters are values appended to the address after ?; further parameters are separated by &. This method does not require a body, meaning the part of a request containing data to send.
| Parameter | Requirement | Meaning |
|---|---|---|
id |
Required, integer 0–1999 |
Number of an existing scene from the mobile application. |
time |
Optional, non-negative integer | Hold duration in seconds. |
Choose the duration
| Variant | Behaviour |
|---|---|
Omit time |
Uses the default duration saved in the scene. |
time=0 |
Executes commands without establishing a new hold. |
Positive time, such as time=3600 |
Holds temperature setpoints for the specified duration, one hour in this example. The maximum duration is 5 356 800 s, or 62 days. |
A hold means that the scene maintains setpoints; currently this applies to temperature setpoints. It is not a duration after which all scene actions are automatically reversed. Expiry ends the hold without sending opposite commands for all previously completed actions. Delayed commands follow the delays saved in the scene; time does not replace those delays.
time=0 does not remove an earlier hold belonging to an active scene. Use GET /scene/stop, described below, to remove holds and pending delayed commands.
Use a duration of at most 5 356 800 s in your integration. A larger number is usually capped at this maximum, so exceeding the limit alone does not guarantee an HTTP error or an invalid_time status.
Example with the default duration
HTTP request without the time parameter:
GET /integrations/api/scene/start?id=12 HTTP/1.1
Host: SERVER_ADDRESS:PORT
Authorization: Bearer API_KEY
The same request using curl; --include also displays response headers:
curl --include --request GET \
'https://SERVER_ADDRESS:PORT/integrations/api/scene/start?id=12' \
--header 'Authorization: Bearer API_KEY'
Example response with a complete body in JSON, a text data format:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"logic_action":"on_scene","status":"ok"}
logic_action: "on_scene" identifies the start result. status: "ok" means that the scene start command was accepted; it does not confirm that physical devices have performed every action or that delayed commands have finished. Check the response body together with the HTTP code.
Other duration variants
Each example below is a separate command. Choose the variant that matches the intended action; do not run all of them in sequence to check access.
Start without a new hold:
curl --include --request GET \
'https://SERVER_ADDRESS:PORT/integrations/api/scene/start?id=12&time=0' \
--header 'Authorization: Bearer API_KEY'
Start with a one-hour hold of temperature setpoints:
curl --include --request GET \
'https://SERVER_ADDRESS:PORT/integrations/api/scene/start?id=12&time=3600' \
--header 'Authorization: Bearer API_KEY'
When accepted, both variants return the same on_scene result with ok status as the default-duration example.
Start errors
A missing id, a non-integer value, or a number outside 0–1999 returns HTTP 400 with this complete JSON body:
{"error":"Scene ID must be a number between 0 and 1999"}
An invalid time, such as -1 or 1.5, returns HTTP 400 with this complete JSON body:
{"error":"Time must be a non-negative integer"}
If the number is valid but the scene does not exist, the response may have HTTP 200 with this complete JSON body:
{"logic_action":"on_scene","status":"invalid_scene_num"}
This is a rejected command, not a success. Check the scene number and existence in the mobile application. Access errors (401, 403), the HTTPS redirect (308), and processing errors (500) are described on the Responses and errors page.
Stop: GET /scene/stop
Removes holds belonging to the specified scene and its pending delayed commands. Requires the query parameter id: an integer 0–1999 identifying an existing scene, obtained from the mobile application. No body or time parameter is required.
Stopping does not automatically send opposite commands for actions already performed. For example, a relay turned on by the scene does not automatically receive a command to turn off as a result. Ending a temperature hold also does not constitute a command to restore the previous setpoint.
HTTP request:
GET /integrations/api/scene/stop?id=12 HTTP/1.1
Host: SERVER_ADDRESS:PORT
Authorization: Bearer API_KEY
The same request using curl:
curl --include --request GET \
'https://SERVER_ADDRESS:PORT/integrations/api/scene/stop?id=12' \
--header 'Authorization: Bearer API_KEY'
Example response with a complete JSON body:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"logic_action":"off_scene","status":"ok"}
logic_action: "off_scene" identifies the stop result. The ok status confirms that the command was handled, without confirming reversal of earlier actions.
A missing id, a non-integer value, or a number outside the range returns HTTP 400 with this complete JSON body:
{"error":"Scene ID must be a number between 0 and 1999"}
A scene that does not exist may return HTTP 200 with this complete JSON body:
{"logic_action":"off_scene","status":"invalid_scene_num"}
Check the scene number and existence in the mobile application. Common access and processing errors are described on the Responses and errors page.
Retries and lost responses
Starting a scene again may repeat its actions, renew its hold duration, and reschedule delayed commands. A repeated call is another command, even when it uses the same id and time.
A timeout, meaning that the wait for a response exceeded its limit, or a broken connection does not prove that the start or stop did not execute. The server does not automatically retry a sent command. Do not configure unconditional automatic retries for these requests: another start may repeat effects, while another stop may remove holds and commands added by a scene start in the meantime.
Before retrying manually, check the available installation state, for example in the mobile application, and decide whether another start or stop matches the intended action. REST does not provide a current scene status read that would establish the outcome of a lost request. The Responses and errors page describes timeouts and response interpretation in more detail.
Return to Getting started to choose another task.