Skip to content

REST API — getting started

REST API allows an external integration to read and write project variables, start and stop scenes, and read the state of F&Home devices. Devices are controlled through variables connected to project logic or through scenes.

A request is a single call to an API address using a selected HTTP method, such as GET for reading. Start by retrieving the variable list: this read does not change the installation state.

Enable access in the panel

  1. Sign in to the web panel as an administrator.
  2. Open Settings → System management → Remote access → Manage → REST API.
  3. If no key exists yet, select Generate key.
  4. Turn on Enable REST API and wait for the confirmed Active state.
  5. Select Copy key.
  6. Enter the key in your integration configuration and perform the first read described below.

Opening the screen does not generate a key or enable REST API. Generating a key preserves the current enabled state. Disabling REST API preserves the key, so the same value can be used after enabling it again.

While REST API is disabled, the panel blocks copying and replacing an existing key and changing Allow HTTP. Initial key generation remains available so that access can be prepared before enabling it.

To replace an existing key while REST API is active, select Generate a new token and confirm the operation. The previous key will stop working. Enter the new key in every integration that uses it.

If the panel does not receive confirmation of an operation, do not assume that the change did not happen. Rely on reading the state and key again. When the panel offers Read the state again, use that option; if the session is missing or has expired, select Sign in again. The last confirmed state may not reflect the result of an unconfirmed change.

Key and authorization header

A header is additional information included in an HTTP request. Every REST API call requires this header:

Authorization: Bearer API_KEY

Replace API_KEY with the copied key. Keep the exact word Bearer, with a capital B, and one space before the key. Send the key only in this header, without placing it in the URL or request body.

A new key contains 32 alphanumeric characters. It is shared by REST integrations, has no expiry date, and has no separate scopes for applications or devices. Access does not inherit an individual user account's restrictions on selected variables or scenes. Keep the key secret.

The integration key is independent of the administrator session token. Configure your integration using the key from the REST API section.

Server address and connection

The API base address has this form:

https://SERVER_ADDRESS:PORT/integrations/api
  • Replace SERVER_ADDRESS with the installation's direct address, reachable from the device running the integration.
  • Replace PORT with the installation's HTTPS port. If the connection uses the default HTTPS port 443, the :PORT part can be omitted.
  • /integrations/api is the fixed API path. Do not append panel address fragments such as /#/system/remote.

The cloud panel name and enabling cloud access do not establish REST access. The cloud panel tunnel does not carry REST API calls; the integration needs a direct connection to the installation.

Connections from loopback source addresses, including 127.0.0.1 and ::1, are rejected even with a valid key. Use a network connection to the installation's address instead of a loopback address.

HTTPS and optional HTTP

If the installation uses HTTPS, use the correct HTTPS address and a certificate trusted by the integration client. The address must match the certificate.

Allow HTTP permits unencrypted REST requests that still require the key. It is disabled by default. Enabling it keeps HTTPS available, but does not itself activate HTTPS or TLS. Prefer HTTPS with proper certificate verification.

When HTTPS is active, a remote HTTP request without this exception receives an HTTP 308 redirect to the HTTPS address. When HTTPS is not active, disabling Allow HTTP alone does not block the existing HTTP service.

The HTTP option does not change the key, the REST API enabled state, or cloud configuration. The saved preference remains in place after disabling and enabling REST API again.

First read: GET /variable/list

This method retrieves the names of variables available in the project. It requires no parameters, meaning additional values passed to a method, and no request body. The result does not include variable values, units, or type declarations.

Example HTTP request; replace all address, port, and key placeholders as described above:

GET /integrations/api/variable/list HTTP/1.1
Host: SERVER_ADDRESS:PORT
Authorization: Bearer API_KEY

The same call using curl; --include also displays response headers:

curl --include --request GET \
  'https://SERVER_ADDRESS:PORT/integrations/api/variable/list' \
  --header 'Authorization: Bearer API_KEY'

The server returns JSON, a text data format using, among other things, arrays in [] brackets and objects in {} braces. Example response with a complete JSON body and fictional variable names:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

["garden_light", "room_temp"]

An empty array is also a valid complete JSON response:

[]

It means that no variables are available in the current project. If you expect names, check the active variable blocks and save the project. An empty list with HTTP 200 is a valid result.

The Variables page explains the next steps: preparing a variable in the project, reading its value, and controlling devices through writes.

Access errors (401, 403), the HTTPS redirect (308), and processing errors (500) are described on the Responses and errors page. For this method, the expected result is an array of names without a status field.

Prepare the format for later writes

The body is the part of a request containing the data to send. When writing JSON data, include this header:

Content-Type: application/json

It tells the server how to read the body. The JSON value type matters: true, 1, and "1" represent a boolean, a number, and text, respectively.

Next steps

  • Variables — reading a measurement, controlling a device property, and batch operations.
  • Scenes — starting and stopping scenes, choosing the hold duration, and the effects of retrying commands.
  • Devices — retrieving the list, selecting an object, and reading its state with an interpretation of availability and values.
  • Responses and errors — identifying access errors, command results, and uncertainty after losing a response.
  • F&Home documentation table of contents.