REST API — variables
Variables connect an integration to project logic: they let you read a measurement made available by a block or pass a value for control. The API reads and writes existing variables; it does not create them.
First configure access using Getting started. In the examples below, replace SERVER_ADDRESS, PORT, and API_KEY with the installation address, HTTPS port, and key from the panel. Method paths are relative to /integrations/api. Example names and values are fictional. Common access and processing errors are described on the Responses and errors page.
Prepare variables in the project
A variable is available when the saved project contains at least one correctly configured, active variable block with that name. No separate publication or API export option is required. All instances with the same name share one value.
A name must contain 1 to 25 characters: ASCII letters (A–Z, a–z), digits, or _. The first character must not be a digit. Names are case-sensitive: room_temp and Room_temp are different names. A variable block variable is not a device created by app-value.
Read a measurement: input → variable
- Add an
inputblock. Under Device, select the room temperature sensor, and under Property, select its temperature measurement. - Add a
variableblock and set Name toroom_temp. - Connect output 1 of
inputto thevariableblock input. Output 1 provides the value; output 2 reports whether the device is attached. - Save the project. After receiving a measurement from the device, read
room_tempusingGET /variableas described below.
For example, a measurement of 21.5 is returned as a number. In this flow, it means a temperature in °C because the measurement source is configured that way; the variable response itself does not include a unit.
Control a device: variable → output
- Add a
variableblock and set Name togarden_light. - Add an
outputblock. Under Device, select the relay controlling the garden light, and under Property, select its binary output. - Connect the
variableblock output to theoutputblock input and save the project. - Send
POST /variablewith{"name":"garden_light","value":true}, as in the example below. Use the JSON booleanstrueorfalsefor this property.
The value type and range must match the selected property. output does not change the received value's type. A write status of ok confirms that the variable accepted the value, but does not confirm physical execution by the device. The output block page explains behavior when detached and value filtering.
Types, initial value, and precision
Supported write values are:
| JSON type | Example value values |
|---|---|
| No value | null |
| Boolean | true, false |
| Number | 0, 21.5, 40 |
| Text | "evening", "1", "" |
Objects and arrays are not supported variable values. true, 1, and "1" are different values. A later write can change the variable's type. null means no value and is different from zero, false, or empty text.
The initial absence of a value is read as null. Values are not persistent: after a restart or project reload, they must be supplied again by the logic or written through the API.
Numbers have a resolution of 0.001. Further digits are truncated toward zero rather than rounded; floating-point representation can affect the conversion result. Use typical automation ranges and do not assume support for arbitrarily large numbers, including integers. A numeric read does not include a unit; its meaning comes from the project configuration.
List names: GET /variable/list
Retrieves an array of available variable names. It requires no parameters or body. The result does not include values, units, or type declarations.
HTTP request:
GET /integrations/api/variable/list 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/variable/list' \
--header 'Authorization: Bearer API_KEY'
Example response with a complete JSON body:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
["garden_light", "room_temp"]
An empty array [] with HTTP 200 is a valid result: the project exposes no variables. Check the variable blocks and save the project if you expect names. Access and processing errors are described on the Responses and errors page.
Read one variable: GET /variable
Supply the name in the name query parameter. Query parameters are appended to the address after ?, for example ?name=room_temp. The method requires no body.
HTTP request:
GET /integrations/api/variable?name=room_temp 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/variable?name=room_temp' \
--header 'Authorization: Bearer API_KEY'
Example response with a complete JSON body:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"value":21.5}
An existing variable with no value returns the complete body {"value":null}. An unknown variable normally returns HTTP 200 with the complete body {"status":"invalid_variable"}. Do not interpret this as success or expect HTTP 404 as the normal result for an unknown variable. A successful read has a value field and does not have to contain status.
Write one variable: POST /variable
Send a JSON object with a text name and a value field of a supported type. The Content-Type: application/json header specifies the body format and preserves the value type.
HTTP request:
POST /integrations/api/variable HTTP/1.1
Host: SERVER_ADDRESS:PORT
Authorization: Bearer API_KEY
Content-Type: application/json
{"name":"garden_light","value":true}
The same request using curl:
curl --include --request POST \
'https://SERVER_ADDRESS:PORT/integrations/api/variable' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"garden_light","value":true}'
Example response with a complete JSON body when the value was changed:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"status":"ok"}
Check the status field even with HTTP 200:
status |
Meaning |
|---|---|
ok |
The variable accepted the value and passed it to connected logic; this does not confirm physical execution by the device. |
already_set |
The variable already has the same value. The write does not trigger the logic again. |
invalid_variable |
A valid name is missing or the project does not expose a variable with that name. Check the active block and save the project. |
invalid_value |
The value field is missing or its type is unsupported, such as an object or array. |
Disabling Block duplicated value in output does not bypass already_set: such a write stops before passing the value to the logic again.
A single write also accepts the name and value query parameters. Each supplied query parameter takes precedence over its corresponding body field. A query value remains text: value=true means the text "true", not the boolean true. Use a JSON body as in the example and omit these URL parameters when you want to preserve the type.
Batch operations
Both batch methods accept a nonempty JSON array directly, without a wrapping data object. An invalid list or element structure causes HTTP 400 before any command is sent:
- reads require text names;
[]or["room_temp", 7]is rejected; - writes require objects with a text
nameand a presentvaluefield;[]or[{"name":"garden_light"}]is rejected.
null, false, 0, and empty text are present values, not a missing field. Example complete write body with a valid structure; each of these fictional names must exist in the project:
[
{"name":"empty_value","value":null},
{"name":"enabled_flag","value":false},
{"name":"counter_value","value":0},
{"name":"mode_text","value":""}
]
An object or array in value passes the field-presence check but produces invalid_value for that item. It does not cause the entire list's structure to be rejected before execution.
Read multiple variables: POST /variables/get
Retrieves values for the names supplied in the body. In this example, garden_light and room_temp exist, while missing_variable does not.
HTTP request:
POST /integrations/api/variables/get HTTP/1.1
Host: SERVER_ADDRESS:PORT
Authorization: Bearer API_KEY
Content-Type: application/json
["garden_light","room_temp","missing_variable"]
The same request using curl:
curl --include --request POST \
'https://SERVER_ADDRESS:PORT/integrations/api/variables/get' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '["garden_light","room_temp","missing_variable"]'
Example response with a complete JSON body:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[{"name":"room_temp","value":21.5},{"name":"garden_light","value":true}]
Unknown variables are omitted. If none of the supplied variables exist, [] is a valid result. An existing variable with no value remains in the result with "value":null.
Write multiple variables: POST /variables/set
Writes values from the objects in the body. In this example, garden_light and target_temp exist in the saved project, target_temp already has the value 21.5, and missing_variable does not exist.
HTTP request:
POST /integrations/api/variables/set HTTP/1.1
Host: SERVER_ADDRESS:PORT
Authorization: Bearer API_KEY
Content-Type: application/json
[{"name":"garden_light","value":true},{"name":"target_temp","value":21.5},{"name":"missing_variable","value":false}]
The same request using curl:
curl --include --request POST \
'https://SERVER_ADDRESS:PORT/integrations/api/variables/set' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '[{"name":"garden_light","value":true},{"name":"target_temp","value":21.5},{"name":"missing_variable","value":false}]'
Example response with a complete JSON body if the exchange completed successfully and garden_light changed value:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[{"name":"target_temp","status":"already_set"},{"name":"garden_light","status":"ok"},{"name":"missing_variable","status":"invalid_variable"}]
Each item has its own status result, with the meanings described for single writes. HTTP 200 does not mean every write succeeded.
Order, partial execution, and limits
For both batch methods, response order does not have to match input order. Use unique names as in the examples and match results by name, not by list position.
A batch write is not a transaction and does not roll back earlier changes. A transport error or timeout can end the entire request after some writes have taken effect, without returning a partial result. The approximately 5-second waiting limit applies to the complete set of replies, not separately to each item. Processing or exchange failures may produce HTTP 500.
The server does not automatically resend commands. After losing a response, do not assume the write did not happen; read the values and assess the result before deciding on another write. Reading the variable still does not confirm physical execution by the device.
The established HTTP limit is a 1 MiB body; exceeding it produces HTTP 413. There is no separate established item-count limit here. Details of errors and uncertainty after a timeout are described on the Responses and errors page.
Return to Getting started for access configuration.