Skip to main content
Version: 1.0

XT1

XT modules extend the standard API responses with additional properties. The sections below describe XT1-specific attributes and available Service methods. XT1 modules also support XMOD service.

Virtual Components​

In addition to the Virtual Components listed, XT1 devices supports one more type of Virtual Component called Virtual Object.

Virtual Object​

The virtual Object component is used to store an object (or null). It uses Object as RPC namespace and has the following methods:

Methods​

Object.SetConfig​

PropertyTypeDescription

id

number

Id of the component instance

config

object

Configuration that the method takes

Find more about the config properties in config section

Object.GetConfig​

Properties:

PropertyTypeDescription

id

number

Id of the component instance

Find the Object.GetConfig response properties in config section

Object.GetStatus​

Properties:

PropertyTypeDescription

id

number

Id of the component instance

Find more about the status response properties in status section

Object.Set​

This method updates the Object component.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the component instance. Required

value

object

Object to be saved. Required

Configuration​

The configuration of the Object component contains information about its properties and how it will be rendered in the UI. To Get/Set the configuration of the Object component its id must be specified.

Properties:

PropertyTypeDescription

id

number

Id of the component instance

name

string or null

Name of the component instance

meta

object or null

Stores the component's metadata

Status​

The status of the Object component contains information about its current value, the timestamp for the value update, and the source of the last command. To obtain the status of the Object component its id must be specified.

Properties:

PropertyTypeDescription

source

string

Source of the last command

value

object

Value of the component

last_update_ts

number

Unix timestamp for the value update

For all virtual components owned by a service, the API methods can be addressed using the owner and role parameters instead of the numeric id. For example:

Button.GetConfig example​

http://192.168.33.1/rpc/Button.GetConfig?owner="service:0"&role="open"

Response

{
  "id": 201,
  "name": "Open",
  "meta": {
    "ui": {
      "view": "button"
    }
  },
  "owner": "service:0",
  "access": "crw"
}

Note that any virtual component owned by a service includes additional fields in the response:

PropertyTypeDescription

owner

string

Identifies the owning service.

access

string

Describes access permissions:

  • * — Full access (all operations).
  • C — Full config access (GetConfig and SetConfig).
  • c — Read-only config access (GetConfig only).
  • w — Write access (also implies read) — allows modifying the property's value.
  • r — Read-only access — allows reading the property's value.

Button.Trigger example​

http://192.168.33.1/rpc/Button.Trigger?owner="service:0"&role="open"&event="single_push"

Response

null

Access Restriction​

note

Depending on the virtual component's permissions, some API requests may be blocked.

In that case the response will look like:

Boolean.SetConfig example​

http://192.168.33.1/rpc/Boolean.SetConfig?id=200&config={"owner":"service:0","role":"has_power","name":"Has Power","meta":{"ui":{"titles":["Close","Open"]}}}

Response

{
  "error": {
    "code": -107,
    "message": "Permission denied: SetConfig!"
  }
}

Shelly.GetDeviceInfo​

Request​

Parameters

Response​

On XT1 devices, the response contains extra fields describing the Service configuration and metadata:

PropertyTypeDescription

jwt

object

PropertyTypeDescription

xt1

object

XT1-specific configuration.

PropertyTypeDescription

svc0

object

Defines the service type to be executed by Application.

svc0

object

Service definition stored on the device file system.

PropertyTypeDescription

type

string

Service type.

ver

string

Service version.

build_id

string

Service build identifier.

Methods​

The Shelly.ListMethods RPC call on XT1 device shows the Service’s available methods.

Generic methods include:

Custom methods may also be defined for a specific device.
Example: Service.ReceiveWiFiSensorData.

Service.GetResources​

Returns information about the resources owned by the service.

Request​

Parameters:

PropertyTypeDescription

id

number

Service id. Required. (Currently, only 0 is supported).

Response​

PropertyTypeDescription

etag

string

Unique MD5 hash of the current service file.

vc

object

Each entry is a key–value pair where the key is the role of the component and the value is the key of the component formatted as "type:id".

Service.GetInfo​

Returns details about the Service and its metadata.

Request​

Parameters:

PropertyTypeDescription

id

number

Service id. Required. (Currently, only 0 is supported).

Response​

PropertyTypeDescription

type

string

Service type.

ver

string

Service version.

build_id

string

Service build identifier.

etag

string

Unique MD5 hash of the current service file.

meta

object

Additional service information

PropertyTypeDescription

ui

number

PropertyTypeDescription

svc_errors

object

Available service errors.

actions

object[]

Actions describe what the user can do with schedules or with webhooks.

conditions

object

Conditions define events that can trigger webhooks.

Service.GetConfig​

Retrieves the configuration parameters defined for the service instance.

Request​

Parameters:

PropertyTypeDescription

id

number

Service id. Required. (Currently, only 0 is supported).

Response​

On success, a JSON object containing the current service configuration is returned. The configuration is service-specific.

Service.SetConfig​

Updates the service's configuration.

Request​

Parameters:

PropertyTypeDescription

id

number

Service id. Required. (Currently, only 0 is supported).

config

object

New configuration object. Include only the properties that need to be updated.

Response​

PropertyTypeDescription

restart_required

boolean

True if restart is required, false otherwise

Service.GetStatus​

Reports current service state, memory usage, errors and flags.

Request​

Parameters:

PropertyTypeDescription

id

number

Service id. Required. (Currently, only 0 is supported).

Response​

PropertyTypeDescription

etag

string

Unique MD5 hash of the current service file.

state

string

Current state of the service.

stats

object

System resource usage statistics.

PropertyTypeDescription

mem

number

Current memory usage (number of variables)

mem_peak

number

Peak memory usage recorded since Service start (number of variables).

errors

string[]

Active service errors. Optional (Only if there are active errors).

flags

string[]

Active service flags. Optional (Only if there are active flags).

Examples​

Service.GetResources example​

http://192.168.33.1/rpc/Service.GetResources?id=0

Response

{
  "etag": "bb7083b2d6d1c4647a89ea441da69fac",
  "vc": {
    "anti_freeze": "boolean:200",
    "current_humidity": "number:200",
    "current_temperature": "number:201",
    "enable": "boolean:201",
    "fan_speed": "enum:200",
    "target_humidity": "number:202",
    "target_temperature": "number:203",
    "working_mode": "enum:201"
  }
}

Service.GetInfo example​

http://192.168.33.1/rpc/Service.GetInfo?id=0

Response

{
  "type": "simple-water-valve-controller",
  "ver": "1-dev141902",
  "build_id": "20251009-103105/6997087",
  "etag": "a65f22cee777aefc3284442124a98b72",
  "meta": {
    "ui": {
      "actions": [
        {
          "component": "open",
          "name": "Open valve",
          "method": "trigger",
          "params": {
            "event": "single_push"
          }
        },
        {
          "component": "close",
          "name": "Close valve",
          "method": "trigger",
          "params": {
            "event": "single_push"
          }
        },
        {
          "component": "position",
          "name": "Set position",
          "method": "set",
          "input": {
            "value": {
              "type": "number",
              "name": "Position",
              "min": 0,
              "max": 100,
              "step": 10
            }
          }
        }
      ],
      "conditions": {
        "position": [
          {
            "name": "Position changes",
            "event": "number.change"
          }
        ],
        "has_power": [
          {
            "name": "Power supply status",
            "event": "boolean.change"
          }
        ]
      }
    }
  }
}

Service.GetConfig example​

http://192.168.33.1/rpc/Service.GetConfig?id=0

Response

{
  "temp_offset": 1,
  "humidity_offset": 0,
  "temp_unit": "C",
  "thermostat_mode": "auto",
  "ext_sensor": {
    "enable": true,
    "ext_sens_type": "wifi",
    "on_timeout": "use_internal",
    "temperature_keys": [],
    "humidity_keys": [],
    "timeout": 1
  },
  "ws_rev": 7,
  "id": 0
}

Service.SetConfig example​

http://192.168.33.1/rpc/Service.SetConfig?id=0&config={"name":"Water valve"}

Response

{
  "restart_required": false
}

Service.GetStatus example​

http://192.168.33.1/rpc/Service.GetStatus?id=0

Response

{
  "etag": "bb7083b2d6d1c4647a89ea441da69fac",
  "state": "running",
  "stats": {
    "mem": 1479,
    "mem_peak": 1710
  },
  "errors": [
    "TEMP_USE_INTERNAL",
    "TIMEOUT_END"
  ]
}

Actions​

Actions specify which states of a Service’s Virtual Components can be controlled programmatically (via schedules or webhooks). Virtual Components represent real device features that the Service exposes for interaction.

Each action specifies:

  • component – target feature (e.g., thermostat enable).
  • name – human-readable label.
  • method – RPC method to execute (e.g., Set).
  • input – expected data type and UI widget (toggle, slider, text).

Example:

{
  "component": "target_temperature",
  "name": "Set target temperature",
  "method": "Set",
  "input": {
    "value": {
      "type": "number",
      "name": "temperature",
      "min": 5,
      "max": 95
    }
  }
}

In this example, the thermostat's target temperature can be adjusted.

Conditions​

Conditions define events that can trigger webhooks.
They describe when a webhook should be triggered.

Each condition includes:

  • name – description of the event.
  • event – event type (e.g., boolean.change).

Example:

{
  "current_temperature": [
    {
      "name": "Current temperature change",
      "event": "number.change"
    }
  ]
}

This condition means that when the "current_temperature" Virtual Component changes (the thermostat’s current temperature is updated), it can trigger linked webhooks.

Object.SetConfig example​

http://192.168.33.1/rpc/Object.SetConfig?id=200&config={"name":"Irrigation Controller"}

Response

{
  "restart_required": false
}

Object.GetConfig example​

http://192.168.33.1/rpc/Object.GetConfig?id=200

Response

{
  "id": 200,
  "name": "Irrigation Controller",
  "meta": null,
  "owner": "service:0",
  "access": "crw"
}

Object.GetStatus example​

http://192.168.33.1/rpc/Object.GetStatus?id=200

Response

{
  "value": {
    "zone0": {
      "duration": 15,
      "started_at": 1761221505,
      "source": "rpc"
    },
    "zone1": {
      "duration": 5,
      "started_at": 1761221506,
      "source": "init"
    },
    "zone2": {
      "duration": 10,
      "started_at": 1761221507,
      "source": "init"
    }
  },
  "source": "rpc",
  "last_update_ts": 1761289589
}

Object.Set example​

http://192.168.33.1/rpc/Object.Set?id=200&value={"zone0":{"duration":15,"started_at":1761221505,"source":"rpc"},"zone1":{"duration":5,"started_at":1761221506,"source":"init"},"zone2":{"duration":10,"started_at":1761221507,"source":"init"}}

Response

null