API Documentation - End-User RESTful API

Action Groups

An action group is composed of one or more actions. Each action is related to a single setup device (designate...d by its device URL) and is composed of one or more commands to be executed on that device.
Read more

Expand commands

POST

Action group

/actionGroups

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a managed action group label",
  "metadata" : "some metadata",
  "shortcut" : true,
  "notificationTypeMask" : 1,
  "notificationCondition" : "ON_SUCCESS",
  "notificationText" : "a notification text",
  "notificationTitle" : "a notification title",
  "targetEmailAddresses" : [ "some target email addresses" ],
  "targetPhoneNumbers" : [ "some target phone numbers" ],
  "targetPushSubscriptions" : [ "some target push subscriptions" ],
  "actions" : [ {
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
    "commands" : [ {
      "type" : 1,
      "name" : "a command name",
      "parameters" : [ "some parameters" ],
      "sensitiveParametersIndexes" : [ 1 ],
      "authentication" : "an authentication",
      "delay" : 1,
      "lockLevel" : 5
    } ]
  } ]
}

The new action group to create

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "actionGroupOID" : "string value" }

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

ActionGroupCreatedEvent
Field name	Field description
Description	An action group has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "actionGroupOID" : "an action group OID", "actionGroupLabel" : "an action group label", "metadata" : "some metadata", "notificationCondition" : "a notification condition", "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "name" : "an execution command entry name", "delay" : 1, "parameters" : [ { "type" : 1, "value" : "an execution command parameter entry value" } ] } ] } ], "type" : "ActionGroupCreatedEvent" }
actionGroupLabel	Action group label
actionGroupOID	Action group OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

Action group

/actionGroups

application/json

Parameters

Type

Name

Value

Description

Request Parameter

preventLockLevelReset

false

(Optional)

Do not reset command lock levels

Request Body

(JSON)

{
  "label" : "a managed action group label",
  "metadata" : "some metadata",
  "shortcut" : true,
  "notificationTypeMask" : 1,
  "notificationCondition" : "ON_SUCCESS",
  "notificationText" : "a notification text",
  "notificationTitle" : "a notification title",
  "targetEmailAddresses" : [ "some target email addresses" ],
  "targetPhoneNumbers" : [ "some target phone numbers" ],
  "targetPushSubscriptions" : [ "some target push subscriptions" ],
  "actions" : [ {
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
    "commands" : [ {
      "type" : 1,
      "name" : "a command name",
      "parameters" : [ "some parameters" ],
      "sensitiveParametersIndexes" : [ 1 ],
      "authentication" : "an authentication",
      "delay" : 1,
      "lockLevel" : 5
    } ]
  } ],
  "oid" : "the managed action group UUID"
}

An action group definition, containing the OID of the target action group to update

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ActionGroupUpdatedEvent
Field name	Field description
Description	An action group has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "actionGroupOID" : "an action group OID", "actionGroupLabel" : "an action group label", "metadata" : "some metadata", "notificationCondition" : "a notification condition", "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "name" : "an execution command entry name", "delay" : 1, "parameters" : [ { "type" : 1, "value" : "an execution command parameter entry value" } ] } ] } ], "type" : "ActionGroupUpdatedEvent" }
actionGroupLabel	Action group label
actionGroupOID	Action group OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Action group

/actionGroups/{oid}

application/json

DELETE Action group /actionGroups/{oid} application/json

Delete an action group by OID

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	oid	"string value"	Action group OID to delete

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ActionGroupDeletedEvent
Field name	Field description
Description	An action group has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "actionGroupOID" : "an action group OID", "type" : "ActionGroupDeletedEvent" }
actionGroupOID	Action group OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Action groups

/actionGroups

application/json

Action Groups Execution

Expand commands

POST

Action group execution

/exec/{actionGroupOID}

application/json

Parameters
Type	Name	Value	Description
Path Variable	actionGroupOID	"string value"	Action group OID to execute

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Action group execution

/exec/{actionGroupOID}/geolocated

application/json

Parameters
Type	Name	Value	Description
Path Variable	actionGroupOID	"string value"	Action group OID to execute

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

POST

Action group execution

/exec/{actionGroupOID}/internal

application/json

Parameters
Type	Name	Value	Description
Path Variable	actionGroupOID	"string value"	Action group OID to execute

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DELETE Current execution /exec/current/setup/{execId} application/json

Cancel a running setup-level execution

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	execId	"string value"	Execution ID to cancel

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

GET

Current execution

/exec/current/{execId}

application/json

Parameters
Type	Name	Value	Description
Path Variable	execId	"string value"	Execution ID to get

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "startTime" : 2,
  "owner" : "an owner",
  "actionGroup" : {
    "creationTime" : 1785140822212,
    "lastUpdateTime" : 1785140822213,
    "label" : "a managed action group label",
    "metadata" : "some metadata",
    "shortcut" : true,
    "notificationTypeMask" : 1,
    "notificationCondition" : "ON_SUCCESS",
    "notificationText" : "a notification text",
    "notificationTitle" : "a notification title",
    "targetEmailAddresses" : [ "some target email addresses" ],
    "targetPhoneNumbers" : [ "some target phone numbers" ],
    "targetPushSubscriptions" : [ "some target push subscriptions" ],
    "actions" : [ {
      "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
      "commands" : [ {
        "type" : 1,
        "name" : "a command name",
        "parameters" : [ "some parameters" ],
        "sensitiveParametersIndexes" : [ 1 ],
        "authentication" : "an authentication",
        "delay" : 1,
        "lockLevel" : 5
      } ]
    } ],
    "oid" : "the managed action group UUID"
  },
  "description" : "Execution : a managed action group label",
  "id" : "an exec id",
  "state" : "COMPLETED",
  "executionType" : "Immediate execution",
  "executionSubType" : "MANUAL_CONTROL"
}

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

DELETE Current execution [DEPRECATED] since version 2018.3.3 /exec/current/{execId} application/json

Cancel a running execution

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	execId	"string value"	Execution ID to cancel

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

GET

Current executions

/exec/current

application/json

DELETE Current executions [DEPRECATED] since version 2018.3.3 /exec/current application/json

Cancel all running executions

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

DELETE Current executions /exec/current/setup application/json

Cancel all running setup-level executions

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

GET

Current executions

/exec/internalCurrent

application/json

DELETE

Current technical execution [DEPRECATED] since version 2018.3.3

/exec/current/gateway/{gatewayId}/{execId}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	ID of the gateway running the execution
Path Variable	execId	"string value"	Execution ID to cancel

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

DELETE Current technical executions [DEPRECATED] since version 2018.3.3 /exec/current/gateway/{gatewayId} application/json

Cancel all running gateway-level executions. DEPRECATED : all executions started through the API are now attached to setup level

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	ID of the gateway running the execution

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

GET

Delayed trigger schedule execution

/exec/delayedTriggerSchedule/{triggerId}

application/json

DELETE Delayed trigger schedule execution /exec/delayedTriggerSchedule/{triggerId} application/json

Cancel a delayed trigger

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	triggerId	"string value"	Trigger id

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

DelayedTriggerCancelledEvent
Field name	Field description
Description	A delayed trigger has been cancelled
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "triggerId" : "a trigger id", "type" : "DelayedTriggerCancelledEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
triggerId	Trigger id

GET

Delayed trigger schedule executions

/exec/delayedTriggerSchedule

application/json

POST

Execute action group

/exec/apply

application/json

Parameters

Type

Name

Value

Description

Request Parameter

optimizeWithProtocolGroups

false

(Optional)

Optimize execution: replace individual devices sharing the same command (name + parameters) by matching existing protocol groups to improve execution speed

Request Body

(JSON)

{
  "label" : "a managed action group label",
  "metadata" : "some metadata",
  "shortcut" : true,
  "notificationTypeMask" : 1,
  "notificationCondition" : "ON_SUCCESS",
  "notificationText" : "a notification text",
  "notificationTitle" : "a notification title",
  "targetEmailAddresses" : [ "some target email addresses" ],
  "targetPhoneNumbers" : [ "some target phone numbers" ],
  "targetPushSubscriptions" : [ "some target push subscriptions" ],
  "actions" : [ {
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
    "commands" : [ {
      "type" : 1,
      "name" : "a command name",
      "parameters" : [ "some parameters" ],
      "sensitiveParametersIndexes" : [ 1 ],
      "authentication" : "an authentication",
      "delay" : 1,
      "lockLevel" : 5
    } ]
  } ]
}

Json description of the action group to execute

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Execute action group

/exec/apply/geolocated

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a managed action group label",
  "metadata" : "some metadata",
  "shortcut" : true,
  "notificationTypeMask" : 1,
  "notificationCondition" : "ON_SUCCESS",
  "notificationText" : "a notification text",
  "notificationTitle" : "a notification title",
  "targetEmailAddresses" : [ "some target email addresses" ],
  "targetPhoneNumbers" : [ "some target phone numbers" ],
  "targetPushSubscriptions" : [ "some target push subscriptions" ],
  "actions" : [ {
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
    "commands" : [ {
      "type" : 1,
      "name" : "a command name",
      "parameters" : [ "some parameters" ],
      "sensitiveParametersIndexes" : [ 1 ],
      "authentication" : "an authentication",
      "delay" : 1,
      "lockLevel" : 5
    } ]
  } ]
}

Json description of the action group to execute

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Execute action group

/exec/apply/highPriority

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a managed action group label",
  "metadata" : "some metadata",
  "shortcut" : true,
  "notificationTypeMask" : 1,
  "notificationCondition" : "ON_SUCCESS",
  "notificationText" : "a notification text",
  "notificationTitle" : "a notification title",
  "targetEmailAddresses" : [ "some target email addresses" ],
  "targetPhoneNumbers" : [ "some target phone numbers" ],
  "targetPushSubscriptions" : [ "some target push subscriptions" ],
  "actions" : [ {
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
    "commands" : [ {
      "type" : 1,
      "name" : "a command name",
      "parameters" : [ "some parameters" ],
      "sensitiveParametersIndexes" : [ 1 ],
      "authentication" : "an authentication",
      "delay" : 1,
      "lockLevel" : 5
    } ]
  } ]
}

Json description of the action group to execute

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Execute action group

/exec/apply/internal

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a managed action group label",
  "metadata" : "some metadata",
  "shortcut" : true,
  "notificationTypeMask" : 1,
  "notificationCondition" : "ON_SUCCESS",
  "notificationText" : "a notification text",
  "notificationTitle" : "a notification title",
  "targetEmailAddresses" : [ "some target email addresses" ],
  "targetPhoneNumbers" : [ "some target phone numbers" ],
  "targetPushSubscriptions" : [ "some target push subscriptions" ],
  "actions" : [ {
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
    "commands" : [ {
      "type" : 1,
      "name" : "a command name",
      "parameters" : [ "some parameters" ],
      "sensitiveParametersIndexes" : [ 1 ],
      "authentication" : "an authentication",
      "delay" : 1,
      "lockLevel" : 5
    } ]
  } ]
}

Json description of the action group to execute

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Optimize action group

/exec/optimizeWithProtocolGroups

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a managed action group label",
  "metadata" : "some metadata",
  "shortcut" : true,
  "notificationTypeMask" : 1,
  "notificationCondition" : "ON_SUCCESS",
  "notificationText" : "a notification text",
  "notificationTitle" : "a notification title",
  "targetEmailAddresses" : [ "some target email addresses" ],
  "targetPhoneNumbers" : [ "some target phone numbers" ],
  "targetPushSubscriptions" : [ "some target push subscriptions" ],
  "actions" : [ {
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
    "commands" : [ {
      "type" : 1,
      "name" : "a command name",
      "parameters" : [ "some parameters" ],
      "sensitiveParametersIndexes" : [ 1 ],
      "authentication" : "an authentication",
      "delay" : 1,
      "lockLevel" : 5
    } ]
  } ]
}

Json description of the action group to optimize

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1785140822216,
  "lastUpdateTime" : 1785140822216,
  "label" : "a managed action group label",
  "metadata" : "some metadata",
  "shortcut" : true,
  "notificationTypeMask" : 1,
  "notificationCondition" : "ON_SUCCESS",
  "notificationText" : "a notification text",
  "notificationTitle" : "a notification title",
  "targetEmailAddresses" : [ "some target email addresses" ],
  "targetPhoneNumbers" : [ "some target phone numbers" ],
  "targetPushSubscriptions" : [ "some target push subscriptions" ],
  "actions" : [ {
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
    "commands" : [ {
      "type" : 1,
      "name" : "a command name",
      "parameters" : [ "some parameters" ],
      "sensitiveParametersIndexes" : [ 1 ],
      "authentication" : "an authentication",
      "delay" : 1,
      "lockLevel" : 5
    } ]
  } ],
  "oid" : "the managed action group UUID"
}

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

GET

Schedule execution

/exec/schedule/{actionGroupOID}

application/json

POST

Schedule execution

/exec/schedule/{actionGroupOID}/{utcTimestamp}

application/json

Parameters
Type	Name	Value	Description
Path Variable	actionGroupOID	"string value"	Action group OID
Path Variable	utcTimestamp	120123456790	Date at which the action group should be launched

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "triggerId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DelayedTriggerSetEvent
Field name	Field description
Description	A new delayed trigger has been scheduled
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "triggerId" : "a trigger id", "type" : "DelayedTriggerSetEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
triggerId	Trigger id

GroupTriggeredEvent
Field name	Field description
Description	An action group has been triggered and is currently in execution
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "triggerId" : "a trigger id", "triggerType" : "a trigger type", "actionGroupOID" : "an action group OID", "execId" : "an exec id", "type" : "GroupTriggeredEvent" }
actionGroupOID	OID of the started action group
execId	Execution id
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
triggerId	Trigger id
triggerType	Trigger type

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Schedule executions

/exec/schedule

application/json

Authentication

Expand commands

GET

Authorization

/oauth2/applications/authorized

application/json

DELETE

Authorization

/oauth2/applications/authorized/{clientId}

application/json

PUT

Authorization

/oauth2/applications/authorized/{clientId}/disable

application/json

PUT

Authorization

/oauth2/applications/authorized/{clientId}/enable

application/json

GET

Authorization

/oauth2/authorization

application/json

Parameters
Type	Name	Value	Description
Request Parameter	setupOIDs	[ "string value" ]	(Optional) target setup OIDs (can be a single comma separated list parameter)
Request Parameter	response_type	"string value"	oauth2 response type
Request Parameter	client_id	"string value"	oauth2 client ID
Request Parameter	redirect_uri	"string value"	oauth2 redirect uri
Request Parameter	scope	"string value"	oauth2 authorization scope
Request Parameter	state	"string value"	(Optional) oauth2 state reference
Request Parameter	code_challenge	"string value"	(Optional) oauth2 PKCE code challenge
Request Parameter	code_challenge_method	"string value"	(Optional) oauth2 PKCE code challenge method (plain or S256)

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "state" : "a state", "code" : "a code", "error" : "an error", "url" : "a url" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Condition Groups

A condition group is composed of one or more conditions.

Expand commands

POST

Condition group

/conditionGroups

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a condition group label",
  "metadata" : "some metadata",
  "conditions" : [ {
    "controllable" : {
      "stateName" : "a state name",
      "value" : "a controllable condition value",
      "operator" : "GREATERTHAN",
      "controllableNames" : [ "some controllable names" ]
    }
  } ]
}

The new condition group to create

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "conditionGroupOID" : "string value" }

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

ConditionGroupCreatedEvent
Field name	Field description
Description	A condition group has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "conditionGroupOID" : "a condition group OID", "label" : "a condition group created event label", "metadata" : "some metadata", "conditions" : [ { "controllable" : { "stateName" : "a state name", "value" : "a controllable condition value", "operator" : "GREATERTHAN", "controllableNames" : [ "some controllable names" ] } } ], "type" : "ConditionGroupCreatedEvent" }
conditionGroupOID	Condition group OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT Condition group /conditionGroups application/json

Update a condition group

Access scope : enduser/*

> Test operation

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a condition group label",
  "metadata" : "some metadata",
  "conditions" : [ {
    "controllable" : {
      "stateName" : "a state name",
      "value" : "a controllable condition value",
      "operator" : "GREATERTHAN",
      "controllableNames" : [ "some controllable names" ]
    }
  } ],
  "oid" : "the condition group UUID"
}

A condition group definition, containing the OID of the target condition group to update

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ConditionGroupUpdatedEvent
Field name	Field description
Description	A condition group has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "conditionGroupOID" : "a condition group OID", "label" : "a condition group updated event label", "metadata" : "some metadata", "conditions" : [ { "controllable" : { "stateName" : "a state name", "value" : "a controllable condition value", "operator" : "GREATERTHAN", "controllableNames" : [ "some controllable names" ] } } ], "type" : "ConditionGroupUpdatedEvent" }
conditionGroupOID	Condition group OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Condition group

/conditionGroups/{oid}

application/json

DELETE Condition group /conditionGroups/{oid} application/json

Delete a condition group by OID

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	oid	"string value"	Condition group OID to delete

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

ConditionGroupDeletedEvent
Field name	Field description
Description	A condition group has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "conditionGroupOID" : "a condition group OID", "type" : "ConditionGroupDeletedEvent" }
conditionGroupOID	Condition group OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Condition group

/conditionGroups/{oid}/evaluate

application/json

GET

Condition groups

/conditionGroups

application/json

Configuration

Expand commands

August protocol

Private tags : [ august-config ]

Expand commands

POST

August create authentication URL

/config/august/createAuthenticationURL/{redirectURL}

application/json

POST August gateways candidates /config/august/discoverGatewaysCandidates application/json

Return the list of the gateways candidates

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

AugustDiscoverHousesCandidatesFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "AugustDiscoverHousesCandidatesFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

AugustDiscoverHousesCandidatesCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "houses" : [ { "id" : "an id", "name" : "an august house candidate name", "locks" : [ { "id" : "an id", "name" : "an august lock candidate name" } ] } ], "type" : "AugustDiscoverHousesCandidatesCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT Authentication /config/august/tokens application/json

Refresh current access token if necessary

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

AugustRefreshCurrentTokenFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "AugustRefreshCurrentTokenFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

AugustRefreshCurrentTokenCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "AugustRefreshCurrentTokenCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Configuration /config/august/discoverGateway/{houseId} application/json

Start a discover August gateway

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	houseId	"string value"	August house Id

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

AugustGatewayDiscoverCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "type" : "AugustGatewayDiscoverCompletedEvent" }
gatewayId	gateway Id
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

AugustGatewayDiscoverFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "type" : "AugustGatewayDiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Configuration /config/august/gateways/{gatewayId}/discoverDevices application/json

Start discover August devices

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	August gatewayId

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverCompleteEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

Camera

Private tags : [ camera-config ]

Expand commands

POST

Camera

/config/{gatewayId}/camera/discover/{rootUser}/{rootPassword}

application/json

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "gatewayId" : "a gateway id", "name" : "a discovered camera name", "description" : "a description", "deviceAddress" : "a device address", "cameraIpOrFqdn" : "a camera ip or fqdn", "type" : 1, "lockType" : 1, "wifiEnabled" : false, "locked" : true }	Json description of the camera to pair
Path Variable	rootUser	"string value"	Camera root user name (optional for Domis camera)
Path Variable	rootPassword	"string value"	Camera root user password (optional for Domis camera)
Path Variable	gatewayId	"string value"	Gateway id to which camera has to be paired

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

CameraDiscoveredEvent
Field name	Field description
Description	A new camera has been discovered
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "cameraId" : "a camera id", "type" : "CameraDiscoveredEvent" }
cameraId	Camera id
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DELETE

Camera

/config/{gatewayId}/camera/unused

application/json

POST

Camera

/config/{gatewayId}/camera/wifi/{deviceAddress}/{wifiProfile}/{wifiSSID}/{secretKey}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	Gateway id to which camera has to be paired
Path Variable	deviceAddress	"string value"	Camera device address
Path Variable	wifiProfile	"string value"	Wifi network profile. Supported values are: -> ?OPENRELAY? for Open-Relay -> ?WEP64OPN? for WEP 64 Bits Open Key -> ?WEP64SHRD? for WEP 64 Bits Shared Key -> ?WEP128OPN? for WEP 128 Bits Open Key -> ?WEP128SHRD? for WEP 128 Bits Shared Key -> ?WPA_WPA2? for WPA2-PSK
Path Variable	wifiSSID	"string value"	WIFI network SSID
Path Variable	secretKey	"string value"	WIFI network secret key. If key is in hex format, key should be prefixes by ?hex:?

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

GET

Camera candidates

/config/{gatewayId}/camera/candidates

application/json

Device Pairing Operations

In certain cases, devices have to be explicitly created or deleted from client application.

Expand commands

GET

Commissioning

/config/{gatewayId}/devices/{protocolType}/commissioning/codes

application/json

POST

Commissioning

/config/{gatewayId}/devices/{protocolType}/commissioning/codes

application/json

DELETE

Commissioning

/config/{gatewayId}/devices/{protocolType}/commissioning/codes

application/json

DELETE

Commissioning

/config/{gatewayId}/devices/{protocolType}/commissioning/codes/{code}

application/json

POST

Commissioning

/config/{gatewayId}/devices/{protocolType}/commissioning/import

application/json

GET

Commissioning

/config/{gatewayId}/devices/{protocolType}/commissioning/savedCodes

application/json

POST

Commissioning

/config/{gatewayId}/devices/{protocolType}/commissioning/savedCodes

application/json

DELETE

Commissioning

/config/{gatewayId}/devices/{protocolType}/commissioning/savedCodes

application/json

DELETE

Commissioning

/config/{gatewayId}/devices/{protocolType}/commissioning/savedCodes/{code}

application/json

POST

Device

/config/{gatewayId}/devices/{deviceAddress}/{protocolType}/{deviceType}/{deviceLabel}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	deviceAddress	"string value"	The device address (real type may differ depenging on the protocol type: String, Integer in base 10 or base 16, ...)
Path Variable	protocolType	1	The protocol type
Path Variable	deviceType	2	The device type
Path Variable	deviceLabel	"string value"	The device label

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Devices

/config/{gatewayId}/devices/{protocolType}/partial

application/json

DELETE

Devices

/config/{gatewayId}/devices/{protocolType}/partial

application/json

DELETE

Devices

/config/{gatewayId}/devices/{protocolType}/partial/{deviceAddress}

application/json

POST

Initialization

/config/{gatewayId}/devices/{protocolType}/init

application/json

Eliot protocol

Private tags : [ eliot-config ]

Expand commands

PUT Authentication /config/eliot/tokens application/json

Refresh current access token if necessary

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

EliotRefreshCurrentTokenCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "EliotRefreshCurrentTokenCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

EliotRefreshCurrentTokenFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "EliotRefreshCurrentTokenFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Configuration /config/eliot/discoverGateway/{gatewayId} application/json

Start a discover Eliot gateway

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	Eliot gateway Id

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

EliotDiscoverGatewayFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "EliotDiscoverGatewayFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

EliotDiscoverGatewayCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "type" : "EliotDiscoverGatewayCompletedEvent" }
gatewayId	Eliot gateway id
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Configuration /config/eliot/discoverGateways application/json

Send get a list of all user's gateways

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

EliotDiscoverGatewaysCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "plants" : [ { "id" : "an id", "name" : "an eliot plant name" } ], "type" : "EliotDiscoverGatewaysCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

EliotDiscoverGatewaysFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "EliotDiscoverGatewaysFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Configuration /config/eliot/gateways/{gatewayId}/discoverDevices application/json

Start discover Eliot devices

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	Eliot gatewayId

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverCompleteEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Eliot create authentication URL

/config/eliot/createAuthenticationURL/{redirectURL}

application/json

EnOcean protocol

Private tags : [ enocean-config ]

Expand commands

GET

Device address

/config/{gatewayId}/enocean/deviceAddress/{deviceType}

application/json

POST

Learning device procedure [DEPRECATED] since version 2018.3.4

/config/{gatewayId}/enocean/learn/start/{deviceRef}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	deviceRef	"string value"	The device reference

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

EnOceanLearnModeTimeoutEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "EnOceanLearnModeTimeoutEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

EnOceanLearnStartedEvent
Field name	Field description
Description	An EnOcean learn operation started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "EnOceanLearnStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

EnOceanBadDeviceStimulationEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "EnOceanBadDeviceStimulationEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

See Allowed Values

Device Reference
Name	Code	Meaning
EltakoSmokeSensor	EEP=0xF60201 subType=0x1	Eltako Smoke Sensor
RockerSwitchx1	EEP=0xF60201 subType=0x2	Rocker Switchx 1
RockerSwitchx2	EEP=0xF60201 subType=0x0	Rocker Switchx 2
RockerSwitchx4	EEP=0xF60301 subType=0x0	Rocker Switchx 4
RockerSwitchAutoManuUpDown	EEP=0xF60203 subType=0x0	Rocker Switch Auto Manu Up Down
NodOnCardSwitch	EEP=0xF60401 subType=0x1	Nod On Card Switch
AdvisenDHW	EEP=0xD20101 subType=0x1	Advisen DHW
EltakoContactSensor	EEP=0xF60401 subType=0x2	Eltako Contact Sensor

POST

Learning procedure [DEPRECATED] since version 2018.3.4

/config/{gatewayId}/enocean/learn/start

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Request Body	(JSON)	{ "enoceanEquipmentProfile" : 1, "subType" : 1 }	(Optional) Json description of the device to learn. Useful for devices using generic profiles (require a manual specification).

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

EnOceanLearnModeTimeoutEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "EnOceanLearnModeTimeoutEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

EnOceanLearnStartedEvent
Field name	Field description
Description	An EnOcean learn operation started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "EnOceanLearnStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

EnOceanBadDeviceStimulationEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "EnOceanBadDeviceStimulationEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

IO HomeControl protocol

Private tags : [ io-config ]

Expand commands

POST

Actuators

/config/{gatewayId}/io/setConfigState

application/json

POST

Atlantic

/config/{gatewayId}/io/atlantic/twinningExit/{deviceAddress}

application/json

POST

Controller

/config/{gatewayId}/io/controller/{controllerAddress}/sendSystemTable

application/json

POST

Device

/config/{gatewayId}/io/openDeviceInRCM/{deviceAddress}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	deviceAddress	"string value"	Device address

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

POST

Gas Pulse Sensor

/config/{gatewayId}/io/discover/sensors/pulse/gas/{deviceAddress}

application/json

POST

Generic Pulse Sensor

/config/{gatewayId}/io/discover/sensors/pulse/{category}/{scaleFactor}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	category	"string value"	Energy category
Path Variable	scaleFactor	0.12345	The scale factor

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

See Allowed Values

IO Energy Type
Name	Code	Meaning
ELECTRICITY	1	Electricity
GAS	2	Gas
OIL	3	Oil
WATER	4	Water
THERMAL_ENERGY	5	Thermal Energy

POST

Key

/config/{gatewayId}/io/propagateTransferKey

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Request Body	(JSON)	{ "saveMasterNode" : false, "propagate" : true }	(Optional) Transfert options

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

POST Key /config/{gatewayId}/io/revertToCurrentKey application/json

This operation allows to send the current IO security key

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

IOChangedKeyEvent
Field name	Field description
Description	IO key changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "IOChangedKeyEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
setupOID	Setup OID
siteOID	Site OID

POST

Key

/config/{gatewayId}/io/sendIOKeyToDevices

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Request Body	(JSON)	[ "string value" ]	Device adresses list

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

POST

Sensor

/config/{gatewayId}/io/discover/sensors/{sensorAddress}/unsubscribe

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	sensorAddress	"string value"	Sensor address

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

KNX Over OGP Protocol

Private tags : [ ogpknx-config ]

Expand commands

POST

KNX over OGP import

/config/{gatewayId}/ogp/knx/import

application/json

Modbus Protocol

Private tags : [ modbus-config ]

Expand commands

POST

Discover

/config/{gatewayId}/modbus/discover/{ovpGatewayAddress}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	ovpGatewayAddress	"string value"	The OVP gateway address

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverCompleteEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

POST

Discover modules

/config/{gatewayId}/modbus/discover/modules/{deviceAddress}

application/json

OGCP cloud protocol

Expand commands

POST

Create OAuth2 authorization URL

/config/ogcp/{cloudId}/oauth2/createAuthenticationURL

application/json

POST

Discover Device

/config/ogcp/{cloudId}/discover/device/{deviceId}

application/json

Parameters
Type	Name	Value	Description
Path Variable	cloudId	"string value"	The OGCP cloud ID
Path Variable	deviceId	"string value"	The device ID
Request Body	(JSON)	{ "commissioningKey" : "a commissioning key" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

OGCPDiscoverDeviceCompletedEvent
Field name	Field description
Description	A device discovery operation has successfully completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "deviceId" : "a device id", "type" : "OGCPDiscoverDeviceCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

OGCPDiscoverDeviceFailedEvent
Field name	Field description
Description	A device discovery operation has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "deviceId" : "a device id", "type" : "OGCPDiscoverDeviceFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Discover Site

/config/ogcp/{cloudId}/discover/sites/{siteId}

application/json

Parameters
Type	Name	Value	Description
Path Variable	cloudId	"string value"	The OGCP cloud ID
Path Variable	siteId	"string value"	The site ID

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

OGCPDiscoverSiteFailedEvent
Field name	Field description
Description	A device discovery operation has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "siteId" : "a site id", "type" : "OGCPDiscoverSiteFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

OGCPDiscoverSiteCompletedEvent
Field name	Field description
Description	A site discovery operation has successfully completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "siteId" : "a site id", "type" : "OGCPDiscoverSiteCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Discover Sites /config/ogcp/{cloudId}/discover/sites application/json

Start a discovery of available sites. Only works on clouds using site-level integration mode and supporting multi-sites per account.

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	cloudId	"string value"	The OGCP cloud ID

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

OGCPDiscoverSitesCompletedEvent
Field name	Field description
Description	A discovery operation of available sites has successfully completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "sites" : [ { "siteId" : "a site id", "label" : "a OGCPSite reference label" } ], "type" : "OGCPDiscoverSitesCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

OGCPDiscoverSitesFailedEvent
Field name	Field description
Description	A discovery operation of available sites has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "type" : "OGCPDiscoverSitesFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

List Instances

/config/ogcp/instances

application/json

POST

OAuth2 Password grant

/config/ogcp/{cloudId}/oauth2/passwordGrant

application/json

POST

Pair Device

/config/ogcp/{cloudId}/pairing/device/{deviceId}

application/json

Parameters
Type	Name	Value	Description
Path Variable	cloudId	"string value"	The OGCP cloud ID
Path Variable	deviceId	"string value"	The device ID
Request Body	(JSON)	{ "commissioningData" : { "a commissioning data" : "a commissioning data" } }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

OGCPDevicePairingCompletedEvent
Field name	Field description
Description	A device pairing operation has successfully completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "deviceId" : "a device id", "commissioningKey" : "a commissioning key", "productMetaData" : { "a product meta data" : "a product meta data" }, "deviceMetaData" : { "a device meta data" : "a device meta data" }, "type" : "OGCPDevicePairingCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

OGCPDevicePairingFailedEvent
Field name	Field description
Description	A device pairing operation has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "deviceId" : "a device id", "type" : "OGCPDevicePairingFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Pair Devices

/config/ogcp/{cloudId}/pairing/device

application/json

Parameters
Type	Name	Value	Description
Path Variable	cloudId	"string value"	The OGCP cloud ID
Request Body	(JSON)	{ "commissioningData" : { "a commissioning data" : "a commissioning data" } }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

OGCPDevicePairingFailedEvent
Field name	Field description
Description	A device pairing operation has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "deviceId" : "a device id", "type" : "OGCPDevicePairingFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

OGCPDevicePairingCompletedEvent
Field name	Field description
Description	A device pairing operation has successfully completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "deviceId" : "a device id", "commissioningKey" : "a commissioning key", "productMetaData" : { "a product meta data" : "a product meta data" }, "deviceMetaData" : { "a device meta data" : "a device meta data" }, "type" : "OGCPDevicePairingCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Refresh OAuth2 tokens. Only works on clouds using site-level integration mode /config/ogcp/{cloudId}/oauth2/tokens/refresh application/json

Refresh OAuth2 tokens if necessary

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	cloudId	"string value"	The OGCP cloud ID

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

OGCPTokensRefreshCompletedEvent
Field name	Field description
Description	OAuth2 tokens were successfully refreshed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "type" : "OGCPTokensRefreshCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

OGCPTokensRefreshFailedEvent
Field name	Field description
Description	OAuth2 tokens could not be refreshed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "cloudId" : "a cloud id", "type" : "OGCPTokensRefreshFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

OpenDoors protocol

Private tags : [ opendoors-config ]

Expand commands

POST Authentication /config/opendoors/tokens application/json

Generate OAuth2 tokens from credentials

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "username" : "a username", "password" : "a password", "applicationId" : "an application id" }

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

OpenDoorsGenerateOAuthTokensFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "OpenDoorsGenerateOAuthTokensFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

OpenDoorsGenerateOAuthTokensCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "OpenDoorsGenerateOAuthTokensCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Discover [DEPRECATED] since version 2019.1

/config/opendoors/discover

application/json

Parameters
Type	Name	Value	Description
Request Parameter	login	"string value"	The OpenDoors main account login
Request Parameter	password	"string value"	The OpenDoors main account password
Request Parameter	autoCreateDevices	false	(Optional) (Default: false) Parameter used to define discover behavior: if true, all supported OpenDoors devices available on the given account will be automatically created on the generated gateway
Request Parameter	withGuests	false	(Optional) (Default: true) Parameter used to define discover behavior: if false, only the OpenDoors devices for which the user it admin will be created

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

OpenDoorsDiscoverFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "userId" : "a user id", "type" : "OpenDoorsDiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
userId	User login

OpenDoorsDiscoverCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "candidates" : [ { "deviceLabel" : "a device label", "deviceAddress" : "a device address", "deviceType" : 2 } ], "type" : "OpenDoorsDiscoverCompletedEvent" }
candidates	List of user opendoors devices
gatewayId	User login
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Discover

/config/opendoors/discoverGateway

application/json

Parameters

Type

Name

Value

Description

Request Parameter

autoCreateDevices

false

(Optional) (Default: false)

Parameter used to define discover behavior: if true, all supported OpenDoors devices available on the given account will be automatically created on the generated gateway

Request Parameter

withGuests

false

(Optional) (Default: true)

Parameter used to define discover behavior: if false, only the OpenDoors devices for which the user it admin will be created

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

OpenDoorsDiscoverCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "candidates" : [ { "deviceLabel" : "a device label", "deviceAddress" : "a device address", "deviceType" : 2 } ], "type" : "OpenDoorsDiscoverCompletedEvent" }
candidates	List of user opendoors devices
gatewayId	User login
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

OpenDoorsDiscoverFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "userId" : "a user id", "type" : "OpenDoorsDiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
userId	User login

POST

Discover devices

/config/opendoors/{gatewayId}/discoverDevices

application/json

Parameters

Type

Name

Value

Description

Path Variable

gatewayId

"string value"

The gateway ID

Request Parameter

autoCreateDevices

false

(Optional) (Default: false)

Parameter used to define discover behavior: if true, all supported OpenDoors devices available on the given gateway will be automatically created

Request Parameter

withGuests

false

(Optional) (Default: true)

Parameter used to define discover behavior: if false, only the OpenDoors devices for which the user it admin will be created

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

OpenDoorsDiscoverCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "candidates" : [ { "deviceLabel" : "a device label", "deviceAddress" : "a device address", "deviceType" : 2 } ], "type" : "OpenDoorsDiscoverCompletedEvent" }
candidates	List of user opendoors devices
gatewayId	User login
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

OpenDoorsDiscoverFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "userId" : "a user id", "type" : "OpenDoorsDiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
userId	User login

POST

OpenDoors create authentication URL

/config/opendoors/createAuthenticationURL/{redirectURL}

application/json

Overkiz Protocol

Private tags : [ ovp-config ]

Expand commands

POST

Actuators

/config/{gatewayId}/ovp/discover

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

POST

Actuators

/config/{gatewayId}/ovp/discover/inSystem

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Actuators

/config/{gatewayId}/ovp/discover/simple

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

POST

Module

/config/{gatewayId}/ovp/discover/modbus/{gatewayAddress}/modules

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	gatewayAddress	"string value"	The modbus gateway address

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Sensor

/config/{gatewayId}/ovp/discover/sensors

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Sensor

/config/{gatewayId}/ovp/discover/sensors/simple

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

Philips HUE

Private tags : [ hue-config ]

Expand commands

PUT

Create HUE bridge user

/config/{gatewayId}/hue/bridge/{hueBridgeAddress}/createBridgeUser

application/json

POST

Discover HUE bridge

/config/{gatewayId}/hue/bridge/discover

application/json

POST

Discover HUE bridge configuration

/config/{gatewayId}/hue/bridge/{hueBridgeAddress}/discoverConfiguration

application/json

Profalux868 protocol

Private tags : [ profalux868-config ]

Expand commands

GET

Device Address

/config/{gatewayId}/profalux868/address

application/json

POST

Profalux868 pair

/config/{gatewayId}/profalux868/{deviceAddress}/pair

application/json

POST

Profalux868 unpair

/config/{gatewayId}/profalux868/{deviceAddress}/unpair

application/json

Protocol Group

A protocol group need to be explicitly created from client application.

Expand commands

GET

All protocol groups with their devices

/setup/protocols/groups

application/json

POST

Other

/config/{gatewayId}/{protocolType}/group

application/json

GET

Other

/config/{gatewayId}/{protocolType}/group/capabilities

application/json

GET

Protocol Group Devices

/config/{gatewayId}/{protocolType}/group/{groupAddress}/devices

application/json

RTD protocol

Private tags : [ rtd-config ]

Expand commands

GET

Device address

/config/{gatewayId}/rtd/deviceAddress

application/json

POST

Discover

/config/{gatewayId}/rtd/discover

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Key

/config/{gatewayId}/rtd/transferKey/{deviceAddress}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	deviceAddress	"string value"	The device address

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

RTS protocol

Private tags : [ rts-config ]

Expand commands

GET

Channel

/config/{gatewayId}/rts/channel

application/json

GET

Key

/config/{gatewayId}/rts/transferKey/{channel}/{type}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	channel	1	RTS device channel
Path Variable	type	1	RTS device category type: 0 for a up/down device, 1 for a 4-time device

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

Ramses protocol

Private tags : [ ramses-config ]

Expand commands

POST

Discover master nodes

/config/{gatewayId}/ramses/discover/gatewayNode/{gatewayAddress}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	gatewayAddress	"string value"	The Ramses gateway address

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverCompleteEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Discover master nodes

/config/{gatewayId}/ramses/discover/masterNodes/{evoHomeAddress}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	evoHomeAddress	"string value"	The EvoHome address (device ID)

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverCompleteEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

GET

Master destination address

/config/{gatewayId}/ramses/test/address/{evoHomeAddress}

application/json

GET

Test gateway destination address

/config/{gatewayId}/ramses/test/gateway/{gatewayAddress}

application/json

Somfy Thermostat protocol

Private tags : [ somfy-thermostat-config ]

Expand commands

POST Authentication /config/somfythermostat/tokens application/json

Generate OAuth2 tokens from credentials

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "username" : "a username", "password" : "a password", "applicationId" : "an application id" }

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

SomfyThermostatGenerateOAuthTokensCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyThermostatGenerateOAuthTokensCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyThermostatGenerateOAuthTokensFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyThermostatGenerateOAuthTokensFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT Authentication /config/somfythermostat/tokens application/json

Refresh current access token if necessary

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

SomfyThermostatCurrentTokensFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyThermostatCurrentTokensFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyThermostatCurrentTokensCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyThermostatCurrentTokensCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Discover Devices /config/somfythermostat/{gatewayId}/discoverDevices application/json

Start a SomfyThermostat discover devices procedure

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverCompleteEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Discover Gateways /config/somfythermostat/discoverGateways application/json

Start a discover gateways

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

SomfyThermostatDiscoverCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyThermostatDiscoverCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyThermostatDiscoverFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyThermostatDiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyThermostatDiscoveredEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "thermostatId" : "a thermostat id", "thermostatLabel" : "a thermostat label", "type" : "SomfyThermostatDiscoveredEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
thermostatId	thermostat ID
thermostatLabel	thermostat Label

POST Discover Gateways /config/somfythermostat/discoverGateways/{gatewayId} application/json

discover the gateway corresponding to the gatewayId

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway Id

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

SomfyThermostatDiscoveredEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "thermostatId" : "a thermostat id", "thermostatLabel" : "a thermostat label", "type" : "SomfyThermostatDiscoveredEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
thermostatId	thermostat ID
thermostatLabel	thermostat Label

SomfyThermostatDiscoverCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyThermostatDiscoverCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyThermostatDiscoverFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyThermostatDiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Discover Gateways Candidates /config/somfythermostat/discoverGatewaysCandidates application/json

discover gateways candidates

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

SomfyThermostatDiscoverCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyThermostatDiscoverCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyThermostatsCandidatesDiscoveredEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "candidates" : [ { "thermostatLabel" : "a thermostat label", "gatewayId" : "a gateway id", "thermostatId" : "a thermostat id" } ], "type" : "SomfyThermostatsCandidatesDiscoveredEvent" }
candidates	List of thermostat Gateway
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyThermostatDiscoverFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyThermostatDiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Somfy thermostat create authentication URL

/config/somfythermostat/createAuthenticationURL/{redirectURL}

application/json

POST

Webhooks

/config/somfythermostat/{gatewayId}/webhook/{thermostatId}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	thermostatId	"string value"	The thermostat Id

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

SomfyThermostatRegisterWebhookSuccessEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "SomfyThermostatRegisterWebhookSuccessEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyThermostatRegisterWebhookFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "SomfyThermostatRegisterWebhookFailedEvent", "failureType" : "NON_EXECUTING" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DELETE

Webhooks

/config/somfythermostat/{gatewayId}/webhook/{thermostatId}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	thermostatId	"string value"	The thermostat Id

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

SomfyThermostatDeleteWebhookFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "SomfyThermostatDeleteWebhookFailedEvent", "failureType" : "NON_EXECUTING" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyThermostatDeleteWebhookSuccessEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "webhookId" : 1, "type" : "SomfyThermostatDeleteWebhookSuccessEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
webhookId	Webhook id

SomfyProtect protocol

Private tags : [ somfyprotect-config ]

Expand commands

POST Authentication /config/somfyprotect/tokens application/json

Generate OAuth2 tokens from credentials

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "username" : "a username", "password" : "a password", "applicationId" : "an application id" }

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

SomfyProtectGenerateOAuthTokensFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyProtectGenerateOAuthTokensFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyProtectGenerateOAuthTokensCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyProtectGenerateOAuthTokensCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT Authentication /config/somfyprotect/tokens application/json

Refresh current access token if necessary

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

SomfyProtectCurrentTokenFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyProtectCurrentTokenFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyProtectCurrentTokenCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "accessToken" : "an access token", "refreshToken" : "a refresh token", "type" : "SomfyProtectCurrentTokenCompletedEvent" }
accessToken	Access token
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
refreshToken	Refresh token
setupOID	Setup OID
siteOID	Site OID

POST Discover Devices /config/somfyprotect/{gatewayId}/discoverDevices application/json

Start a SomfyProtect discover devices procedure

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "type" : "DiscoverCompleteEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type
ref	Reference
setupOID	Setup OID
siteOID	Site OID

POST Discover Gateway /config/somfyprotect/discoverGateway application/json

Start a discover of the gateway with the siteID

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Parameter	siteId	"string value"	Somfy protect site Id

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

SomfyProtectDiscoverCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyProtectDiscoverCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyProtectDiscoverFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyProtectDiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Discover Gateways [DEPRECATED] since version 2018.7 /config/somfyprotect/discoverGateways application/json

Start a discover gateways @Deprecated: use discoverGatewaysCandidates and discoverGateway to discover a gateway

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "withGuests" : false }	(Optional)

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

SomfyProtectDiscoverFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyProtectDiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyProtectSiteDiscoveredEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "siteId" : "a site id", "siteLabel" : "a site label", "type" : "SomfyProtectSiteDiscoveredEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteId	Site ID
siteLabel	Site Label
siteOID	Site OID

SomfyProtectDiscoverCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyProtectDiscoverCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Somfy protect discover gateways candidates /config/somfyprotect/discoverGatewaysCandidates application/json

Discover gateways candidates

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "withGuests" : false }	(Optional)

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

SomfyProtectGetSitesCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "sites" : [ { "siteId" : "a site id", "securityLevel" : "a security level", "diagnosisStatus" : "some diagnosis status", "diagnosisMessage" : "a diagnosis message", "diagnosis" : { "mainStatus" : "some main status", "mainMessage" : "a main message" }, "profiles" : [ { "type" : "a somfy protect profile type", "enabled" : true } ], "shutterAutomaticEnabled" : false, "label" : "a somfy protect site label" } ], "type" : "SomfyProtectGetSitesCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyProtectGetSitesFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyProtectGetSitesFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Somfy protect send get sites [DEPRECATED] since version 2018.7 /config/somfyprotect/sendGetSites application/json

Send get sites @Deprecated: use discoverGatewaysCandidates

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "withGuests" : false }	(Optional)

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

SomfyProtectGetSitesCompletedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "sites" : [ { "siteId" : "a site id", "securityLevel" : "a security level", "diagnosisStatus" : "some diagnosis status", "diagnosisMessage" : "a diagnosis message", "diagnosis" : { "mainStatus" : "some main status", "mainMessage" : "a main message" }, "profiles" : [ { "type" : "a somfy protect profile type", "enabled" : true } ], "shutterAutomaticEnabled" : false, "label" : "a somfy protect site label" } ], "type" : "SomfyProtectGetSitesCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SomfyProtectGetSitesFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "SomfyProtectGetSitesFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

SomfyProtect create authentication URL

/config/somfyprotect/createAuthenticationURL/{redirectUrl}

application/json

Wiser protocol

Private tags : [ wiser-config ]

Expand commands

POST

discover devices

/config/wiser/gateway/{gatewayId}/discoverDevices

application/json

POST

wiser create authentication URL

/config/wiser/createAuthenticationURL/{redirectURL}

application/json

POST wiser gateways /config/wiser/discoverGateway/{siteId} application/json

discover a site by id

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	siteId	"string value"	site Id to discover

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

WiserGatewayDiscoveredEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "label" : "a wiser gateway discovered event label", "type" : "WiserGatewayDiscoveredEvent" }
gatewayId	gateway Id
label	label
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

WiserGatewayDiscoveredFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "type" : "WiserGatewayDiscoveredFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST wiser gateways candidates /config/wiser/discoverGatewaysCandidates application/json

Return the list of the gateways candidates

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

WiserSitesCandidatesDiscoveredEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "candidates" : [ { "id" : "an id", "name" : "a wiser site name" } ], "type" : "WiserSitesCandidatesDiscoveredEvent" }
candidates	List of Wiser sites candidates
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

WiserSitesCandidatesFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "WiserSitesCandidatesFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

Z-Wave protocol

Private tags : [ zwave-config ]

Expand commands

POST

Refresh association group

/config/{gatewayId}/zwave/association/nodes/{nodeId}/groups/{groupId}/refresh

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	nodeId	1	The target node whose association group will be refreshed
Path Variable	groupId	1	The target groupId to refresh

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

POST

Refresh association groups

/config/{gatewayId}/zwave/association/nodes/{nodeId}/groups/refresh

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	nodeId	1	The target node whose association groups will be refreshed

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

POST Reset procedure /config/{gatewayId}/zwave/reset application/json

Start a Z-Wave reset procedure.

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ZWaveResetCompleteEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZWaveResetCompleteEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ZWaveResetFailedEvent
Field name	Field description
Description
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZWaveResetFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceDisabledEvent
Field name	Field description
Description	Device is disabled
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "DeviceDisabledEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Retrieve association group

/config/{gatewayId}/zwave/association/nodes/{nodeId}/groups/{groupId}

application/json

GET

Retrieve association groups

/config/{gatewayId}/zwave/association/nodes/{nodeId}/groups

application/json

POST

Set association group

/config/{gatewayId}/zwave/association/nodes/{nodeId}/groups/{groupId}

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	nodeId	1	The target node whose association group will be set
Path Variable	groupId	1	The target groupId to set
Request Body	(JSON)	[ 2 ]	The association group definition to set

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "executionType" : 1, "subType" : 1, "oldState" : "TRANSMITTED", "timeToNextState" : 2, "failedCommands" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "detailedStatus" : { "type" : "generic-error", "message" : "a message", "error" : true }, "rank" : 1, "failureType" : "NON_EXECUTING" } ], "relatedDevices" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ], "technical" : false, "failureTypeCode" : 11, "type" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
executionType	Execution type
failedCommands	List of failed commands
failureType	Failure type
newState	Execution new state
oldState	Execution previous state
ownerKey	Execution owner key
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
relatedDevices	List of devices involved in this execution
setupOID	Setup OID
siteOID	Site OID
subType	Execution sub type
timeToNextState	Remaining time until next execution state

Zigbee protocol

Private tags : [ zigbee-config ]

Expand commands

POST

BindNetwork

/config/{gatewayId}/zigbee/bindNetwork

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ZigbeeBindNetworkCompletedEvent
Field name	Field description
Description	When zigbee network is bound
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeBindNetworkCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ZigbeeBindNetworkFailedEvent
Field name	Field description
Description	When zigbee network cannot be bound
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeBindNetworkFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceUpdatedEvent
Field name	Field description
Description	Device has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "type" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

CreateNetwork

/config/{gatewayId}/zigbee/createNetwork

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ZigbeeCreateNetworkCompletedEvent
Field name	Field description
Description	The new Zigbee network has been successfully created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeCreateNetworkCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ZigbeeCreateNetworkFailedEvent
Field name	Field description
Description	An error occurred while creating the new Zigbee network
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeCreateNetworkFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

CreateNetwork with channels

/config/{gatewayId}/zigbee/createNetwork/channels

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Request Body	(JSON)	[ 1 ]	List of channel possible for creating network

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ZigbeeCreateNetworkFailedEvent
Field name	Field description
Description	An error occurred while creating the new Zigbee network
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeCreateNetworkFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ZigbeeCreateNetworkCompletedEvent
Field name	Field description
Description	The new Zigbee network has been successfully created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeCreateNetworkCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

JoinNetwork

/config/{gatewayId}/zigbee/joinNetwork

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ZigbeeJoinNetworkCompletedEvent
Field name	Field description
Description	When zigbee network is joined
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeJoinNetworkCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ZigbeeJoinNetworkFailedEvent
Field name	Field description
Description	When zigbee network cannot be joined
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeJoinNetworkFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

LeaveNetwork

/config/{gatewayId}/zigbee/leaveNetwork

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ZigbeeLeaveNetworkCompletedEvent
Field name	Field description
Description	When zigbee network is left
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeLeaveNetworkCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceRemovedEvent
Field name	Field description
Description	A device has been removed from the gateway
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "type" : "DeviceRemovedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ZigbeeLeaveNetworkFailedEvent
Field name	Field description
Description	When zigbee network cannot be left
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeLeaveNetworkFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

RefreshNetwork

/config/{gatewayId}/zigbee/refreshNetwork

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device created event label", "placeOID" : "a place OID", "metadata" : "some metadata", "deviceAttributes" : [ { "name" : "a device attribute change item name", "type" : 1, "value" : "a device attribute change item value" } ], "type" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ZigbeeRefreshNetworkCompletedEvent
Field name	Field description
Description	When zigbee network is refreshed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeRefreshNetworkCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

ZigbeeRefreshNetworkFailedEvent
Field name	Field description
Description	When zigbee network cannot be refreshed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "ZigbeeRefreshNetworkFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

Documentation

Expand commands

GET

Doc

/doc

text/html

End-User

Expand commands

Accounts management

Expand commands

PUT End-user Account /enduser/account application/json

Update an end-user account

	-> last name, first name
	-> email address
	-> phone and mobile phone numbers
	-> locale
	-> extra emails

Access scope : enduser/*

> Test operation

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "userId" : "a user id",
  "title" : 1,
  "firstName" : "a first name",
  "lastName" : "a last name",
  "email" : "an email",
  "phoneNumber" : "a phone number",
  "mobilePhone" : "a mobile phone",
  "locale" : "a locale",
  "commercialMailAgreement" : false,
  "extraEmails" : [ {
    "email" : "an email"
  } ]
}

Information to update the end-user account

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

EndUserAccountUpdatedEvent
Field name	Field description
Description	Enduser account has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "userId" : "a user id", "locked" : true, "owner" : false, "roleName" : "a role name", "setupLabel" : "a setup label", "firstName" : "a first name", "lastName" : "a last name", "email" : "an email", "locale" : "a locale", "mobilePhone" : "a mobile phone", "phoneNumber" : "a phone number", "templateName" : "a role name", "type" : "EndUserAccountUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

End-user Account

/enduser/email/validation

application/json

POST

End-user Account

/enduser/email/validation/{token}

application/json

POST

End-user Account

/enduser/jwt/createToken

application/json

POST

End-user Account

/enduser/password

application/json

POST

End-user Account

/enduser/password/reset

application/json

POST

End-user Account

/enduser/{userId}/validation

application/json

POST

End-user Account

/enduser/{userId}/validation/{token}

application/json

POST

End-user Setup

/enduser/setup

application/json

GET

End-user setup

/enduser/defaultSetupOID

application/json

POST

End-user setup

/enduser/defaultSetupOID

application/json

GET

End-user setup

/enduser/setupLabel

application/json

PUT

End-user setup

/enduser/setupLabel

application/json

GET

End-user setup

/enduser/setups

application/json

PUT

End-user setup

/enduser/{userId}/accessPeriod

application/json

DELETE

End-user setup

/enduser/{userId}/accessPeriod

application/json

GET

Enduser

/enduser/existingUserIds/{userId}

application/json

GET

Main end-user Account

/enduser/mainAccount

application/json

POST

Main end-user Account

/enduser/mainAccount

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "location" : {
    "city" : "a city",
    "country" : "a country",
    "postalCode" : "a postal code",
    "addressLine1" : "an address line1",
    "addressLine2" : "an address line2",
    "timezone" : "a timezone",
    "longitude" : 0.12345,
    "latitude" : 0.12345,
    "twilightMode" : 1,
    "twilightAngle" : "NAUTICAL",
    "twilightCity" : "a twilight city",
    "summerSolsticeDuskMinutes" : 1,
    "winterSolsticeDuskMinutes" : 1,
    "twilightOffsetEnabled" : false,
    "dawnOffset" : 1,
    "duskOffset" : 1,
    "tariffSettings" : {
      "tariffMode" : "offPeakWeekDays",
      "tariffs" : [ {
        "dayTariffs" : [ {
          "name" : "tariff0",
          "startTime" : "00:01"
        } ],
        "dayWeekName" : "SAT"
      } ]
    }
  },
  "label" : "a main enduser account label",
  "roleName" : "a role name",
  "applicationId" : "an application id",
  "activationTimestamp" : 120123456790,
  "expirationTimestamp" : 120123456794,
  "gatewayId" : "A comma separated list of gateway ids",
  "endUser" : {
    "userId" : "a user id",
    "title" : 1,
    "firstName" : "a first name",
    "lastName" : "a last name",
    "email" : "an email",
    "phoneNumber" : "a phone number",
    "mobilePhone" : "a mobile phone",
    "locale" : "a locale",
    "commercialMailAgreement" : true,
    "extraEmails" : [ {
      "email" : "an email"
    } ]
  },
  "password" : "a password",
  "templateName" : "a role name"
}

All information about the new main user

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

PUT Main end-user Account [DEPRECATED] since version 2018.3.3 /enduser/mainAccount application/json

Update enduser main account

	-> last name, first name
	-> email address
	-> phone and mobile phone numbers
	-> locale

Access scope : enduser/*

> Test operation

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "userId" : "a user id",
  "title" : 1,
  "firstName" : "a first name",
  "lastName" : "a last name",
  "email" : "an email",
  "phoneNumber" : "a phone number",
  "mobilePhone" : "a mobile phone",
  "locale" : "a locale",
  "commercialMailAgreement" : false,
  "extraEmails" : [ {
    "email" : "an email"
  } ]
}

All information to update the main user

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

MainAccountUpdatedEvent
Field name	Field description
Description	A main account was updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "MainAccountUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Password quality check

/enduser/password/check

application/json

POST

Secondary end-users account

/enduser/secondaryAccounts

application/json

GET

Secondary end-users account

/enduser/secondaryAccounts/{secondaryEndUserId}

application/json

GET

Secondary end-users accounts

/enduser/secondaryAccounts

application/json

Custom role

Expand commands

GET

End-user custom role

/setup/roles

application/json

POST

End-user custom role

/setup/roles

application/json

GET

End-user custom role

/setup/roles/{roleName}

application/json

DELETE

End-user custom role

/setup/roles/{roleName}

application/json

Permissions

Expand commands

GET

End-user permissions

/enduser/permissions

application/json

GET

End-user permissions

/enduser/permissions/control

application/json

GET

End-user permissions

/enduser/permissions/view

application/json

GET

End-user permissions

/enduser/{secondaryUserId}/permissions

application/json

GET

End-user permissions

/enduser/{secondaryUserId}/permissions/control

application/json

POST

End-user permissions

/enduser/{secondaryUserId}/permissions/control/{target}/{action}

application/json

DELETE

End-user permissions

/enduser/{secondaryUserId}/permissions/control/{target}/{action}

application/json

GET

End-user permissions

/enduser/{secondaryUserId}/permissions/view

application/json

POST

End-user permissions

/enduser/{secondaryUserId}/permissions/view/{target}

application/json

DELETE

End-user permissions

/enduser/{secondaryUserId}/permissions/view/{target}

application/json

Preferences

Expand commands

GET

End-user preferences

/enduser/preferences

application/json

POST

End-user preferences

/enduser/preferences/{name}/{value}

application/json

Parameters
Type	Name	Value	Description
Path Variable	name	"string value"	Preference name
Path Variable	value	"string value"	Preference value

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

EndUserPreferenceCreatedEvent
Field name	Field description
Description	A user preference has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "preferenceOID" : "a preference OID", "userId" : "a user id", "preferenceName" : "a preference name", "preferenceValue" : "a preference value", "type" : "EndUserPreferenceCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
preferenceName	Preference name
preferenceOID	Preference OID
preferenceValue	Preference value
setupOID	Setup OID
siteOID	Site OID
userId	User id

GET

End-user preferences

/enduser/preferences/{preferenceId}

application/json

DELETE End-user preferences /enduser/preferences/{preferenceId} application/json

Delete a user preference

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	preferenceId	"string value"	Preference OID

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

EndUserPreferenceDeletedEvent
Field name	Field description
Description	A user preference has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "preferenceOID" : "a preference OID", "userId" : "a user id", "preferenceName" : "a preference name", "type" : "EndUserPreferenceDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
preferenceName	Preference name
preferenceOID	Preference OID
setupOID	Setup OID
siteOID	Site OID
userId	User id

PUT

End-user preferences

/enduser/preferences/{preferenceId}/{value}

application/json

Parameters
Type	Name	Value	Description
Path Variable	preferenceId	"string value"	Preference OID
Path Variable	value	"string value"	Preference value

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

EndUserPreferenceUpdatedEvent
Field name	Field description
Description	A user preference has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "preferenceOID" : "a preference OID", "userId" : "a user id", "preferenceName" : "a preference name", "preferenceValue" : "a preference value", "type" : "EndUserPreferenceUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
preferenceName	Preference name
preferenceOID	Preference OID
preferenceValue	Preference value
setupOID	Setup OID
siteOID	Site OID
userId	User id

Events

Register a setup event listener and fetch new events from the API.

Expand commands

POST

Events Registration

/events/register

application/json

POST

Events Unregistration

/events/{listenerId}/unregister

application/json

POST

Fetching Events

/events/{listenerId}/fetch

application/json

History

Expand commands

GET

Data retention policy

/history/dataRetentionPolicy

application/json

GET

Device event history

/history/devicesEvent/{eventId}

application/json

GET

Device events history

/history/devicesEvent

application/json

GET

Execution history

/history/executions/{execId}

application/json

Parameters
Type	Name	Value	Description
Path Variable	execId	"string value"	The id of the execution to display

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "execution" : {
    "eventTime" : 1785140821890,
    "actionGroupOID" : "an action group OID",
    "actionGroupMetadata" : "an action group metadata",
    "owner" : "an owner",
    "source" : "a source",
    "endTime" : 1785140821897,
    "effectiveStartTime" : 1785140821890,
    "duration" : 7,
    "id" : "an exec id",
    "label" : "an action group label",
    "metaData" : "an execution meta data",
    "type" : "Immediate execution - MANUAL_CONTROL",
    "state" : "COMPLETED",
    "executionType" : "Immediate execution",
    "executionSubType" : "MANUAL_CONTROL",
    "failureType" : "UNKNOWN_ERROR",
    "commands" : [ {
      "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
      "command" : "a command",
      "parameters" : [ "some parameters" ],
      "detailedStatus" : {
        "type" : "generic-error",
        "message" : "a message",
        "error" : true
      },
      "rank" : 1,
      "dynamic" : false,
      "delay" : 1,
      "state" : "COMPLETED",
      "failureType" : "UNKNOWN_ERROR"
    } ]
  }
}

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

GET

Executions history

/history/executions/daily/{year}/{month}/{day}

application/json

Parameters
Type	Name	Value	Description
Path Variable	year	1	Year of the history to retrieve
Path Variable	month	1	Month of the history to retrieve (1-12)
Path Variable	day	1	Day of the history to retrieve (1-31)
Request Parameter	executionCategory	"string value"	(Optional) (Default: any) (Optional) Category of executions : manual, automation, any. (any by default)
Request Parameter	actionGroupCategory	"string value"	(Optional) (Default: any) (Optional) Category of action group : persistent, nonPersistent, any. (any by default)

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "limitReached" : true,
  "executions" : [ {
    "execution" : {
      "eventTime" : 1785201548433,
      "actionGroupOID" : "an action group OID",
      "actionGroupMetadata" : "an action group metadata",
      "owner" : "an owner",
      "source" : "a source",
      "endTime" : 1785201548434,
      "effectiveStartTime" : 1785201548434,
      "duration" : 0,
      "id" : "an exec id",
      "label" : "an action group label",
      "metaData" : "an execution meta data",
      "type" : "Immediate execution - MANUAL_CONTROL",
      "state" : "COMPLETED",
      "executionType" : "Immediate execution",
      "executionSubType" : "MANUAL_CONTROL",
      "failureType" : "UNKNOWN_ERROR",
      "commands" : [ {
        "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
        "command" : "a command",
        "parameters" : [ "some parameters" ],
        "detailedStatus" : {
          "type" : "generic-error",
          "message" : "a message",
          "error" : true
        },
        "rank" : 1,
        "dynamic" : false,
        "delay" : 1,
        "state" : "COMPLETED",
        "failureType" : "UNKNOWN_ERROR"
      } ]
    }
  } ]
}

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

GET

Executions history

/history/lastExecutions

application/json

GET

History

/history

application/json

DELETE History /history application/json

Clear history

Clear all history. This includes all executions and device events.

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

HistoryDeletedEvent
Field name	Field description
Description	Execution and device event history has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "type" : "HistoryDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Notification events history

/history/notificationEvents

application/json

GET

Setup Access Audit

/history/accessAudit/{from}/{to}

application/json

Login & Session

Establishing or terminating an API session

Expand commands

GET

Current user

/authenticated

application/json

GET

Current user

/currentUserId

application/json

POST

/login

application/json

Parameters
Type	Name	Value	Description
Request Parameter	userId	"string value"	(Optional) a user name
Request Parameter	userPassword	"string value"	(Optional) a user password
Request Parameter	ssoToken	"string value"	(Optional) an Overkiz single-sign-on token obtained through Overkiz webservices
Request Parameter	accessToken	"string value"	(Optional) an OAuth access token obtained from an OAuth service
Request Parameter	jwt	"string value"	(Optional) a Json Web Token obtained from another service
Request Parameter	applicationId	"string value"	(Optional) client application ID
Request Parameter	apiKey	"string value"	(Optional) client API Key
Request Parameter	setupOID	"string value"	(Optional) setup OID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "roles" : [ { "name" : "a security role name" } ], "extraAttributes" : { "some extra attributes" : "some extra attributes" }, "success" : true }	Returns { success: true } on successful login

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

POST

Logout

/logout

application/json

GET

Other

/accountManagement/resetPasswordFailure

application/json

GET

Other

/accountManagement/resetPasswordSuccess

application/json

Reference Data

Private tags : [ reference ]

Expand commands

GET

Controllable

/reference/controllable/{controllableName}

application/json

GET

Controllable Types

/reference/controllableTypes

application/json

POST

Devices Model

/reference/devices/search

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "uiWidgets" : [ "some ui widgets" ],
  "uiClassifiers" : [ "some ui classifiers" ],
  "controllableTypes" : [ "some controllable types" ],
  "protocolTypes" : [ "some protocol types" ],
  "uiClasses" : [ "some ui classes" ],
  "anyCriteria" : "an any criteria",
  "withManufacturerReferences" : false,
  "withStates" : true,
  "withCommands" : true,
  "withAttributes" : false
}

This following parameters are optional:
   withManufacturerReferences
   withStates
   withCommands
   withAttributes

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "allResult" : true,
  "devicesTypes" : [ {
    "typeId" : 2,
    "subsystemId" : 1,
    "localPairing" : true,
    "commands" : [ {
      "commandName" : "a command name",
      "prototype" : {
        "parameters" : [ {
          "optional" : true,
          "sensitive" : false,
          "valuePrototypes" : [ {
            "type" : "STRING",
            "description" : "string value"
          } ]
        } ]
      },
      "description" : "a description",
      "protocolSpecifics" : [ {
        "some protocol specifics" : "some protocol specifics"
      } ],
      "nparams" : 1
    } ],
    "states" : [ {
      "name" : "a device state wrapper name",
      "type" : "a device state wrapper type",
      "eventBased" : false,
      "persistent" : true,
      "prototype" : {
        "valuePrototypes" : [ {
          "type" : "STRING",
          "description" : "string value"
        } ]
      },
      "protocolSpecifics" : [ {
        "some protocol specifics" : "some protocol specifics"
      } ]
    } ],
    "attributes" : [ {
      "name" : "a device attribute wrapper name",
      "type" : 1,
      "defaultValue" : "a default value",
      "protocolSpecifics" : [ {
        "some protocol specifics" : "some protocol specifics"
      } ]
    } ],
    "manufacturerReferences" : [ {
      "provider" : "a provider",
      "tags" : [ {
        "tag" : "a tag",
        "type" : "SPEC"
      } ]
    } ],
    "uiWidget" : "a widget name",
    "controllableType" : "ACTUATOR",
    "uiClassifiers" : [ "some ui classifiers" ],
    "uiProfiles" : [ "some ui profiles" ],
    "uiClass" : "a ui class",
    "protocolType" : "IO"
  } ]
}

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

GET

Protocol Types

/reference/protocolTypes

application/json

GET

Timezones

/reference/timezones

application/json

GET

UI Classes

/reference/ui/classes

application/json

GET

UI Classifiers

/reference/ui/classifiers

application/json

GET

UI Profiles

/reference/ui/profile/{profileName}

application/json

GET

UI Profiles

/reference/ui/profileNames

application/json

GET

UI Widgets

/reference/ui/widgets

application/json

Setup

Expand commands

POST

Bulk automation configuration

/setup/automation

application/json

Parameters
Type	Name	Value	Description
Request Body	(JSON)	[ { "actionGroupOperation" : { "type" : "READ", "referenceOID" : "a reference OID" } } ]	List of operations

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "operationResponses" : [ {
    "actionGroupResponse" : {
      "managedActionGroupValue" : {
        "creationTime" : 1785201548609,
        "lastUpdateTime" : 1785201548610,
        "label" : "a managed action group label",
        "metadata" : "some metadata",
        "shortcut" : true,
        "notificationTypeMask" : 1,
        "notificationCondition" : "ON_SUCCESS",
        "notificationText" : "a notification text",
        "notificationTitle" : "a notification title",
        "targetEmailAddresses" : [ "some target email addresses" ],
        "targetPhoneNumbers" : [ "some target phone numbers" ],
        "targetPushSubscriptions" : [ "some target push subscriptions" ],
        "actions" : [ {
          "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
          "commands" : [ {
            "type" : 1,
            "name" : "a command name",
            "parameters" : [ "some parameters" ],
            "sensitiveParametersIndexes" : [ 1 ],
            "authentication" : "an authentication",
            "delay" : 1,
            "lockLevel" : 5
          } ]
        } ],
        "oid" : "the managed action group UUID"
      }
    }
  } ]
}

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

See Allowed Types

Operation Type
Operation Type
{ "actionGroupOperation" : { "type" : "READ", "referenceOID" : "a reference OID" } }
{ "setupTriggerOperation" : { "type" : "UPDATE", "setupTriggerValue" : { "sensorThreshold" : { "label" : "a sensor threshold label", "serverSide" : false, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 19, "stopMinutes" : 25, "startOffset" : 24, "stopOffset" : 22, "startAngle" : 18, "stopAngle" : 23, "startType" : "DAWN", "stopType" : "TIME", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : false, "metadata" : "some metadata", "allowFromUnknownValue" : false, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "stateName" : "a state name", "objectPath" : "an object path", "upperBound" : 15, "lowerBound" : 31, "upperEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : true, "notificationTypeMask" : 1, "notificationCondition" : "ALWAYS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 7 } ] } ] } } } ], "middleEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : true, "notificationTypeMask" : 1, "notificationCondition" : "ON_SUCCESS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 29 } ] } ] } } } ], "lowerEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : true, "notificationTypeMask" : 1, "notificationCondition" : "ALWAYS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 13 } ] } ] } } } ], "upperActivationDelay" : 1, "middleActivationDelay" : 1, "lowerActivationDelay" : 1, "upperDeactivationDelay" : 3, "middleDeactivationDelay" : 9, "lowerDeactivationDelay" : 17, "usingTriggerModeFlag" : false } }, "allowExecuteOnCreate" : false, "allowExecuteOnUpdate" : true, "setupTriggerType" : "a setup trigger type" } }
{ "calendarRuleOperation" : { "type" : "PATCH", "referenceOID" : "a reference OID", "calendarRulePatch" : { "enabled" : false } } }
{ "calendarDayOperation" : { "type" : "CREATE", "calendarDayValue" : { "label" : "a calendar day label", "type" : "WORK_DAY", "dayTimeTriggers" : [ { "startActionGroupTimeTrigger" : { "triggerType" : "DAWN", "minutes" : 1, "hours" : 1, "metadata" : "some metadata", "enabled" : false, "duskOffset" : 1, "dawnOffset" : 1, "randomTimeOffset" : 8, "alwaysBeforeHours" : 5, "alwaysBeforeMinutes" : 7, "alwaysAfterHours" : 4, "alwaysAfterMinutes" : 9, "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : true, "notificationTypeMask" : 1, "notificationCondition" : "ALWAYS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 13 } ] } ] } } } ], "metadata" : "some metadata" } } }

GET

Current setup

/setup/current

application/json

POST

Current setup

/setup/current/{setupOID}

application/json

GET

Dawn time

/setup/dawnTime

application/json

GET

Dawn time by date

/setup/dawnTime/{year}/{month}/{day}

application/json

GET

Disconnection configuration

/setup/disconnectionAlert/configuration

application/json

PUT

Disconnection configuration

/setup/disconnectionAlert/configuration

application/json

GET

Dusk time

/setup/duskTime

application/json

GET

Dusk time by date

/setup/duskTime/{year}/{month}/{day}

application/json

POST

Enduser

/setup/enduser

application/json

DELETE

Enduser

/setup/enduser/{userId}

application/json

GET

Location

/setup/location

application/json

PUT Location /setup/location application/json

Update setup location of user

Access scope : enduser/*

> Test operation

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "city" : "a city",
  "country" : "a country",
  "postalCode" : "a postal code",
  "addressLine1" : "an address line1",
  "addressLine2" : "an address line2",
  "timezone" : "a timezone",
  "longitude" : 0.12345,
  "latitude" : 0.12345,
  "twilightMode" : 1,
  "twilightAngle" : "SOLAR",
  "twilightCity" : "a twilight city",
  "summerSolsticeDuskMinutes" : 1,
  "winterSolsticeDuskMinutes" : 1,
  "twilightOffsetEnabled" : true,
  "dawnOffset" : 1,
  "duskOffset" : 1,
  "tariffSettings" : {
    "tariffMode" : "offPeakHours",
    "tariffs" : [ {
      "name" : "tariff0",
      "startTime" : "00:01"
    } ]
  }
}

The new location to set

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

LocationUpdatedEvent
Field name	Field description
Description	Setup location has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "city" : "a city", "country" : "a country", "postalCode" : "a postal code", "timezone" : "a timezone", "addressLine1" : "an address line1", "addressLine2" : "an address line2", "dawnOffset" : 1, "duskOffset" : 1, "longitude" : 791.12345, "latitude" : 790.12345, "twilightMode" : "a twilight mode", "twilightCity" : "a twilight city", "twilightAngle" : "a twilight angle", "type" : "LocationUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Setup

/setup

application/json

Parameters
Type	Name	Value	Description
Request Parameter	withManufacturerData	false	(Optional) (Default: false) true to recover manufacturer data

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1785140822076,
  "lastUpdateTime" : 1785140822096,
  "id" : "an id",
  "location" : {
    "creationTime" : 1785140822090,
    "lastUpdateTime" : 1785140822096,
    "city" : "a city",
    "country" : "a country",
    "postalCode" : "a postal code",
    "addressLine1" : "an address line1",
    "addressLine2" : "an address line2",
    "timezone" : "a timezone",
    "longitude" : 0.12345,
    "latitude" : 0.12345,
    "twilightMode" : 1,
    "twilightAngle" : "NAUTICAL",
    "twilightCity" : "a twilight city",
    "summerSolsticeDuskMinutes" : 1,
    "winterSolsticeDuskMinutes" : 1,
    "twilightOffsetEnabled" : false,
    "dawnOffset" : 1,
    "duskOffset" : 1,
    "tariffSettings" : {
      "tariffMode" : "offPeakWeekDays",
      "tariffs" : [ {
        "dayTariffs" : [ {
          "name" : "tariff0",
          "startTime" : "00:01"
        } ],
        "dayWeekName" : "SAT"
      } ]
    }
  },
  "gateways" : [ {
    "gatewayId" : "a gateway id",
    "type" : 1,
    "subType" : 1,
    "placeOID" : "a place OID",
    "autoUpdateEnabled" : false,
    "updateDeferralEnabled" : true,
    "alive" : false,
    "timeReliable" : false,
    "connectivity" : {
      "status" : "DISCONNECTED",
      "problems" : [ "NO_NTP" ],
      "protocolVersion" : "a protocol version"
    },
    "upToDate" : false,
    "updateStatus" : "UNKNOWN",
    "syncInProgress" : true,
    "updateCriticityLevel" : "DEVICES_CONTROL_ONLY",
    "automaticUpdate" : true,
    "mode" : "ACTIVE",
    "functions" : "some function names"
  } ],
  "devices" : [ {
    "label" : "a device response label",
    "uiClass" : "a ui class",
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
    "shortcut" : true,
    "controllableName" : "a controllable name",
    "metadata" : "some metadata",
    "creationTime" : 1785140822076,
    "lastUpdateTime" : 1785140822077,
    "definition" : {
      "commands" : [ {
        "commandName" : "a command name",
        "nparams" : 0
      } ],
      "states" : [ {
        "type" : "a state type",
        "values" : [ "some values" ]
      } ],
      "dataProperties" : [ {
        "value" : "a data property value"
      } ],
      "widgetName" : "a widget name",
      "uiProfiles" : [ "some ui profiles" ],
      "uiClass" : "a ui class",
      "uiClassifiers" : [ "some ui classifiers" ],
      "type" : "ACTUATOR"
    },
    "states" : [ {
      "name" : "a device state name",
      "type" : 1,
      "value" : "a device state value",
      "lastUpdateTime" : 120123456806
    } ],
    "attributes" : [ {
      "name" : "a device attribute name",
      "type" : 1,
      "value" : "a device attribute value"
    } ],
    "manufacturerData" : [ {
      "name" : "a device manufacturer data name",
      "value" : "a device manufacturer data value"
    } ],
    "localDeviceData" : [ {
      "key" : "a key",
      "value" : "a local device attribute value",
      "category" : "a category",
      "localDeviceOID" : "a local device OID"
    } ],
    "available" : false,
    "enabled" : false,
    "placeOID" : "a place OID",
    "oid" : "the device response UUID",
    "widget" : "a widget name",
    "type" : 1
  } ],
  "localDevices" : [ {
    "label" : "a local device response label",
    "placeOID" : "a place OID",
    "mapped" : false,
    "model" : {
      "type" : "a OGPNode model type",
      "subType" : "a sub type",
      "features" : [ {
        "name" : "a OGPFeature name",
        "commandLess" : true,
        "eventBased" : true,
        "authenticationRestrictedCommands" : [ "some authentication restricted commands" ]
      } ]
    },
    "attributes" : {
      "some attributes" : "some attributes"
    },
    "localDeviceData" : {
      "a local device data" : "a local device data"
    },
    "oid" : "the local device response UUID"
  } ],
  "zones" : [ {
    "creationTime" : 1785140822080,
    "lastUpdateTime" : 1785140822080,
    "label" : "a zone label",
    "type" : 0,
    "items" : [ {
      "itemType" : "device",
      "deviceOID" : "a device OID",
      "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
    } ],
    "externalOID" : "an external OID",
    "metadata" : "some metadata",
    "oid" : "the zone UUID"
  } ],
  "resellerDelegationType" : "DATE",
  "resellerDelegationEndDate" : 1785140822090,
  "metadata" : "some metadata",
  "disconnectionConfiguration" : {
    "notificationTitle" : "a notification title",
    "notificationText" : "a notification text",
    "targetPushSubscriptions" : [ "some target push subscriptions" ],
    "notificationType" : "PUSH"
  },
  "partnerId" : "a partner id",
  "rootPlace" : {
    "creationTime" : 1785140822096,
    "lastUpdateTime" : 1785140822096,
    "label" : "a place label",
    "type" : 1,
    "metadata" : "some metadata",
    "oid" : "the place UUID",
    "subPlaces" : [ {
      "creationTime" : 1785140822096,
      "lastUpdateTime" : 1785140822096,
      "label" : "a place label",
      "type" : 1,
      "metadata" : "some metadata",
      "oid" : "the place UUID",
      "subPlaces" : [ {
        "creationTime" : 1785140822096,
        "lastUpdateTime" : 1785140822096,
        "label" : "a place label",
        "type" : 1,
        "metadata" : "some metadata",
        "oid" : "the place UUID",
        "subPlaces" : [ ]
      } ]
    } ]
  },
  "features" : [ {
    "name" : "a setup feature name",
    "source" : "a source"
  } ],
  "siteOID" : "a site OID",
  "oid" : "the setup response UUID"
}

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

GET

Setup

/setup/files

application/json

GET

Setup

/setup/files/uploadURL

application/json

GET

Setup

/setup/files/{fileOID}/downloadURL

application/json

GET

Setup additional information

/setup/additionalInformation

application/json

GET

Setup additional information

/setup/additionalInformation/{templateId}

application/json

DELETE

Setup additional information

/setup/additionalInformation/{templateId}

application/json

POST

Setup additional information

/setup/additionalInformation/{templateId}/{value}

application/json

GET

Setup features

/setup/features

application/json

PUT

Setup metadata

/setup/metadata

application/json

GET

Setup options

/setup/options

application/json

GET

Setup options

/setup/options/{optionId}

application/json

GET

Setup options

/setup/options/{optionId}/{parameterName}

application/json

GET

Setup quotas

/setup/quotas

application/json

GET

Setup quotas

/setup/quotas/{quotaId}

application/json

Calendar

Private tags : [ calendar ]

Expand commands

GET

Calendar day

/setup/calendar/days

application/json

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "creationTime" : 1785140822009,
  "lastUpdateTime" : 1785140822043,
  "label" : "a calendar day label",
  "type" : "WORK_DAY",
  "dayTimeTriggers" : [ {
    "startActionGroupTimeTrigger" : {
      "triggerType" : "DAWN",
      "id" : "an id",
      "minutes" : 1,
      "hours" : 1,
      "metadata" : "some metadata",
      "enabled" : false,
      "duskOffset" : 1,
      "dawnOffset" : 1,
      "randomTimeOffset" : 8,
      "alwaysBeforeHours" : 5,
      "alwaysBeforeMinutes" : 7,
      "alwaysAfterHours" : 4,
      "alwaysAfterMinutes" : 9,
      "actionGroupOID" : "an action group OID",
      "localActionGroup" : {
        "creationTime" : 1785140822035,
        "lastUpdateTime" : 1785140822043,
        "label" : "a managed action group label",
        "metadata" : "some metadata",
        "shortcut" : true,
        "notificationTypeMask" : 1,
        "notificationCondition" : "ALWAYS",
        "notificationText" : "a notification text",
        "notificationTitle" : "a notification title",
        "targetEmailAddresses" : [ "some target email addresses" ],
        "targetPhoneNumbers" : [ "some target phone numbers" ],
        "targetPushSubscriptions" : [ "some target push subscriptions" ],
        "actions" : [ {
          "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
          "commands" : [ {
            "type" : 1,
            "name" : "a command name",
            "parameters" : [ "some parameters" ],
            "sensitiveParametersIndexes" : [ 1 ],
            "authentication" : "an authentication",
            "delay" : 1,
            "lockLevel" : 13
          } ]
        } ],
        "oid" : "the managed action group UUID"
      }
    }
  } ],
  "metadata" : "some metadata",
  "oid" : "the calendar day UUID"
} ]

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

POST

Calendar day

/setup/calendar/days

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a calendar day label",
  "type" : "WORK_DAY",
  "dayTimeTriggers" : [ {
    "startActionGroupTimeTrigger" : {
      "triggerType" : "DAWN",
      "minutes" : 1,
      "hours" : 1,
      "metadata" : "some metadata",
      "enabled" : false,
      "duskOffset" : 1,
      "dawnOffset" : 1,
      "randomTimeOffset" : 8,
      "alwaysBeforeHours" : 5,
      "alwaysBeforeMinutes" : 7,
      "alwaysAfterHours" : 4,
      "alwaysAfterMinutes" : 9,
      "actionGroupOID" : "an action group OID",
      "localActionGroup" : {
        "label" : "a managed action group label",
        "metadata" : "some metadata",
        "shortcut" : true,
        "notificationTypeMask" : 1,
        "notificationCondition" : "ALWAYS",
        "notificationText" : "a notification text",
        "notificationTitle" : "a notification title",
        "targetEmailAddresses" : [ "some target email addresses" ],
        "targetPhoneNumbers" : [ "some target phone numbers" ],
        "targetPushSubscriptions" : [ "some target push subscriptions" ],
        "actions" : [ {
          "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
          "commands" : [ {
            "type" : 1,
            "name" : "a command name",
            "parameters" : [ "some parameters" ],
            "sensitiveParametersIndexes" : [ 1 ],
            "authentication" : "an authentication",
            "delay" : 1,
            "lockLevel" : 13
          } ]
        } ]
      }
    }
  } ],
  "metadata" : "some metadata"
}

Json description of the calendar day to create

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "calendarDayOID" : "string value" }

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

CalendarDayCreatedEvent
Field name	Field description
Description	A calendar day has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "calendarDayOID" : "a calendar day OID", "label" : "a calendar day created event label", "metadata" : "some metadata", "dayType" : "a day type", "dayTimeTriggers" : [ { "startActionGroupTimeTrigger" : { "triggerType" : "DAWN", "id" : "an id", "minutes" : 1, "hours" : 1, "metadata" : "some metadata", "enabled" : false, "duskOffset" : 1, "dawnOffset" : 1, "randomTimeOffset" : 6, "alwaysBeforeHours" : 3, "alwaysBeforeMinutes" : 5, "alwaysAfterHours" : 2, "alwaysAfterMinutes" : 7, "actionGroupOID" : "an action group OID", "localActionGroup" : { "creationTime" : 1785201548584, "lastUpdateTime" : 1785201548584, "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : true, "notificationTypeMask" : 1, "notificationCondition" : "ON_SUCCESS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 11 } ] } ], "oid" : "the managed action group UUID" } } } ], "type" : "CalendarDayCreatedEvent" }
calendarDayOID	Calendar day OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT Calendar day /setup/calendar/days application/json

Update a calendar day.

Access scope : enduser/*

> Test operation

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a calendar day label",
  "type" : "WORK_DAY",
  "dayTimeTriggers" : [ {
    "startActionGroupTimeTrigger" : {
      "triggerType" : "DAWN",
      "minutes" : 1,
      "hours" : 1,
      "metadata" : "some metadata",
      "enabled" : false,
      "duskOffset" : 1,
      "dawnOffset" : 1,
      "randomTimeOffset" : 8,
      "alwaysBeforeHours" : 5,
      "alwaysBeforeMinutes" : 7,
      "alwaysAfterHours" : 4,
      "alwaysAfterMinutes" : 9,
      "actionGroupOID" : "an action group OID",
      "localActionGroup" : {
        "label" : "a managed action group label",
        "metadata" : "some metadata",
        "shortcut" : true,
        "notificationTypeMask" : 1,
        "notificationCondition" : "ALWAYS",
        "notificationText" : "a notification text",
        "notificationTitle" : "a notification title",
        "targetEmailAddresses" : [ "some target email addresses" ],
        "targetPhoneNumbers" : [ "some target phone numbers" ],
        "targetPushSubscriptions" : [ "some target push subscriptions" ],
        "actions" : [ {
          "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
          "commands" : [ {
            "type" : 1,
            "name" : "a command name",
            "parameters" : [ "some parameters" ],
            "sensitiveParametersIndexes" : [ 1 ],
            "authentication" : "an authentication",
            "delay" : 1,
            "lockLevel" : 13
          } ]
        } ],
        "oid" : "the managed action group UUID"
      }
    }
  } ],
  "metadata" : "some metadata",
  "oid" : "the calendar day UUID"
}

Json description of the calendar day to update

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

CalendarDayUpdatedEvent
Field name	Field description
Description	A calendar day has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "calendarDayOID" : "a calendar day OID", "label" : "a calendar day updated event label", "metadata" : "some metadata", "dayType" : "a day type", "dayTimeTriggers" : [ { "startActionGroupTimeTrigger" : { "triggerType" : "DAWN", "id" : "an id", "minutes" : 1, "hours" : 1, "metadata" : "some metadata", "enabled" : false, "duskOffset" : 1, "dawnOffset" : 1, "randomTimeOffset" : 6, "alwaysBeforeHours" : 3, "alwaysBeforeMinutes" : 5, "alwaysAfterHours" : 2, "alwaysAfterMinutes" : 7, "actionGroupOID" : "an action group OID", "localActionGroup" : { "creationTime" : 1785201548590, "lastUpdateTime" : 1785201548590, "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : true, "notificationTypeMask" : 1, "notificationCondition" : "ON_SUCCESS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 11 } ] } ], "oid" : "the managed action group UUID" } } } ], "type" : "CalendarDayUpdatedEvent" }
calendarDayOID	Calendar day OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Calendar day

/setup/calendar/days/{oid}

application/json

Parameters
Type	Name	Value	Description
Path Variable	oid	"string value"	OID of the calendar day to retrieve

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1785140822061,
  "lastUpdateTime" : 1785140822062,
  "label" : "a calendar day label",
  "type" : "WORK_DAY",
  "dayTimeTriggers" : [ {
    "startActionGroupTimeTrigger" : {
      "triggerType" : "DAWN",
      "id" : "an id",
      "minutes" : 1,
      "hours" : 1,
      "metadata" : "some metadata",
      "enabled" : false,
      "duskOffset" : 1,
      "dawnOffset" : 1,
      "randomTimeOffset" : 8,
      "alwaysBeforeHours" : 5,
      "alwaysBeforeMinutes" : 7,
      "alwaysAfterHours" : 4,
      "alwaysAfterMinutes" : 9,
      "actionGroupOID" : "an action group OID",
      "localActionGroup" : {
        "creationTime" : 1785140822061,
        "lastUpdateTime" : 1785140822062,
        "label" : "a managed action group label",
        "metadata" : "some metadata",
        "shortcut" : true,
        "notificationTypeMask" : 1,
        "notificationCondition" : "ALWAYS",
        "notificationText" : "a notification text",
        "notificationTitle" : "a notification title",
        "targetEmailAddresses" : [ "some target email addresses" ],
        "targetPhoneNumbers" : [ "some target phone numbers" ],
        "targetPushSubscriptions" : [ "some target push subscriptions" ],
        "actions" : [ {
          "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
          "commands" : [ {
            "type" : 1,
            "name" : "a command name",
            "parameters" : [ "some parameters" ],
            "sensitiveParametersIndexes" : [ 1 ],
            "authentication" : "an authentication",
            "delay" : 1,
            "lockLevel" : 13
          } ]
        } ],
        "oid" : "the managed action group UUID"
      }
    }
  } ],
  "metadata" : "some metadata",
  "oid" : "the calendar day UUID"
}

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

DELETE Calendar day /setup/calendar/days/{oid} application/json

Delete a calendar day.

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	oid	"string value"	Calendar day's oid to delete

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

CalendarDayDeletedEvent
Field name	Field description
Description	A calendar day has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "calendarDayOID" : "a calendar day OID", "type" : "CalendarDayDeletedEvent" }
calendarDayOID	Calendar day OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Calendar objects

/setup/calendar/schedule/{startDate}/{endDate}

application/json

GET

Calendar objects

/setup/calendar/schedule/{year}/{month}/{day}

application/json

POST

Calendar objects

/setup/calendar/schedule/{year}/{month}/{day}/dayView

application/json

Parameters
Type	Name	Value	Description
Path Variable	year	1	The year
Path Variable	month	1	The month
Path Variable	day	1	The day
Request Body	(JSON)	{ "calendarDaysOid" : [ "a calendar days oid" ], "calendarRulesOid" : [ "a calendar rules oid" ], "timeTriggersId" : [ "a time triggers id" ], "priority" : 1 }	Calendar objects filters : contains certain levels of filter to remove items calendarDaysOid => oids of the days to ignore calendarRulesOid => oids of the rules to ignore timeTriggersId => ids of the time trigger to ignore priority => ignore all rules with a lower priority Please note that none of these elements are mandatory : by default, a calendarDay with all applicable time triggers will be created

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1785140822061,
  "lastUpdateTime" : 1785140822062,
  "label" : "a calendar day label",
  "type" : "WORK_DAY",
  "dayTimeTriggers" : [ {
    "startActionGroupTimeTrigger" : {
      "triggerType" : "DAWN",
      "id" : "an id",
      "minutes" : 1,
      "hours" : 1,
      "metadata" : "some metadata",
      "enabled" : false,
      "duskOffset" : 1,
      "dawnOffset" : 1,
      "randomTimeOffset" : 8,
      "alwaysBeforeHours" : 5,
      "alwaysBeforeMinutes" : 7,
      "alwaysAfterHours" : 4,
      "alwaysAfterMinutes" : 9,
      "actionGroupOID" : "an action group OID",
      "localActionGroup" : {
        "creationTime" : 1785140822061,
        "lastUpdateTime" : 1785140822062,
        "label" : "a managed action group label",
        "metadata" : "some metadata",
        "shortcut" : true,
        "notificationTypeMask" : 1,
        "notificationCondition" : "ALWAYS",
        "notificationText" : "a notification text",
        "notificationTitle" : "a notification title",
        "targetEmailAddresses" : [ "some target email addresses" ],
        "targetPhoneNumbers" : [ "some target phone numbers" ],
        "targetPushSubscriptions" : [ "some target push subscriptions" ],
        "actions" : [ {
          "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
          "commands" : [ {
            "type" : 1,
            "name" : "a command name",
            "parameters" : [ "some parameters" ],
            "sensitiveParametersIndexes" : [ 1 ],
            "authentication" : "an authentication",
            "delay" : 1,
            "lockLevel" : 13
          } ]
        } ],
        "oid" : "the managed action group UUID"
      }
    }
  } ],
  "metadata" : "some metadata",
  "oid" : "the calendar day UUID"
}

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

GET

Calendar rule

/setup/calendar/rules

application/json

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "weeklyCalendarRule" : {
    "creationTime" : 1785140822056,
    "lastUpdateTime" : 1785140822057,
    "priority" : 1,
    "calendarDayOID" : "a calendar day OID",
    "finalRule" : true,
    "randomTimeRange" : 1,
    "dayType" : "HOLIDAY",
    "enabled" : false,
    "metadata" : "some metadata",
    "startTimeHours" : 1,
    "startTimeMinutes" : 1,
    "endTimeHours" : 1,
    "endTimeMinutes" : 1,
    "localCalendarDay" : {
      "creationTime" : 1785140822056,
      "lastUpdateTime" : 1785140822056,
      "label" : "a calendar day label",
      "type" : "DAY_OFF_AT_HOME",
      "dayTimeTriggers" : [ {
        "startActionGroupTimeTrigger" : {
          "triggerType" : "DUSK",
          "id" : "an id",
          "minutes" : 1,
          "hours" : 1,
          "metadata" : "some metadata",
          "enabled" : true,
          "duskOffset" : 1,
          "dawnOffset" : 1,
          "randomTimeOffset" : 9,
          "alwaysBeforeHours" : 6,
          "alwaysBeforeMinutes" : 8,
          "alwaysAfterHours" : 5,
          "alwaysAfterMinutes" : 10,
          "actionGroupOID" : "an action group OID",
          "localActionGroup" : {
            "creationTime" : 1785140822056,
            "lastUpdateTime" : 1785140822056,
            "label" : "a managed action group label",
            "metadata" : "some metadata",
            "shortcut" : false,
            "notificationTypeMask" : 1,
            "notificationCondition" : "ON_SUCCESS",
            "notificationText" : "a notification text",
            "notificationTitle" : "a notification title",
            "targetEmailAddresses" : [ "some target email addresses" ],
            "targetPhoneNumbers" : [ "some target phone numbers" ],
            "targetPushSubscriptions" : [ "some target push subscriptions" ],
            "actions" : [ {
              "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
              "commands" : [ {
                "type" : 1,
                "name" : "a command name",
                "parameters" : [ "some parameters" ],
                "sensitiveParametersIndexes" : [ 1 ],
                "authentication" : "an authentication",
                "delay" : 1,
                "lockLevel" : 14
              } ]
            } ],
            "oid" : "the managed action group UUID"
          }
        }
      } ],
      "metadata" : "some metadata",
      "oid" : "the calendar day UUID"
    },
    "startYear" : 1,
    "startMonth" : 1,
    "startDay" : 1,
    "endYear" : 1,
    "endMonth" : 1,
    "endDay" : 1,
    "period" : 1,
    "presenceFilter" : "NO_FILTER",
    "dayMask" : 1,
    "oid" : "the weekly calendar rule UUID"
  }
} ]

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

POST

Calendar rule

/setup/calendar/rules

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "weeklyCalendarRule" : {
    "priority" : 1,
    "calendarDayOID" : "a calendar day OID",
    "finalRule" : true,
    "randomTimeRange" : 1,
    "dayType" : "HOLIDAY",
    "enabled" : false,
    "metadata" : "some metadata",
    "startTimeHours" : 1,
    "startTimeMinutes" : 1,
    "endTimeHours" : 1,
    "endTimeMinutes" : 1,
    "localCalendarDay" : {
      "label" : "a calendar day label",
      "type" : "DAY_OFF_AT_HOME",
      "dayTimeTriggers" : [ {
        "startActionGroupTimeTrigger" : {
          "triggerType" : "DUSK",
          "minutes" : 1,
          "hours" : 1,
          "metadata" : "some metadata",
          "enabled" : true,
          "duskOffset" : 1,
          "dawnOffset" : 1,
          "randomTimeOffset" : 9,
          "alwaysBeforeHours" : 6,
          "alwaysBeforeMinutes" : 8,
          "alwaysAfterHours" : 5,
          "alwaysAfterMinutes" : 10,
          "actionGroupOID" : "an action group OID",
          "localActionGroup" : {
            "label" : "a managed action group label",
            "metadata" : "some metadata",
            "shortcut" : false,
            "notificationTypeMask" : 1,
            "notificationCondition" : "ON_SUCCESS",
            "notificationText" : "a notification text",
            "notificationTitle" : "a notification title",
            "targetEmailAddresses" : [ "some target email addresses" ],
            "targetPhoneNumbers" : [ "some target phone numbers" ],
            "targetPushSubscriptions" : [ "some target push subscriptions" ],
            "actions" : [ {
              "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
              "commands" : [ {
                "type" : 1,
                "name" : "a command name",
                "parameters" : [ "some parameters" ],
                "sensitiveParametersIndexes" : [ 1 ],
                "authentication" : "an authentication",
                "delay" : 1,
                "lockLevel" : 14
              } ]
            } ]
          }
        }
      } ],
      "metadata" : "some metadata"
    },
    "startYear" : 1,
    "startMonth" : 1,
    "startDay" : 1,
    "endYear" : 1,
    "endMonth" : 1,
    "endDay" : 1,
    "period" : 1,
    "presenceFilter" : "NO_FILTER",
    "dayMask" : 1
  }
}

Json description of the calendar rule to create

Request Parameter

withTimeValidityChecks

false

(Optional) (Default: true)

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "calendarRuleId" : "a calendar rule id", "calendarRuleOID" : "a calendar rule OID" }

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

CalendarRuleCreatedEvent
Field name	Field description
Description	A calendar rule has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "calendarRuleOID" : "a calendar rule OID", "calendarRuleId" : "a calendar rule id", "priority" : 1, "calendarDayOID" : "a calendar day OID", "dayType" : "a day type", "metadata" : "some metadata", "finalRule" : false, "randomTimeRange" : 1, "startDay" : 7, "startMonth" : 3, "startYear" : 8, "startTimeHours" : 4, "startTimeMinutes" : 10, "endDay" : 6, "endMonth" : 11, "endYear" : 5, "endTimeHours" : 2, "endTimeMinutes" : 9, "type" : "CalendarRuleCreatedEvent" }
calendarRuleId	Calendar rule Id
calendarRuleOID	Calendar rule OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

Calendar rule

/setup/calendar/rules

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "weeklyCalendarRule" : {
    "priority" : 1,
    "calendarDayOID" : "a calendar day OID",
    "finalRule" : true,
    "randomTimeRange" : 1,
    "dayType" : "HOLIDAY",
    "enabled" : false,
    "metadata" : "some metadata",
    "startTimeHours" : 1,
    "startTimeMinutes" : 1,
    "endTimeHours" : 1,
    "endTimeMinutes" : 1,
    "localCalendarDay" : {
      "label" : "a calendar day label",
      "type" : "DAY_OFF_AT_HOME",
      "dayTimeTriggers" : [ {
        "startActionGroupTimeTrigger" : {
          "triggerType" : "DUSK",
          "minutes" : 1,
          "hours" : 1,
          "metadata" : "some metadata",
          "enabled" : true,
          "duskOffset" : 1,
          "dawnOffset" : 1,
          "randomTimeOffset" : 9,
          "alwaysBeforeHours" : 6,
          "alwaysBeforeMinutes" : 8,
          "alwaysAfterHours" : 5,
          "alwaysAfterMinutes" : 10,
          "actionGroupOID" : "an action group OID",
          "localActionGroup" : {
            "label" : "a managed action group label",
            "metadata" : "some metadata",
            "shortcut" : false,
            "notificationTypeMask" : 1,
            "notificationCondition" : "ON_SUCCESS",
            "notificationText" : "a notification text",
            "notificationTitle" : "a notification title",
            "targetEmailAddresses" : [ "some target email addresses" ],
            "targetPhoneNumbers" : [ "some target phone numbers" ],
            "targetPushSubscriptions" : [ "some target push subscriptions" ],
            "actions" : [ {
              "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
              "commands" : [ {
                "type" : 1,
                "name" : "a command name",
                "parameters" : [ "some parameters" ],
                "sensitiveParametersIndexes" : [ 1 ],
                "authentication" : "an authentication",
                "delay" : 1,
                "lockLevel" : 14
              } ]
            } ],
            "oid" : "the managed action group UUID"
          }
        }
      } ],
      "metadata" : "some metadata",
      "oid" : "the calendar day UUID"
    },
    "startYear" : 1,
    "startMonth" : 1,
    "startDay" : 1,
    "endYear" : 1,
    "endMonth" : 1,
    "endDay" : 1,
    "period" : 1,
    "presenceFilter" : "NO_FILTER",
    "dayMask" : 1,
    "oid" : "the weekly calendar rule UUID"
  }
}

Json description of the calendar rule to update

Request Parameter

withTimeValidityChecks

false

(Optional) (Default: true)

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

CalendarRuleUpdatedEvent
Field name	Field description
Description	A calendar rule has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "calendarRuleOID" : "a calendar rule OID", "calendarRuleId" : "a calendar rule id", "priority" : 1, "calendarDayOID" : "a calendar day OID", "dayType" : "a day type", "metadata" : "some metadata", "finalRule" : false, "randomTimeRange" : 1, "startDay" : 7, "startMonth" : 3, "startYear" : 8, "startTimeHours" : 4, "startTimeMinutes" : 10, "endDay" : 6, "endMonth" : 11, "endYear" : 5, "endTimeHours" : 2, "endTimeMinutes" : 9, "type" : "CalendarRuleUpdatedEvent" }
calendarRuleId	Calendar rule Id
calendarRuleOID	Calendar rule OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Calendar rule

/setup/calendar/rules/{oid}

application/json

Parameters
Type	Name	Value	Description
Path Variable	oid	"string value"	Calendar rule's oid

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "weeklyCalendarRule" : {
    "creationTime" : 1785140822063,
    "lastUpdateTime" : 1785140822065,
    "priority" : 1,
    "calendarDayOID" : "a calendar day OID",
    "finalRule" : true,
    "randomTimeRange" : 1,
    "dayType" : "HOLIDAY",
    "enabled" : false,
    "metadata" : "some metadata",
    "startTimeHours" : 1,
    "startTimeMinutes" : 1,
    "endTimeHours" : 1,
    "endTimeMinutes" : 1,
    "localCalendarDay" : {
      "creationTime" : 1785140822064,
      "lastUpdateTime" : 1785140822064,
      "label" : "a calendar day label",
      "type" : "DAY_OFF_AT_HOME",
      "dayTimeTriggers" : [ {
        "startActionGroupTimeTrigger" : {
          "triggerType" : "DUSK",
          "id" : "an id",
          "minutes" : 1,
          "hours" : 1,
          "metadata" : "some metadata",
          "enabled" : true,
          "duskOffset" : 1,
          "dawnOffset" : 1,
          "randomTimeOffset" : 9,
          "alwaysBeforeHours" : 6,
          "alwaysBeforeMinutes" : 8,
          "alwaysAfterHours" : 5,
          "alwaysAfterMinutes" : 10,
          "actionGroupOID" : "an action group OID",
          "localActionGroup" : {
            "creationTime" : 1785140822064,
            "lastUpdateTime" : 1785140822064,
            "label" : "a managed action group label",
            "metadata" : "some metadata",
            "shortcut" : false,
            "notificationTypeMask" : 1,
            "notificationCondition" : "ON_SUCCESS",
            "notificationText" : "a notification text",
            "notificationTitle" : "a notification title",
            "targetEmailAddresses" : [ "some target email addresses" ],
            "targetPhoneNumbers" : [ "some target phone numbers" ],
            "targetPushSubscriptions" : [ "some target push subscriptions" ],
            "actions" : [ {
              "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
              "commands" : [ {
                "type" : 1,
                "name" : "a command name",
                "parameters" : [ "some parameters" ],
                "sensitiveParametersIndexes" : [ 1 ],
                "authentication" : "an authentication",
                "delay" : 1,
                "lockLevel" : 14
              } ]
            } ],
            "oid" : "the managed action group UUID"
          }
        }
      } ],
      "metadata" : "some metadata",
      "oid" : "the calendar day UUID"
    },
    "startYear" : 1,
    "startMonth" : 1,
    "startDay" : 1,
    "endYear" : 1,
    "endMonth" : 1,
    "endDay" : 1,
    "period" : 1,
    "presenceFilter" : "NO_FILTER",
    "dayMask" : 1,
    "oid" : "the weekly calendar rule UUID"
  }
}

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

DELETE Calendar rule /setup/calendar/rules/{oid} application/json

Delete a calendar rule.

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	oid	"string value"	Calendar rule's oid to delete

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

CalendarRuleDeletedEvent
Field name	Field description
Description	A calendar rule has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "calendarRuleOID" : "a calendar rule OID", "type" : "CalendarRuleDeletedEvent" }
calendarRuleOID	Calendar rule OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Calendar rules

/setup/calendar/ruleSet

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

[ {
  "weeklyCalendarRule" : {
    "priority" : 1,
    "calendarDayOID" : "a calendar day OID",
    "finalRule" : true,
    "randomTimeRange" : 1,
    "dayType" : "HOLIDAY",
    "enabled" : false,
    "metadata" : "some metadata",
    "startTimeHours" : 1,
    "startTimeMinutes" : 1,
    "endTimeHours" : 1,
    "endTimeMinutes" : 1,
    "localCalendarDay" : {
      "label" : "a calendar day label",
      "type" : "DAY_OFF_AT_HOME",
      "dayTimeTriggers" : [ {
        "startActionGroupTimeTrigger" : {
          "triggerType" : "DUSK",
          "minutes" : 1,
          "hours" : 1,
          "metadata" : "some metadata",
          "enabled" : true,
          "duskOffset" : 1,
          "dawnOffset" : 1,
          "randomTimeOffset" : 9,
          "alwaysBeforeHours" : 6,
          "alwaysBeforeMinutes" : 8,
          "alwaysAfterHours" : 5,
          "alwaysAfterMinutes" : 10,
          "actionGroupOID" : "an action group OID",
          "localActionGroup" : {
            "label" : "a managed action group label",
            "metadata" : "some metadata",
            "shortcut" : false,
            "notificationTypeMask" : 1,
            "notificationCondition" : "ON_SUCCESS",
            "notificationText" : "a notification text",
            "notificationTitle" : "a notification title",
            "targetEmailAddresses" : [ "some target email addresses" ],
            "targetPhoneNumbers" : [ "some target phone numbers" ],
            "targetPushSubscriptions" : [ "some target push subscriptions" ],
            "actions" : [ {
              "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
              "commands" : [ {
                "type" : 1,
                "name" : "a command name",
                "parameters" : [ "some parameters" ],
                "sensitiveParametersIndexes" : [ 1 ],
                "authentication" : "an authentication",
                "delay" : 1,
                "lockLevel" : 14
              } ]
            } ]
          }
        }
      } ],
      "metadata" : "some metadata"
    },
    "startYear" : 1,
    "startMonth" : 1,
    "startDay" : 1,
    "endYear" : 1,
    "endMonth" : 1,
    "endDay" : 1,
    "period" : 1,
    "presenceFilter" : "NO_FILTER",
    "dayMask" : 1
  }
} ]

Json description of the set of calendar rules to create

Request Parameter

withTimeValidityChecks

false

(Optional) (Default: true)

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "calendarRulesIds" : [ "some calendar rules ids" ], "calendarRulesOIDs" : [ "some calendar rules OIDs" ] }

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

CalendarRuleCreatedEvent
Field name	Field description
Description	A calendar rule has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "calendarRuleOID" : "a calendar rule OID", "calendarRuleId" : "a calendar rule id", "priority" : 1, "calendarDayOID" : "a calendar day OID", "dayType" : "a day type", "metadata" : "some metadata", "finalRule" : false, "randomTimeRange" : 1, "startDay" : 7, "startMonth" : 3, "startYear" : 8, "startTimeHours" : 4, "startTimeMinutes" : 10, "endDay" : 6, "endMonth" : 11, "endYear" : 5, "endTimeHours" : 2, "endTimeMinutes" : 9, "type" : "CalendarRuleCreatedEvent" }
calendarRuleId	Calendar rule Id
calendarRuleOID	Calendar rule OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

Calendar rules

/setup/calendar/ruleSet

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

[ {
  "weeklyCalendarRule" : {
    "priority" : 1,
    "calendarDayOID" : "a calendar day OID",
    "finalRule" : true,
    "randomTimeRange" : 1,
    "dayType" : "HOLIDAY",
    "enabled" : false,
    "metadata" : "some metadata",
    "startTimeHours" : 1,
    "startTimeMinutes" : 1,
    "endTimeHours" : 1,
    "endTimeMinutes" : 1,
    "localCalendarDay" : {
      "label" : "a calendar day label",
      "type" : "DAY_OFF_AT_HOME",
      "dayTimeTriggers" : [ {
        "startActionGroupTimeTrigger" : {
          "triggerType" : "DUSK",
          "minutes" : 1,
          "hours" : 1,
          "metadata" : "some metadata",
          "enabled" : true,
          "duskOffset" : 1,
          "dawnOffset" : 1,
          "randomTimeOffset" : 9,
          "alwaysBeforeHours" : 6,
          "alwaysBeforeMinutes" : 8,
          "alwaysAfterHours" : 5,
          "alwaysAfterMinutes" : 10,
          "actionGroupOID" : "an action group OID",
          "localActionGroup" : {
            "label" : "a managed action group label",
            "metadata" : "some metadata",
            "shortcut" : false,
            "notificationTypeMask" : 1,
            "notificationCondition" : "ON_SUCCESS",
            "notificationText" : "a notification text",
            "notificationTitle" : "a notification title",
            "targetEmailAddresses" : [ "some target email addresses" ],
            "targetPhoneNumbers" : [ "some target phone numbers" ],
            "targetPushSubscriptions" : [ "some target push subscriptions" ],
            "actions" : [ {
              "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
              "commands" : [ {
                "type" : 1,
                "name" : "a command name",
                "parameters" : [ "some parameters" ],
                "sensitiveParametersIndexes" : [ 1 ],
                "authentication" : "an authentication",
                "delay" : 1,
                "lockLevel" : 14
              } ]
            } ],
            "oid" : "the managed action group UUID"
          }
        }
      } ],
      "metadata" : "some metadata",
      "oid" : "the calendar day UUID"
    },
    "startYear" : 1,
    "startMonth" : 1,
    "startDay" : 1,
    "endYear" : 1,
    "endMonth" : 1,
    "endDay" : 1,
    "period" : 1,
    "presenceFilter" : "NO_FILTER",
    "dayMask" : 1,
    "oid" : "the weekly calendar rule UUID"
  }
} ]

Json description of the set of calendar rules to update

Request Parameter

withTimeValidityChecks

false

(Optional) (Default: true)

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

CalendarRuleUpdatedEvent
Field name	Field description
Description	A calendar rule has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "calendarRuleOID" : "a calendar rule OID", "calendarRuleId" : "a calendar rule id", "priority" : 1, "calendarDayOID" : "a calendar day OID", "dayType" : "a day type", "metadata" : "some metadata", "finalRule" : false, "randomTimeRange" : 1, "startDay" : 7, "startMonth" : 3, "startYear" : 8, "startTimeHours" : 4, "startTimeMinutes" : 10, "endDay" : 6, "endMonth" : 11, "endYear" : 5, "endTimeHours" : 2, "endTimeMinutes" : 9, "type" : "CalendarRuleUpdatedEvent" }
calendarRuleId	Calendar rule Id
calendarRuleOID	Calendar rule OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Calendar rules /setup/calendar/ruleSet/_delete application/json

Delete a set of calendar rules.

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	[ "string value" ]	Calendar rules oids to delete

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

CalendarRuleDeletedEvent
Field name	Field description
Description	A calendar rule has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "calendarRuleOID" : "a calendar rule OID", "type" : "CalendarRuleDeletedEvent" }
calendarRuleOID	Calendar rule OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Setup calendar status

/setup/calendar/status

application/json

PUT Setup calendar status /setup/calendar/status application/json

Update calendar status.

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "enabled" : false }	Calendar status

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

GatewayFunctionChangedEvent
Field name	Field description
Description	One of the gateway function has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "functionType" : 1, "enabled" : false, "type" : "GatewayFunctionChangedEvent" }
enabled	Indicate if function is enabled or disabled
functionType	Updated function
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

Camera Operations

Private tags : [ camera ]

Expand commands

POST

Picture

/setup/devices/{deviceURL}/pictures/_delete

application/json

GET

Picture

/setup/devices/{deviceURL}/pictures/{pictureId}

application/json

DELETE

Picture

/setup/devices/{deviceURL}/pictures/{pictureId}

application/json

GET

Picture

/setup/devices/{deviceURL}/pictures/{pictureId}/url

application/json

DELETE

Pictures

/setup/devices/{deviceURL}/pictures

application/json

GET

Pictures

/setup/devices/{deviceURL}/pictures/export

application/json

GET

Pictures

/setup/devices/{deviceURL}/pictures/{from}/{to}

application/json

GET

Pictures

/setup/devices/{deviceURL}/pictures/{from}/{to}/{offset}/{size}

application/json

Device

Expand commands

GET

Device

/setup/devices/{deviceURL}

application/json

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	The url of the device
Request Parameter	withManufacturerData	false	(Optional) (Default: false) true to recover manufacturer data

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "label" : "a device response label",
  "uiClass" : "a ui class",
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
  "shortcut" : true,
  "controllableName" : "a controllable name",
  "metadata" : "some metadata",
  "creationTime" : 1785140821935,
  "lastUpdateTime" : 1785140821958,
  "definition" : {
    "commands" : [ {
      "commandName" : "a command name",
      "nparams" : 0
    } ],
    "states" : [ {
      "type" : "a state type",
      "values" : [ "some values" ]
    } ],
    "dataProperties" : [ {
      "value" : "a data property value"
    } ],
    "widgetName" : "a widget name",
    "uiProfiles" : [ "some ui profiles" ],
    "uiClass" : "a ui class",
    "uiClassifiers" : [ "some ui classifiers" ],
    "type" : "ACTUATOR"
  },
  "states" : [ {
    "name" : "a device state name",
    "type" : 1,
    "value" : "a device state value",
    "lastUpdateTime" : 120123456794
  } ],
  "attributes" : [ {
    "name" : "a device attribute name",
    "type" : 1,
    "value" : "a device attribute value"
  } ],
  "manufacturerData" : [ {
    "name" : "a device manufacturer data name",
    "value" : "a device manufacturer data value"
  } ],
  "localDeviceData" : [ {
    "key" : "a key",
    "value" : "a local device attribute value",
    "category" : "a category",
    "localDeviceOID" : "a local device OID"
  } ],
  "available" : false,
  "enabled" : false,
  "placeOID" : "a place OID",
  "oid" : "the device response UUID",
  "widget" : "a widget name",
  "type" : 1
}

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

DELETE

Device [DEPRECATED] since version 2018.3.3

/setup/devices/{deviceURL}

application/json

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL to update
Request Body	(JSON)	{ "purgeHistory" : true, "deleteAllSubSystems" : true, "deleteEmptyCalendarDays" : false, "forced" : false }	(Optional) Json description of the calendar day to create

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

DeviceDeletionFailedEvent
Field name	Field description
Description	Device deletion from the gateway has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "DeviceDeletionFailedEvent", "failureType" : "NON_EXECUTING" }
deviceURL	Device URL
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceRemovedEvent
Field name	Field description
Description	A device has been removed from the gateway
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "type" : "DeviceRemovedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Device [DEPRECATED] since version 2020.3.4

/setup/devices/{deviceURL}/_delete

application/json

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL to update
Request Body	(JSON)	{ "purgeHistory" : true, "deleteAllSubSystems" : true, "deleteEmptyCalendarDays" : false, "forced" : false }	(Optional) Json description of the calendar day to create

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

DeviceDeletionFailedEvent
Field name	Field description
Description	Device deletion from the gateway has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "DeviceDeletionFailedEvent", "failureType" : "NON_EXECUTING" }
deviceURL	Device URL
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceRemovedEvent
Field name	Field description
Description	A device has been removed from the gateway
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "type" : "DeviceRemovedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Device

/setup/devices/{deviceURL}/_deleteCascade

application/json

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL to delete
Request Body	(JSON)	{ "purgeHistory" : true, "deleteAllSubSystems" : true, "deleteEmptyCalendarDays" : false, "forced" : false }	(Optional) Delete options

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "jobId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceRemovedEvent
Field name	Field description
Description	A device has been removed from the gateway
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "type" : "DeviceRemovedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceDeletionFailedEvent
Field name	Field description
Description	Device deletion from the gateway has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "DeviceDeletionFailedEvent", "failureType" : "NON_EXECUTING" }
deviceURL	Device URL
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SetupJobCompletedEvent
Field name	Field description
Description	An asynchronous job has completed successfully
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "jobId" : "a job id", "type" : "SetupJobCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SetupJobFailedEvent
Field name	Field description
Description	An asynchronous job has failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "jobId" : "a job id", "type" : "SetupJobFailedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Device

/setup/devices/{deviceURL}/controllable

application/json

PUT

Device

/setup/devices/{deviceURL}/label/{label}

application/json

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL to update
Path Variable	label	"string value"	New device label
Request Parameter	updateDeviceName	false	(Optional) (Default: false) If true, device name will also be updated

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceUpdatedEvent
Field name	Field description
Description	Device has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "type" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

Device

/setup/devices/{deviceURL}/relocate/{placeOID}

application/json

PUT

Device [DEPRECATED] since version 2026.2.1

/setup/devices/{deviceURL}/{label}

application/json

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL to update
Path Variable	label	"string value"	New device label
Request Parameter	updateDeviceName	false	(Optional) (Default: false) If true, device name will also be updated

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceUpdatedEvent
Field name	Field description
Description	Device has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "type" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

Device

/setup/devices/{deviceURL}/{label}/subSystems

application/json

PUT

Device

/setup/devices/{deviceURL}/{label}/{category}

application/json

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL to update
Path Variable	label	"string value"	New device label
Path Variable	category	"string value"	New device measurement category
Request Parameter	updateDeviceName	false	(Optional) (Default: false) If true, device name will also be updated

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "execId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceUpdatedEvent
Field name	Field description
Description	Device has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "type" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

Device Type

/setup/devices/{deviceURL}/deviceType/{newDeviceType}

application/json

GET

Device additional information

/setup/devices/additionalInformation

application/json

GET

Device additional information

/setup/devices/{deviceURL}/additionalInformation

application/json

GET

Device additional information

/setup/devices/{deviceURL}/additionalInformation/{templateId}

application/json

GET

Device attribute

/setup/devices/{deviceURL}/attributes/{name}

application/json

GET

Device attributes

/setup/devices/{deviceURL}/attributes

application/json

PUT

Device controllable

/setup/devices/{deviceURL}/alternativeControllables/{newControllableName}

application/json

PUT

Device controllable [DEPRECATED] since version 2018.3.3

/setup/devices/{deviceURL}/equivalentControllables/{newControllableName}

application/json

GET

Device controllables

/setup/devices/{deviceURL}/alternativeControllables

application/json

GET

Device firmware

/setup/devices/{deviceURL}/firmwareUpToDate

application/json

GET

Device firmware

/setup/devices/{deviceURL}/firmwareUpdateCapability

application/json

PUT Device firmware /setup/devices/{deviceURL}/updateFirmware application/json

Update The device firmware to the next available version

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL to update

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceFirmwareUpdateStartedEvent
Field name	Field description
Description	A firmware update started on the given device
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "DeviceFirmwareUpdateStartedEvent" }
deviceURL	The device address
gatewayId	The gateway id
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewayFirmwareUpdateFailedEvent
Field name	Field description
Description	Gateway firmware update failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "firmwareType" : "a firmware type", "type" : "GatewayFirmwareUpdateFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceFirmwareUpdateCompletedEvent
Field name	Field description
Description	Device firmware update is completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "DeviceFirmwareUpdateCompletedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewayFirmwareUpdateCompletedEvent
Field name	Field description
Description	Gateway firmware update is completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "firmwareType" : "a firmware type", "type" : "GatewayFirmwareUpdateCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceFirmwareUpdateFailedEvent
Field name	Field description
Description	Device firmware update failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "DeviceFirmwareUpdateFailedEvent", "failureType" : "NON_EXECUTING" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewayFirmwareUpdateStartedEvent
Field name	Field description
Description	A firmware update started on the given gateway
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "type" : "GatewayFirmwareUpdateStartedEvent" }
gatewayId	The gateway id
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Device manufacturer references

/setup/devices/{deviceURL}/manufacturerReferences

application/json

PUT

Device metadata

/setup/devices/{deviceURL}/metadata

application/json

GET

Device state

/setup/devices/{deviceURL}/states/{name}

application/json

PUT

Device state

/setup/devices/{deviceURL}/states/{name}/{stateType}/{stateValue}

application/json

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL to update
Path Variable	name	"string value"	The target state name (ex: core:DummyState)
Path Variable	stateType	1	Type of the state value
Path Variable	stateValue	"string value"	State value as string.

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Device states

/setup/devices/{deviceURL}/states

application/json

GET

Devices

/setup/devices

application/json

Parameters
Type	Name	Value	Description
Request Parameter	withManufacturerData	false	(Optional) (Default: false) true to recover manufacturer data

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "label" : "a device response label",
  "uiClass" : "a ui class",
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
  "shortcut" : true,
  "controllableName" : "a controllable name",
  "metadata" : "some metadata",
  "creationTime" : 1785140821960,
  "lastUpdateTime" : 1785140821961,
  "definition" : {
    "commands" : [ {
      "commandName" : "a command name",
      "nparams" : 0
    } ],
    "states" : [ {
      "type" : "a state type",
      "values" : [ "some values" ]
    } ],
    "dataProperties" : [ {
      "value" : "a data property value"
    } ],
    "widgetName" : "a widget name",
    "uiProfiles" : [ "some ui profiles" ],
    "uiClass" : "a ui class",
    "uiClassifiers" : [ "some ui classifiers" ],
    "type" : "ACTUATOR"
  },
  "states" : [ {
    "name" : "a device state name",
    "type" : 1,
    "value" : "a device state value",
    "lastUpdateTime" : 120123456794
  } ],
  "attributes" : [ {
    "name" : "a device attribute name",
    "type" : 1,
    "value" : "a device attribute value"
  } ],
  "manufacturerData" : [ {
    "name" : "a device manufacturer data name",
    "value" : "a device manufacturer data value"
  } ],
  "localDeviceData" : [ {
    "key" : "a key",
    "value" : "a local device attribute value",
    "category" : "a category",
    "localDeviceOID" : "a local device OID"
  } ],
  "available" : false,
  "enabled" : false,
  "placeOID" : "a place OID",
  "oid" : "the device response UUID",
  "widget" : "a widget name",
  "type" : 1
} ]

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

PUT

Devices

/setup/devices/link

application/json

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "devicesURL" : [ "a devices URL" ] }

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "groupId" : "string value" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceUpdatedEvent
Field name	Field description
Description	Device has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "type" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DELETE Devices [DEPRECATED] since version 2018.3.3 /setup/devices/link application/json

Unlink devices by removing groupId

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "devicesURL" : [ "a devices URL" ] }

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

DeviceUpdatedEvent
Field name	Field description
Description	Device has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "type" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Devices /setup/devices/link/_delete application/json

Unlink devices by removing groupId

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "devicesURL" : [ "a devices URL" ] }

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

DeviceUpdatedEvent
Field name	Field description
Description	Device has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "type" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT Devices availabilities /setup/devices/refresh application/json

Ask the box to refresh all devices availabilities for protocols that support this operation

Per-session rate-limit : 1 calls per 1d period for this particular operation (bulk-load)

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Devices controllable

/setup/devices/controllables/{controllableName}

application/json

GET

Devices controllables

/setup/devices/controllables

application/json

GET

Devices firmware

/setup/devices/notUpToDate

application/json

PUT Devices firmware /setup/devices/updateFirmwares application/json

Update the given devices firmwares to the next available version

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	[ "string value" ]	List of devices URLs to update

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceFirmwareUpdateStartedEvent
Field name	Field description
Description	A firmware update started on the given device
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "DeviceFirmwareUpdateStartedEvent" }
deviceURL	The device address
gatewayId	The gateway id
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewayFirmwareUpdateCompletedEvent
Field name	Field description
Description	Gateway firmware update is completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "firmwareType" : "a firmware type", "type" : "GatewayFirmwareUpdateCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceFirmwareUpdateCompletedEvent
Field name	Field description
Description	Device firmware update is completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "DeviceFirmwareUpdateCompletedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewayFirmwareUpdateStartedEvent
Field name	Field description
Description	A firmware update started on the given gateway
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "type" : "GatewayFirmwareUpdateStartedEvent" }
gatewayId	The gateway id
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceFirmwareUpdateFailedEvent
Field name	Field description
Description	Device firmware update failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "type" : "DeviceFirmwareUpdateFailedEvent", "failureType" : "NON_EXECUTING" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewayFirmwareUpdateFailedEvent
Field name	Field description
Description	Gateway firmware update failed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "gatewayId" : "a gateway id", "firmwareType" : "a firmware type", "type" : "GatewayFirmwareUpdateFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Devices growing index variations

/setup/devices/states/growingIndexes

application/json

POST Devices states /setup/devices/states/refresh application/json

Ask the box to refresh all or given devices states for protocols supporting that operation

Per-session rate-limit : 1 calls per 1d period for this particular operation (bulk-load)

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	[ "string value" ]	(Optional) URLs of the devices to refresh

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

RefreshAllDevicesStatesFailedEvent
Field name	Field description
Description	Devices states could not be refreshed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

RefreshAllDevicesStatesCompletedEvent
Field name	Field description
Description	Refresh all states query for given protocol type is completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT Devices states [DEPRECATED] since version 2018.3.3 /setup/devices/states/refresh application/json

Ask the box to refresh all devices states for protocols supporting that operation - Deprecated : use POST method

Per-session rate-limit : 1 calls per 1d period for this particular operation (bulk-load)

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

RefreshAllDevicesStatesFailedEvent
Field name	Field description
Description	Devices states could not be refreshed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

RefreshAllDevicesStatesCompletedEvent
Field name	Field description
Description	Refresh all states query for given protocol type is completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST Devices states /setup/devices/{deviceURL}/states/refresh application/json

Ask the box to refresh all states on given device

Per-session rate-limit : 1 calls per 1d period for this particular operation (bulk-load)

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

RefreshAllDevicesStatesCompletedEvent
Field name	Field description
Description	Refresh all states query for given protocol type is completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

RefreshAllDevicesStatesFailedEvent
Field name	Field description
Description	Devices states could not be refreshed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

LocalDevice localDeviceData

/setup/devices/{deviceURL}/localDeviceData/{key}

application/json

GET

hidden [DEPRECATED] since version 2018.3.3

/setup/devices/hidden

application/json

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "label" : "a device response label",
  "uiClass" : "a ui class",
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
  "shortcut" : true,
  "controllableName" : "a controllable name",
  "metadata" : "some metadata",
  "creationTime" : 1785140821960,
  "lastUpdateTime" : 1785140821961,
  "definition" : {
    "commands" : [ {
      "commandName" : "a command name",
      "nparams" : 0
    } ],
    "states" : [ {
      "type" : "a state type",
      "values" : [ "some values" ]
    } ],
    "dataProperties" : [ {
      "value" : "a data property value"
    } ],
    "widgetName" : "a widget name",
    "uiProfiles" : [ "some ui profiles" ],
    "uiClass" : "a ui class",
    "uiClassifiers" : [ "some ui classifiers" ],
    "type" : "ACTUATOR"
  },
  "states" : [ {
    "name" : "a device state name",
    "type" : 1,
    "value" : "a device state value",
    "lastUpdateTime" : 120123456794
  } ],
  "attributes" : [ {
    "name" : "a device attribute name",
    "type" : 1,
    "value" : "a device attribute value"
  } ],
  "manufacturerData" : [ {
    "name" : "a device manufacturer data name",
    "value" : "a device manufacturer data value"
  } ],
  "localDeviceData" : [ {
    "key" : "a key",
    "value" : "a local device attribute value",
    "category" : "a category",
    "localDeviceOID" : "a local device OID"
  } ],
  "available" : false,
  "enabled" : false,
  "placeOID" : "a place OID",
  "oid" : "the device response UUID",
  "widget" : "a widget name",
  "type" : 1
} ]

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Device State History

For measurement devices like luminance or energy consumption sensors, a state history can be recorded.

State ...history can be retrieved in two formats :
	-> for only one device
	-> for one device with stacked values of other devices of the same measurement category

In any case, history can be aggregated by day, by month or by year.

To use stacked values, devices has to be sorted by category thanks to the core:MeasurementCategory attribute (see appendix for supported values). Thus the returned stacked values contains values for each categorie and sub-categorie of the device.

For example, measurement category of an electricity sensor can be ?electric/heatingSystem?: this will indicate that device is an electric heating system (if device was a gas heating system, measurement category would be ?gas/heatingSystem?). Therefore, stacked values will contain a value for the device, a value for all the heating systems of the setup and a value for all the electric sensors of the setup.
Read more

Expand commands

GET

Annual history values

/setup/devices/{deviceURL}/states/{name}/history/annual/{from}/{to}

application/json

GET

Annual stacked history values

/setup/devices/{deviceURL}/states/{name}/history/stacked/annual/{from}/{to}

application/json

GET

Annual stacked states history values

/setup/devices/{deviceURL}/states/history/stacked/annual/{from}/{to}

application/json

GET

Annual states history values

/setup/devices/{deviceURL}/states/history/annual/{from}/{to}

application/json

GET

Daily history values

/setup/devices/{deviceURL}/states/{name}/history/daily/{from}/{to}

application/json

GET

Daily stacked history values

/setup/devices/{deviceURL}/states/{name}/history/stacked/daily/{from}/{to}

application/json

GET

Daily stacked history values

/setup/devices/{deviceURL}/states/{name}/history/stacked/daily/{from}/{to}/export

text/csv

GET

Daily stacked states history values

/setup/devices/{deviceURL}/states/history/stacked/daily/{from}/{to}

application/json

GET

Daily states history values

/setup/devices/{deviceURL}/states/history/daily/{from}/{to}

application/json

GET

Export history values

/setup/devices/{deviceURL}/states/{name}/history/export

text/csv

GET

History values

/setup/devices/{deviceURL}/states/{name}/history/{from}/{to}

application/json

GET

History values

/setup/devices/{deviceURL}/states/{name}/history/{from}/{to}/export

text/csv

GET

Monthly history values

/setup/devices/{deviceURL}/states/{name}/history/monthly/{from}/{to}

application/json

GET

Monthly history values [DEPRECATED] since version 2018.3.3

/setup/devices/{deviceURL}/states/{name}/history/montly/{from}/{to}

application/json

GET

Monthly stacked history values

/setup/devices/{deviceURL}/states/{name}/history/stacked/monthly/{from}/{to}

application/json

GET

Monthly stacked states history values

/setup/devices/{deviceURL}/states/history/stacked/monthly/{from}/{to}

application/json

GET

Monthly states history values

/setup/devices/{deviceURL}/states/history/monthly/{from}/{to}

application/json

GET

Stacked history values

/setup/devices/{deviceURL}/states/{name}/history/stacked/{from}/{to}

application/json

GET

Stacked states history values

/setup/devices/{deviceURL}/states/history/stacked/{from}/{to}

application/json

GET

States History values

/setup/devices/{deviceURL}/states/history/{from}/{to}

application/json

Gateway

Expand commands

POST

Activate developer mode

/setup/gateways/{gatewayId}/developerMode

application/json

POST

Activate module

/setup/gateways/{gatewayId}/modules/{moduleId}

application/json

GET

Disconnection configuration

/setup/gateways/{gatewayId}/disconnectionAlert/configuration

application/json

PUT

Disconnection configuration

/setup/gateways/{gatewayId}/disconnectionAlert/configuration

application/json

POST

Enable Auto Update

/setup/gateways/{gatewayId}/enableAutoUpdate

application/json

GET

Gateway

/setup/gateways/{gatewayId}

application/json

GET

Gateway

/setup/gateways/{gatewayId}/activeProtocols

application/json

PUT

Gateway

/setup/gateways/{gatewayId}/attach

application/json

GET

Gateway

/setup/gateways/{gatewayId}/availableProtocols

application/json

GET

Gateway

/setup/gateways/{gatewayId}/supportedProtocols

application/json

PUT

Gateway

/setup/gateways/{gatewayId}/update

application/json

GET

Gateway

/setup/gateways/{gatewayId}/usedActiveProtocols

application/json

PUT

Gateway

/setup/gateways/{sourceGatewayId}/migrate/{targetGatewayId}

application/json

PUT

Gateway

/setup/gateways/{sourceGatewayId}/migrateAndUpdate/{targetGatewayId}

application/json

GET

Gateway Synchronization

/setup/gateways/{gatewayId}/aliveAndReady

application/json

GET

Gateway Synchronization

/setup/gateways/{gatewayId}/synchronization/failedTasks

application/json

GET

Gateway Synchronization

/setup/gateways/{gatewayId}/synchronization/failedTasks/categories

application/json

GET

Gateway Synchronization

/setup/gateways/{gatewayId}/synchronization/inProgress

application/json

GET

Gateway Synchronization

/setup/gateways/{gatewayId}/synchronization/pendingTasks

application/json

POST

Gateway activate partner offer

/setup/gateways/{gatewayId}/partnerOffers/{partnerOfferId}/activate

application/json

GET

Gateway additional informations

/setup/gateways/{gatewayId}/additionalInformation

application/json

GET

Gateway additional informations

/setup/gateways/{gatewayId}/additionalInformation/{templateId}

application/json

POST

Gateway deactivate partner offer

/setup/gateways/{gatewayId}/partnerOffers/{partnerOfferId}/deactivate

application/json

PUT

Gateway management

/setup/gateways/{gatewayId}/detach

application/json

GET

Gateway management

/setup/gateways/{gatewayId}/functions

application/json

PUT

Gateway management

/setup/gateways/{gatewayId}/functions/{functionType}

application/json

GET

Gateway version

/setup/gateways/{gatewayId}/version

application/json

GET

Gateways

/setup/gateways

application/json

GET

Get all partner offers ids

/setup/gateways/{gatewayId}/partnerOffers

application/json

GET

Get developer mode status

/setup/gateways/{gatewayId}/developerMode

application/json

POST

KeepAlive

/setup/gateways/{gatewayId}/protocols/{protocolType}/keepAlive

application/json

POST Refresh states /setup/gateways/{gatewayId}/devices/states/refresh application/json

Refresh all devices states of given gateway

Per-session rate-limit : 1 calls per 1d period for this particular operation (bulk-load)

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

RefreshAllDevicesStatesCompletedEvent
Field name	Field description
Description	Refresh all states query for given protocol type is completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

RefreshAllDevicesStatesFailedEvent
Field name	Field description
Description	Devices states could not be refreshed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Refresh states

/setup/gateways/{gatewayId}/protocols/{protocolType}/devices/states/refresh

application/json

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway
Path Variable	protocolType	1	The protocol type

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

RefreshAllDevicesStatesFailedEvent
Field name	Field description
Description	Devices states could not be refreshed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

RefreshAllDevicesStatesCompletedEvent
Field name	Field description
Description	Refresh all states query for given protocol type is completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DELETE

deactivate module

/setup/gateways/{gatewayId}/modules/{moduleId}

application/json

Interactive Notifications

Expand commands

GET

Setup interactive notification

/setup/interactiveNotifications/{interactiveNotificationOID}

application/json

POST

Setup interactive notification

/setup/interactiveNotifications/{interactiveNotificationOID}/{actionType}

application/json

GET

Setup interactive notifications

/setup/interactiveNotifications

application/json

GET

Setup interactive notifications history

/setup/interactiveNotifications/history

application/json

Local Devices

Expand commands

POST

Local Device

/setup/localDevices

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a local device request label",
  "placeOID" : "a place OID",
  "model" : {
    "type" : "a OGPNode model type",
    "subType" : "a sub type",
    "features" : [ {
      "name" : "a OGPFeature name",
      "stateLess" : true,
      "authenticationRestrictedCommands" : [ "some authentication restricted commands" ]
    } ]
  },
  "attributes" : {
    "some attributes" : "some attributes"
  },
  "localDeviceData" : {
    "a local device data" : "a local device data"
  }
}

The new local device to create

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "label" : "a local device response label",
  "placeOID" : "a place OID",
  "mapped" : false,
  "model" : {
    "type" : "a OGPNode model type",
    "subType" : "a sub type",
    "features" : [ {
      "name" : "a OGPFeature name",
      "commandLess" : true,
      "eventBased" : true,
      "authenticationRestrictedCommands" : [ "some authentication restricted commands" ]
    } ]
  },
  "attributes" : {
    "some attributes" : "some attributes"
  },
  "localDeviceData" : {
    "a local device data" : "a local device data"
  },
  "oid" : "the local device response UUID"
}

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

LocalDeviceCreatedEvent
Field name	Field description
Description	Event sent when a new local device is created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "localDeviceOID" : "a local device OID", "label" : "a local device created event label", "placeOID" : "a place OID", "model" : { "type" : "a OGPNode model type", "subType" : "a sub type", "features" : [ { "name" : "a OGPFeature name", "stateLess" : true, "authenticationRestrictedCommands" : [ "some authentication restricted commands" ] } ] }, "attributes" : { "some attributes" : "some attributes" }, "localDeviceData" : { "a local device data" : "a local device data" }, "type" : "LocalDeviceCreatedEvent" }
localDeviceOID	Local device OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Local Device

/setup/localDevices/{localDeviceOID}

application/json

DELETE

Local Device

/setup/localDevices/{localDeviceOID}

application/json

Parameters
Type	Name	Value	Description
Path Variable	localDeviceOID	"string value"	The OID of the local device to delete
Request Parameter	forced	false	(Optional) (Default: false) true to allow deletion of a mapped device

Response
Type	Name	Value	Description
Response Body	(JSON)

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

LocalDeviceDeletedEvent
Field name	Field description
Description	Event sent when a local device is deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "localDeviceOID" : "a local device OID", "type" : "LocalDeviceDeletedEvent" }
localDeviceOID	Local device OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

Local Device

/setup/localDevices/{localDeviceOID}/label/{newLabel}

application/json

Parameters
Type	Name	Value	Description
Path Variable	localDeviceOID	"string value"	The OID of the local device
Path Variable	newLabel	"string value"	New local device label

Response
Type	Name	Value	Description
Response Body	(JSON)

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

LocalDeviceUpdatedEvent
Field name	Field description
Description	Event sent when a local device changes (label, place)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "localDeviceOID" : "a local device OID", "label" : "a local device updated event label", "placeOID" : "a place OID", "type" : "LocalDeviceUpdatedEvent" }
localDeviceOID	Local device OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

Local Device

/setup/localDevices/{localDeviceOID}/localDeviceData

application/json

Parameters
Type	Name	Value	Description
Path Variable	localDeviceOID	"string value"	The OID of the local device
Request Body	(JSON)	{ "string value" : "object or primitive" }	The local device data to update

Response
Type	Name	Value	Description
Response Body	(JSON)

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

LocalDeviceDataUpdatedEvent
Field name	Field description
Description	Event sent when some local device data changes
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "localDeviceOID" : "a local device OID", "localDeviceData" : { "a local device data" : "a local device data" }, "type" : "LocalDeviceDataUpdatedEvent" }
localDeviceOID	Local device OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

Local Device

/setup/localDevices/{localDeviceOID}/relocate/{placeOID}

application/json

Parameters
Type	Name	Value	Description
Path Variable	localDeviceOID	"string value"	The OID of the local device
Path Variable	placeOID	"string value"	Existing place OID where local device is relocated

Response
Type	Name	Value	Description
Response Body	(JSON)

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

LocalDeviceUpdatedEvent
Field name	Field description
Description	Event sent when a local device changes (label, place)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "localDeviceOID" : "a local device OID", "label" : "a local device updated event label", "placeOID" : "a place OID", "type" : "LocalDeviceUpdatedEvent" }
localDeviceOID	Local device OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GET

Local Devices

/setup/localDevices

application/json

Place

Expand commands

GET

Place

/setup/places

application/json

POST

Place

/setup/places/{parentPlaceOID}/subPlaces

application/json

Parameters
Type	Name	Value	Description
Path Variable	parentPlaceOID	"string value"	The parent place of the new place
Request Body	(JSON)	{ "type" : "a place request type", "label" : "a place request label", "metadata" : "some metadata" }	Place settings : type, label and metadata

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "placeOID" : "string value" }

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

PlaceCreatedEvent
Field name	Field description
Description	A new place has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "placeOID" : "a place OID", "parentPlaceOID" : "a parent place OID", "placeType" : 1, "label" : "a place created event label", "metadata" : "some metadata", "type" : "PlaceCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
placeOID	Place OID
setupOID	Setup OID
siteOID	Site OID

POST

Place [DEPRECATED] since version 2018.3.3

/setup/places/{parentPlaceOID}/{label}/{type}

application/json

Parameters
Type	Name	Value	Description
Path Variable	parentPlaceOID	"string value"	The parent place of the new place
Path Variable	label	"string value"	The name of the place
Path Variable	type	"string value"	The type of the place (Could be an integer or a string)

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

PlaceCreatedEvent
Field name	Field description
Description	A new place has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "placeOID" : "a place OID", "parentPlaceOID" : "a parent place OID", "placeType" : 1, "label" : "a place created event label", "metadata" : "some metadata", "type" : "PlaceCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
placeOID	Place OID
setupOID	Setup OID
siteOID	Site OID

GET

Place

/setup/places/{placeOID}

application/json

PUT

Place

/setup/places/{placeOID}

application/json

DELETE Place /setup/places/{placeOID} application/json

Delete a place from user setup

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	placeOID	"string value"	The id of the place to delete

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

PlaceDeletedEvent
Field name	Field description
Description	An existing place has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "placeOID" : "a place OID", "type" : "PlaceDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
placeOID	Place OID
setupOID	Setup OID
siteOID	Site OID

PUT

Place

/setup/places/{placeOID}/parent/{newParentPlaceOID}

application/json

PUT

Place [DEPRECATED] since version 2018.3.3

/setup/places/{placeOID}/{newParentPlaceOID}

application/json

Protocol

Expand commands

POST Devices states /setup/protocols/{protocolType}/devices/states/refresh application/json

Ask the box to refresh all devices states of given protocol

Per-session rate-limit : 1 calls per 1d period for this particular operation (bulk-load)

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type of devices to refresh

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

RefreshAllDevicesStatesFailedEvent
Field name	Field description
Description	Devices states could not be refreshed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DeviceStateChangedEvent
Field name	Field description
Description	One or more states of a device have changed (high-level)
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "type" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

RefreshAllDevicesStatesCompletedEvent
Field name	Field description
Description	Refresh all states query for given protocol type is completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "type" : "RefreshAllDevicesStatesCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

Push

Private tags : [ push ]

Expand commands

POST

Android [DEPRECATED] since version 2018.3.3

/setup/subscribe/notification/android/{providerApplicationId}

application/json

Parameters

Type

Name

Value

Description

Path Variable

providerApplicationId

"string value"

The provider application Id

Request Body

(JSON)

{
  "device" : {
    "udid" : "a udid",
    "model" : "a model",
    "version" : "a version",
    "name" : "a push device name",
    "metadata" : "some metadata"
  },
  "userId" : "a user id",
  "registrationId" : "a registration id",
  "jsonPayload" : false
}

Json description of the device to subscribe and the configuration wanted

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

PushSubscriptionCreatedEvent
Field name	Field description
Description	A push subscription has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "pushSubscriptionOID" : "a push subscription OID", "type" : "PushSubscriptionCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DELETE

Android [DEPRECATED] since version 2018.3.3

/setup/subscribe/notification/android/{providerApplicationId}/{deviceUdid}

application/json

POST

AndroidFcm

/setup/subscribe/notification/android/fcm/{providerApplicationId}

application/json

Parameters

Type

Name

Value

Description

Path Variable

providerApplicationId

"string value"

The provider application Id

Request Body

(JSON)

{
  "device" : {
    "udid" : "a udid",
    "model" : "a model",
    "version" : "a version",
    "name" : "a push device name",
    "metadata" : "some metadata"
  },
  "userId" : "a user id",
  "registrationId" : "a registration id"
}

Json description of the device to subscribe and the configuration wanted

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

PushSubscriptionCreatedEvent
Field name	Field description
Description	A push subscription has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "pushSubscriptionOID" : "a push subscription OID", "type" : "PushSubscriptionCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

AndroidFcm

/setup/subscribe/notification/android/fcm/{providerApplicationId}

application/json

GET

AndroidFcm

/setup/subscribe/notification/android/fcm/{providerApplicationId}/{deviceUdid}

application/json

POST

Apple

/setup/subscribe/notification/apple/{providerApplicationId}

application/json

Parameters

Type

Name

Value

Description

Path Variable

providerApplicationId

"string value"

The provider application Id

Request Body

(JSON)

{
  "device" : {
    "udid" : "a udid",
    "model" : "a model",
    "version" : "a version",
    "name" : "a push device name",
    "metadata" : "some metadata"
  },
  "deviceToken" : "a device token",
  "userId" : "a user id",
  "badge" : false,
  "alert" : true,
  "sound" : false
}

Json description of the device to subscribe and the configuration wanted

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

PushSubscriptionCreatedEvent
Field name	Field description
Description	A push subscription has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "pushSubscriptionOID" : "a push subscription OID", "type" : "PushSubscriptionCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

PUT

Apple

/setup/subscribe/notification/apple/{providerApplicationId}

application/json

GET

Apple

/setup/subscribe/notification/apple/{providerApplicationId}/{deviceUdid}

application/json

DELETE

Apple [DEPRECATED] since version 2018.3.3

/setup/subscribe/notification/apple/{providerApplicationId}/{deviceUdid}

application/json

GET

Devices

/setup/subscribe/notification/devices/{applicationId}

application/json

Parameters
Type	Name	Value	Description
Path Variable	applicationId	"string value"	The functional application Id

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "userId" : "a user id",
  "devices" : {
    "appleDevices" : [ {
      "subscriberOID" : "a subscriber OID",
      "device" : {
        "creationTime" : 1785140821921,
        "lastUpdateTime" : 1785140821922,
        "udid" : "a udid",
        "model" : "a model",
        "version" : "a version",
        "name" : "a push device name",
        "metadata" : "some metadata"
      }
    } ],
    "androidDevices" : [ {
      "subscriberOID" : "a subscriber OID",
      "device" : {
        "creationTime" : 1785140821922,
        "lastUpdateTime" : 1785140821922,
        "udid" : "a udid",
        "model" : "a model",
        "version" : "a version",
        "name" : "a push device name",
        "metadata" : "some metadata"
      }
    } ],
    "androidFcmDevices" : [ {
      "subscriberOID" : "a subscriber OID",
      "device" : {
        "creationTime" : 1785140821922,
        "lastUpdateTime" : 1785140821922,
        "udid" : "a udid",
        "model" : "a model",
        "version" : "a version",
        "name" : "a push device name",
        "metadata" : "some metadata"
      }
    } ],
    "windowsDevices" : [ {
      "subscriberOID" : "a subscriber OID",
      "device" : {
        "creationTime" : 1785140821922,
        "lastUpdateTime" : 1785140821922,
        "udid" : "a udid",
        "model" : "a model",
        "version" : "a version",
        "name" : "a push device name",
        "metadata" : "some metadata"
      }
    } ]
  }
} ]

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

DELETE Notification /setup/subscribe/notification/user/{userIdToUnsubscribe} application/json

Unsubscribe a user from the notification service for authenticated setup

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	userIdToUnsubscribe	"string value"	The user ID to unsubscribe

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

PushSubscriptionDeletedEvent
Field name	Field description
Description	A push subscription has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "pushSubscriptionOID" : "a push subscription OID", "type" : "PushSubscriptionDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DELETE Notification /setup/subscribe/notification/{subscriberOID} application/json

Unsubscribe a device from the notification service

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	subscriberOID	"string value"	The subscriber OID

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

PushSubscriptionDeletedEvent
Field name	Field description
Description	A push subscription has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "pushSubscriptionOID" : "a push subscription OID", "type" : "PushSubscriptionDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

DELETE

Notifications

/setup/subscribe/notification/all

application/json

Parameters
Type	Name	Value	Description
Request Parameter	deviceUdid	"string value"	The device Udid
Request Parameter	pushProvider	"string value"	The device provider
Request Parameter	applicationId	"string value"	The client application id

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

PushSubscriptionDeletedEvent
Field name	Field description
Description	A push subscription has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "pushSubscriptionOID" : "a push subscription OID", "type" : "PushSubscriptionDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

POST

Windows

/setup/subscribe/notification/windows/{providerApplicationId}

application/json

Parameters

Type

Name

Value

Description

Path Variable

providerApplicationId

"string value"

The provider application Id

Request Body

(JSON)

{
  "device" : {
    "udid" : "a udid",
    "model" : "a model",
    "version" : "a version",
    "name" : "a push device name",
    "metadata" : "some metadata"
  },
  "userId" : "a user id",
  "uri" : "a URI",
  "tile" : "NOW",
  "toast" : "QUARTER",
  "raw" : "HALF_QUARTER"
}

Json description of the device to subscribe and the configuration wanted

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

PushSubscriptionCreatedEvent
Field name	Field description
Description	A push subscription has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "pushSubscriptionOID" : "a push subscription OID", "type" : "PushSubscriptionCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

See Allowed Values

Raw
Name	Code	Meaning
NO_DELAY	-1	No raw notification delivered
NOW	0	Immediate delivery
HALF_QUARTER	450	A half quarter delay (450 seconds)
QUARTER	900	A quarter delay (900 seconds)

Tile
Name	Code	Meaning
NO_DELAY	-1	No tile notification delivered
NOW	0	Immediate delivery
HALF_QUARTER	450	A half quarter delay (450 seconds)
QUARTER	900	A quarter delay (900 seconds)

Toast
Name	Code	Meaning
NO_DELAY	-1	No toast notification delivered
NOW	0	Immediate delivery
HALF_QUARTER	450	A half quarter delay (450 seconds)
QUARTER	900	A quarter delay (900 seconds)

PUT

Windows

/setup/subscribe/notification/windows/{providerApplicationId}

application/json

Parameters

Type

Name

Value

Description

Path Variable

providerApplicationId

"string value"

The provider application Id

Request Body

(JSON)

{
  "device" : {
    "udid" : "a udid",
    "model" : "a model",
    "version" : "a version",
    "name" : "a push device name",
    "metadata" : "some metadata"
  },
  "userId" : "a user id",
  "uri" : "a URI",
  "oid" : "the mpns subscriber json wrapper UUID",
  "tile" : "NOW",
  "toast" : "QUARTER",
  "raw" : "HALF_QUARTER"
}

Json description of the device to update and the configuration wanted

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

See Allowed Values

Raw
Name	Code	Meaning
NO_DELAY	-1	No raw notification delivered
NOW	0	Immediate delivery
HALF_QUARTER	450	A half quarter delay (450 seconds)
QUARTER	900	A quarter delay (900 seconds)

Tile
Name	Code	Meaning
NO_DELAY	-1	No tile notification delivered
NOW	0	Immediate delivery
HALF_QUARTER	450	A half quarter delay (450 seconds)
QUARTER	900	A quarter delay (900 seconds)

Toast
Name	Code	Meaning
NO_DELAY	-1	No toast notification delivered
NOW	0	Immediate delivery
HALF_QUARTER	450	A half quarter delay (450 seconds)
QUARTER	900	A quarter delay (900 seconds)

GET

Windows

/setup/subscribe/notification/windows/{providerApplicationId}/{deviceUdid}

application/json

DELETE

Windows [DEPRECATED] since version 2018.3.3

/setup/subscribe/notification/windows/{providerApplicationId}/{deviceUdid}

application/json

Secrets

Expand commands

POST

Secret

/setup/secrets

application/json

PUT

Secret

/setup/secrets/{OID}

application/json

DELETE

Secret

/setup/secrets/{OID}

application/json

PUT

Secret

/setup/secrets/{OID}/value

application/json

GET

Secrets

/setup/secrets/scope/{scopeName}

application/json

Somfy CMS

Private tags : [ somfy ]

Expand commands

GET Account /setup/external/service/somfy/cms/myTahomaAccountURL application/json

Fetch an URL for the user's MyTahoma account

Access scope : enduser/*

> Test operation

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ExternalServiceURLEvent
Field name	Field description
Description	External service url event
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "serviceId" : "a service id", "url" : "a url", "type" : "ExternalServiceURLEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
serviceId	The service ID
setupOID	Setup OID
siteOID	Site OID
url	The requested URL

Third-Party

Expand commands

GET

Activated Models

/setup/thirdparty/activated

application/json

GET

Security status

/setup/thirdparty/model/{modelName}/security/status

application/json

POST

Security unlock

/setup/thirdparty/model/{modelName}/security/unlock

application/json

Zone

Expand commands

POST Items [DEPRECATED] since version 2018.3.3 /setup/zones/items application/json

Add items to a zone in user setup

Access scope : enduser/*

> Test operation

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a zone label",
  "type" : 0,
  "items" : [ {
    "itemType" : "device",
    "deviceOID" : "a device OID",
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
  } ],
  "externalOID" : "an external OID",
  "metadata" : "some metadata"
}

Json description of item list

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ZoneUpdatedEvent
Field name	Field description
Description	An existing zone has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "zoneOID" : "a zone OID", "zoneType" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "type" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
zoneOID	Zone OID

DELETE Items [DEPRECATED] since version 2018.3.3 /setup/zones/items application/json

Remove items from a zone in user setup

Access scope : enduser/*

> Test operation

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a zone label",
  "type" : 0,
  "items" : [ {
    "itemType" : "device",
    "deviceOID" : "a device OID",
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
  } ],
  "externalOID" : "an external OID",
  "metadata" : "some metadata",
  "oid" : "the zone UUID"
}

Json description of item list to remove

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

ZoneUpdatedEvent
Field name	Field description
Description	An existing zone has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "zoneOID" : "a zone OID", "zoneType" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "type" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
zoneOID	Zone OID

POST

Items

/setup/zones/{sourceZoneOID}/items/relocate/{targetZoneOID}

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

[ {
  "itemType" : "device",
  "deviceOID" : "a device OID",
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
} ]

Json description of item list to relocate

Path Variable

sourceZoneOID

"string value"

Source zone oid

Path Variable

targetZoneOID

"string value"

Target zone oid

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ZoneUpdatedEvent
Field name	Field description
Description	An existing zone has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "zoneOID" : "a zone OID", "zoneType" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "type" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
zoneOID	Zone OID

GET

Items

/setup/zones/{zoneOID}/items

application/json

POST

Items

/setup/zones/{zoneOID}/items

application/json

PUT

Items [DEPRECATED] since version 2018.3.3

/setup/zones/{zoneOID}/items

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a zone label",
  "type" : 0,
  "items" : [ {
    "itemType" : "device",
    "deviceOID" : "a device OID",
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
  } ],
  "externalOID" : "an external OID",
  "metadata" : "some metadata",
  "oid" : "the zone UUID"
}

Json description of item list to relocate

Path Variable

zoneOID

"string value"

Source zone oid

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

ZoneUpdatedEvent
Field name	Field description
Description	An existing zone has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "zoneOID" : "a zone OID", "zoneType" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "type" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
zoneOID	Zone OID

DELETE

Items [DEPRECATED] since version 2018.3.3

/setup/zones/{zoneOID}/items

application/json

Parameters

Type

Name

Value

Description

Path Variable

zoneOID

"string value"

Request Body

(JSON)

[ {
  "itemType" : "device",
  "deviceOID" : "a device OID",
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
} ]

Json description of item list to remove

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

ZoneUpdatedEvent
Field name	Field description
Description	An existing zone has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "zoneOID" : "a zone OID", "zoneType" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "type" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
zoneOID	Zone OID

POST

Items

/setup/zones/{zoneOID}/items/_delete

application/json

Parameters

Type

Name

Value

Description

Path Variable

zoneOID

"string value"

Request Body

(JSON)

[ {
  "itemType" : "device",
  "deviceOID" : "a device OID",
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
} ]

Json description of item list to remove

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

ZoneUpdatedEvent
Field name	Field description
Description	An existing zone has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "zoneOID" : "a zone OID", "zoneType" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "type" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
zoneOID	Zone OID

POST Zone /setup/zones application/json

Create zone in user setup

Access scope : enduser/*

> Test operation

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "label" : "a zone label",
  "type" : 0,
  "items" : [ {
    "itemType" : "device",
    "deviceOID" : "a device OID",
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
  } ],
  "externalOID" : "an external OID",
  "metadata" : "some metadata"
}

Json description of desired zone

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

ZoneCreatedEvent
Field name	Field description
Description	A new zone has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "zoneOID" : "a zone OID", "zoneType" : 1, "label" : "a zone created event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "type" : "ZoneCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
zoneOID	Zone OID

GET

Zone

/setup/zones/{zoneOID}

application/json

PUT

Zone

/setup/zones/{zoneOID}

application/json

DELETE Zone /setup/zones/{zoneOID} application/json

Delete a zone from user setup.

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Path Variable	zoneOID	"string value"	Zone OID to delete

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

ZoneDeletedEvent
Field name	Field description
Description	An existing zone has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "zoneOID" : "a zone OID", "type" : "ZoneDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID
zoneOID	Zone OID

PUT

Zone

/setup/zones/{zoneOID}/{type}/{label}

application/json

GET

Zones

/setup/zones

application/json

Setup Triggers

Private tags : [ setup-triggers ]

One or several effects can be triggered depending on a device state values and/or time conditions. This can be... defined in two ways:
	 -> in a sensor threshold
	 -> in a discrete sensor trigger

A sensor threshold is defined for one sensor on one state. Three effects can be defined (upperEffects, middleEffects, lowerEffects), each one is delimited by an upper bound (upperBound) and a lower bound (lowerBound). Those effects can be triggered with a delay (activationDelay).

To only define two effects, upper and lower bounds should have the same value. Executed effects will be the upper and the lower effects.

A discrete sensor trigger is also defined for one sensor on one state. Several effects can be defined, each one is triggered with a delay (activationDelay) when state riches a set discrete value.

An effect can be composed of action group effects (actionGroupEffect), action group with alert effects (actionGroupWithAlertEffect), default trigger alert effects (defaultTriggerAlertEffect) or alert effects (alertEffect). Difference between actionGroupWithAlertEffect, defaultTriggerAlertEffect and alertEffect is alert message and behavior of alertEffect are fully customizable.

Alerts can be sent through one or several channels (notificationType):
	 -> DASHBOARD: a message is displayed on the user dashboard
	 -> EMAIL: an email is sent to the user email address
	 -> SMS: a sms is sent to the user mobile phone
	 -> PUSH: a push message is sent to the user Apple, Android, Windows device (iPod, iPhone, iPad...)

All sensor triggers may have a name and can be always on (mode=1), off (mode=2) or scheduled (mode=3). Scheduling is from a time (enabledFromLocalHours, enabledFromLocalMinutes) to another time (enabledToLocalHours, enabledToLocalMinutes) in one or several days of the week (enabledDays: list of day ranks, starting from 1 to 7, 1 standing for Sunday).

It is possible to allow the execution of the associated actions when the sensor parameter is activated through the allowExecuteOnEnabled attribute (executions are allowed by default).

When creating or updating the trigger one may want to trigger executions through the allowExecuteOnUpdate attribute (executions are not allowed by default).
Read more

Expand commands

POST

Setup Trigger

/triggers

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "ifThenSetupTrigger" : {
    "label" : "an if then setup trigger label",
    "serverSide" : true,
    "mode" : 1,
    "schedulingIntervals" : [ {
      "weeklySchedule" : {
        "startMinutes" : 9,
        "stopMinutes" : 15,
        "startOffset" : 14,
        "stopOffset" : 12,
        "startAngle" : 8,
        "stopAngle" : 13,
        "startType" : "DUSK",
        "stopType" : "DAWN",
        "startAlwaysBefore" : "07:50",
        "stopAlwaysBefore" : "23:50",
        "startAlwaysAfter" : "06:50",
        "stopAlwaysAfter" : "21:50",
        "startDay" : 2,
        "stopDay" : 6
      }
    } ],
    "allowExecuteOnEnabled" : false,
    "metadata" : "some metadata",
    "allowFromUnknownValue" : true,
    "rootConditionBlock" : {
      "orBlock" : {
        "activationDelay" : 1,
        "deactivationDelay" : 4,
        "subConditionBlocks" : [ {
          "staticDeviceStateCondition" : {
            "activationDelay" : 1,
            "deactivationDelay" : 7,
            "stateName" : "a state name",
            "operator" : "BETWEEN_INCLUSIVE",
            "value1" : "a value1",
            "value2" : "a value2",
            "objectPath" : "an object path",
            "type" : "EVENT_BASED",
            "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>"
          }
        } ]
      }
    },
    "effects" : [ {
      "actionGroupEffect" : {
        "actionGroupOID" : "an action group OID",
        "localActionGroup" : {
          "label" : "a managed action group label",
          "metadata" : "some metadata",
          "shortcut" : false,
          "notificationTypeMask" : 1,
          "notificationCondition" : "ON_SUCCESS",
          "notificationText" : "a notification text",
          "notificationTitle" : "a notification title",
          "targetEmailAddresses" : [ "some target email addresses" ],
          "targetPhoneNumbers" : [ "some target phone numbers" ],
          "targetPushSubscriptions" : [ "some target push subscriptions" ],
          "actions" : [ {
            "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
            "commands" : [ {
              "type" : 1,
              "name" : "a command name",
              "parameters" : [ "some parameters" ],
              "sensitiveParametersIndexes" : [ 1 ],
              "authentication" : "an authentication",
              "delay" : 1,
              "lockLevel" : 20
            } ]
          } ]
        }
      }
    } ],
    "usingTriggerModeFlag" : false
  }
}

Json description of the setup trigger to create

Request Parameter

allowExecuteOnCreate

false

(Optional)

Allow execution of trigger effects on create

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "setupTriggerId" : "a setup trigger id", "setupTriggerOID" : "a setup trigger OID" }

HTTP Status Code
Code	Message	Meaning
201	CREATED	The request has been fulfilled and resulted in a new resource being created

Generated events on method call

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SetupTriggerCreationFailedEvent
Field name	Field description
Description	A setup trigger could not be created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "setupTriggerType" : 1, "setupTriggerOID" : "a setup trigger OID", "setupTriggerId" : "a setup trigger id", "type" : "SetupTriggerCreationFailedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
setupTriggerId	Setup trigger Id
setupTriggerOID	Setup trigger OID
setupTriggerType	Setup trigger type
siteOID	Site OID

SetupTriggerCreatedEvent
Field name	Field description
Description	A setup trigger has been created
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "setupTriggerType" : 1, "setupTriggerOID" : "a setup trigger OID", "setupTriggerId" : "a setup trigger id", "label" : "a setup trigger created event label", "metadata" : "some metadata", "mode" : 1, "sourceDeviceURLs" : [ "some source device URLs" ], "effects" : [ { "actionGroupEffect" : { "id" : "an id", "actionGroupOID" : "an action group OID", "localActionGroup" : { "creationTime" : 1785201548769, "lastUpdateTime" : 1785201548769, "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : true, "notificationTypeMask" : 1, "notificationCondition" : "ALWAYS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 13 } ] } ], "oid" : "the managed action group UUID" } } } ], "rootConditionBlock" : { "staticDeviceStateCondition" : { "blockId" : "a block id", "activationDelay" : 1, "deactivationDelay" : 16, "stateName" : "a state name", "operator" : "NOT_EQUALS", "value1" : "a value1", "value2" : "a value2", "objectPath" : "an object path", "type" : "RETRIGGERABLE_ON_STATE_TRANSITION", "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>" } }, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "type" : "SetupTriggerCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
setupTriggerId	Setup trigger Id
setupTriggerOID	Setup trigger OID
setupTriggerType	Setup trigger type
siteOID	Site OID

See Allowed Types

If-Then Setup Trigger Condition Block
If-Then Setup Trigger Condition Block
{ "andBlock" : { "activationDelay" : 1, "deactivationDelay" : 2, "subConditionBlocks" : [ { "staticDeviceStateCondition" : { "activationDelay" : 1, "deactivationDelay" : 5, "stateName" : "a state name", "operator" : "LOWER_THAN_OR_EQUAL", "value1" : "a value1", "value2" : "a value2", "objectPath" : "an object path", "type" : "EVENT_BASED", "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>" } } ] } }
{ "orBlock" : { "activationDelay" : 1, "deactivationDelay" : 2, "subConditionBlocks" : [ { "staticDeviceStateCondition" : { "activationDelay" : 1, "deactivationDelay" : 5, "stateName" : "a state name", "operator" : "LOWER_THAN_OR_EQUAL", "value1" : "a value1", "value2" : "a value2", "objectPath" : "an object path", "type" : "EVENT_BASED", "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>" } } ] } }
{ "staticDeviceStateCondition" : { "activationDelay" : 1, "deactivationDelay" : 4, "stateName" : "a state name", "operator" : "GREATER_THAN", "value1" : "a value1", "value2" : "a value2", "objectPath" : "an object path", "type" : "RETRIGGERABLE_ON_STATE_TRANSITION", "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>" } }
{ "dualDeviceStateCondition" : { "activationDelay" : 1, "deactivationDelay" : 3, "deviceURL1" : "<protocol>://<gatewayId>/<deviceAddress>", "stateName1" : "a state name1", "objectPath1" : "an object path1", "deviceURL2" : "<protocol>://<gatewayId>/<deviceAddress>", "stateName2" : "a state name2", "objectPath2" : "an object path2", "operator" : "LOWER_THAN" } }
{ "atLeastOneDeviceStateCondition" : { "activationDelay" : 1, "deactivationDelay" : 4, "stateName" : "a state name", "operator" : "GREATER_THAN", "value1" : "a value1", "value2" : "a value2", "objectPath" : "an object path", "type" : "RETRIGGERABLE_ON_STATE_TRANSITION", "deviceURLs" : [ "some device URLs" ] } }
{ "allDevicesStateCondition" : { "activationDelay" : 1, "deactivationDelay" : 4, "stateName" : "a state name", "operator" : "GREATER_THAN", "value1" : "a value1", "value2" : "a value2", "objectPath" : "an object path", "type" : "RETRIGGERABLE_ON_STATE_TRANSITION", "deviceURLs" : [ "some device URLs" ] } }

Scheduling Interval Type
Scheduling Interval Type
{ "annualSchedule" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 1, "startMonth" : 1, "stopDay" : 1, "stopMonth" : 1 } }
{ "weeklySchedule" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } }
{ "dailySchedule" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50" } }
{ "absoluteSchedule" : { "startMinutes" : 1, "startDay" : 1, "startMonth" : 1, "startYear" : 1, "stopMinutes" : 1, "stopDay" : 1, "stopMonth" : 1, "stopYear" : 1 } }
{ "dayType" : { "dayType" : "WORK_DAY", "mask" : "DAY_OFF_AT_HOME" } }
{ "weekDays" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "dayMask" : 1 } }
{ "weekHours" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "dayMask" : 1 } }
{ "annualWeekHours" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "dayMask" : 255, "startDay" : 1, "startMonth" : 1, "stopDay" : 6, "stopMonth" : 1 } }

Setup Trigger Type
Setup Trigger Type
{ "genericStateRegulationTrigger" : { "label" : "a generic state regulation trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "targetRegulationSchedulingIntervals" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 5, "stopMinutes" : 11, "startOffset" : 10, "stopOffset" : 8, "startAngle" : 4, "stopAngle" : 9, "startType" : "TIME", "stopType" : "DUSK", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "targetRegulationOverrides" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 22, "stopMinutes" : 28, "startOffset" : 27, "stopOffset" : 25, "startAngle" : 21, "stopAngle" : 26, "startType" : "DAWN", "stopType" : "TIME", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "regulationHysteresis" : 1, "regulatedStateName" : "a regulated state name", "updateTargetFunctionName" : "a update target function name", "regulationBusyStateName" : "a regulation busy state name" } }
{ "ovpThermostatRegulationTrigger" : { "label" : "a OVPThermostat regulation trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "targetRegulationSchedulingIntervals" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 13, "stopMinutes" : 19, "startOffset" : 18, "stopOffset" : 16, "startAngle" : 12, "stopAngle" : 17, "startType" : "DAWN", "stopType" : "TIME", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "targetRegulationOverrides" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 38, "stopMinutes" : 44, "startOffset" : 43, "stopOffset" : 41, "startAngle" : 37, "stopAngle" : 42, "startType" : "TIME", "stopType" : "DUSK", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "regulationHysteresis" : 1 } }
{ "genericCommandSchedulingTrigger" : { "label" : "a generic command scheduling trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : false, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "usingTriggerModeFlag" : true, "commandFunctionName" : "a command function name", "commandSchedules" : [ { "scheduleTimes" : [ { "dailyTime" : { "minutesOfDay" : 1 } } ], "parameters" : [ "some parameters" ], "label" : "a command schedule label", "enabled" : false } ], "stateRestrictions" : [ { "stateName" : "a state name", "stateValue" : "a state value" } ] } }
{ "genericPointToPointRegulationTrigger" : { "label" : "a generic point to point regulation trigger label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 5, "stopMinutes" : 11, "startOffset" : 10, "stopOffset" : 8, "startAngle" : 4, "stopAngle" : 9, "startType" : "TIME", "stopType" : "DUSK", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : false, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "sourceStateName" : "a source state name", "targetDeviceURL" : "a target device URL", "targetCommandName" : "a target command name", "adaptationFunction" : "an adaptation function", "executionLabel" : "an execution label" } }
{ "discreteTrigger" : { "label" : "a discrete trigger label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 9, "stopMinutes" : 15, "startOffset" : 14, "stopOffset" : 12, "startAngle" : 8, "stopAngle" : 13, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : false, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "stateName" : "a state name", "objectPath" : "an object path", "effectsList" : [ { "key" : "a key", "effects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_ERROR", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 6 } ] } ] } } } ] } ], "executeAlways" : false, "usingTriggerModeFlag" : true, "activationDelays" : { "map" : { "a map" : 17 } }, "deactivationDelays" : { "map" : { "a map" : 20 } } } }
{ "sensorThreshold" : { "label" : "a sensor threshold label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 18, "stopMinutes" : 24, "startOffset" : 23, "stopOffset" : 21, "startAngle" : 17, "stopAngle" : 22, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : true, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "stateName" : "a state name", "objectPath" : "an object path", "upperBound" : 14, "lowerBound" : 30, "upperEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_ERROR", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 6 } ] } ] } } } ], "middleEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ALWAYS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 28 } ] } ] } } } ], "lowerEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_ERROR", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 12 } ] } ] } } } ], "upperActivationDelay" : 1, "middleActivationDelay" : 1, "lowerActivationDelay" : 1, "upperDeactivationDelay" : 2, "middleDeactivationDelay" : 8, "lowerDeactivationDelay" : 16, "usingTriggerModeFlag" : true } }
{ "ifThenSetupTrigger" : { "label" : "an if then setup trigger label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 9, "stopMinutes" : 15, "startOffset" : 14, "stopOffset" : 12, "startAngle" : 8, "stopAngle" : 13, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : false, "metadata" : "some metadata", "allowFromUnknownValue" : true, "rootConditionBlock" : { "orBlock" : { "activationDelay" : 1, "deactivationDelay" : 4, "subConditionBlocks" : [ { "staticDeviceStateCondition" : { "activationDelay" : 1, "deactivationDelay" : 7, "stateName" : "a state name", "operator" : "BETWEEN_INCLUSIVE", "value1" : "a value1", "value2" : "a value2", "objectPath" : "an object path", "type" : "EVENT_BASED", "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>" } } ] } }, "effects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_SUCCESS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 20 } ] } ] } } } ], "usingTriggerModeFlag" : false } }
{ "delayedCommandsSchedulingTrigger" : { "label" : "a delayed commands scheduling trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commandCalls" : [ { "commandFunctionName" : "a command function name", "commandParameters" : [ "some command parameters" ] } ], "commandLabel" : "a command label", "commandMinutes" : 1, "commandDay" : 1, "commandMonth" : 1, "commandYear" : 1, "stateRestrictions" : [ { "stateName" : "a state name", "stateValue" : "a state value" } ], "usingTriggerModeFlag" : false } }

PUT

Setup Trigger

/triggers

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "ifThenSetupTrigger" : {
    "label" : "an if then setup trigger label",
    "serverSide" : true,
    "mode" : 1,
    "schedulingIntervals" : [ {
      "weeklySchedule" : {
        "startMinutes" : 9,
        "stopMinutes" : 15,
        "startOffset" : 14,
        "stopOffset" : 12,
        "startAngle" : 8,
        "stopAngle" : 13,
        "startType" : "DUSK",
        "stopType" : "DAWN",
        "startAlwaysBefore" : "07:50",
        "stopAlwaysBefore" : "23:50",
        "startAlwaysAfter" : "06:50",
        "stopAlwaysAfter" : "21:50",
        "startDay" : 2,
        "stopDay" : 6
      }
    } ],
    "allowExecuteOnEnabled" : false,
    "metadata" : "some metadata",
    "allowFromUnknownValue" : true,
    "rootConditionBlock" : {
      "orBlock" : {
        "activationDelay" : 1,
        "deactivationDelay" : 4,
        "subConditionBlocks" : [ {
          "staticDeviceStateCondition" : {
            "activationDelay" : 1,
            "deactivationDelay" : 7,
            "stateName" : "a state name",
            "operator" : "BETWEEN_INCLUSIVE",
            "value1" : "a value1",
            "value2" : "a value2",
            "objectPath" : "an object path",
            "type" : "EVENT_BASED",
            "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>"
          }
        } ]
      }
    },
    "effects" : [ {
      "actionGroupEffect" : {
        "actionGroupOID" : "an action group OID",
        "localActionGroup" : {
          "label" : "a managed action group label",
          "metadata" : "some metadata",
          "shortcut" : false,
          "notificationTypeMask" : 1,
          "notificationCondition" : "ON_SUCCESS",
          "notificationText" : "a notification text",
          "notificationTitle" : "a notification title",
          "targetEmailAddresses" : [ "some target email addresses" ],
          "targetPhoneNumbers" : [ "some target phone numbers" ],
          "targetPushSubscriptions" : [ "some target push subscriptions" ],
          "actions" : [ {
            "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
            "commands" : [ {
              "type" : 1,
              "name" : "a command name",
              "parameters" : [ "some parameters" ],
              "sensitiveParametersIndexes" : [ 1 ],
              "authentication" : "an authentication",
              "delay" : 1,
              "lockLevel" : 20
            } ]
          } ],
          "oid" : "the managed action group UUID"
        }
      }
    } ],
    "usingTriggerModeFlag" : false,
    "oid" : "the if then setup trigger UUID"
  }
}

Json description of the setup trigger to update

Request Parameter

allowExecuteOnUpdate

false

(Optional)

Allow execution of trigger effects on update

Request Parameter

preventLockLevelReset

false

(Optional)

Do not reset command lock levels

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SetupTriggerUpdatedEvent
Field name	Field description
Description	A setup trigger has been updated
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "setupTriggerType" : 1, "setupTriggerOID" : "a setup trigger OID", "setupTriggerId" : "a setup trigger id", "label" : "a setup trigger updated event label", "metadata" : "some metadata", "mode" : 1, "sourceDeviceURLs" : [ "some source device URLs" ], "effects" : [ { "actionGroupEffect" : { "id" : "an id", "actionGroupOID" : "an action group OID", "localActionGroup" : { "creationTime" : 1785201548778, "lastUpdateTime" : 1785201548778, "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : true, "notificationTypeMask" : 1, "notificationCondition" : "ALWAYS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 13 } ] } ], "oid" : "the managed action group UUID" } } } ], "rootConditionBlock" : { "staticDeviceStateCondition" : { "blockId" : "a block id", "activationDelay" : 1, "deactivationDelay" : 16, "stateName" : "a state name", "operator" : "NOT_EQUALS", "value1" : "a value1", "value2" : "a value2", "objectPath" : "an object path", "type" : "RETRIGGERABLE_ON_STATE_TRANSITION", "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>" } }, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "type" : "SetupTriggerUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
setupTriggerId	Setup trigger Id
setupTriggerOID	Setup trigger OID
setupTriggerType	Setup trigger type
siteOID	Site OID

See Allowed Types

Scheduling Interval Type
Scheduling Interval Type
{ "annualSchedule" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 1, "startMonth" : 1, "stopDay" : 1, "stopMonth" : 1 } }
{ "weeklySchedule" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } }
{ "dailySchedule" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50" } }
{ "absoluteSchedule" : { "startMinutes" : 1, "startDay" : 1, "startMonth" : 1, "startYear" : 1, "stopMinutes" : 1, "stopDay" : 1, "stopMonth" : 1, "stopYear" : 1 } }
{ "dayType" : { "dayType" : "WORK_DAY", "mask" : "DAY_OFF_AT_HOME" } }
{ "weekDays" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "dayMask" : 1 } }
{ "weekHours" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "dayMask" : 1 } }
{ "annualWeekHours" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "dayMask" : 255, "startDay" : 1, "startMonth" : 1, "stopDay" : 6, "stopMonth" : 1 } }

Setup Trigger Type
Setup Trigger Type
{ "genericStateRegulationTrigger" : { "label" : "a generic state regulation trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "targetRegulationSchedulingIntervals" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 5, "stopMinutes" : 11, "startOffset" : 10, "stopOffset" : 8, "startAngle" : 4, "stopAngle" : 9, "startType" : "TIME", "stopType" : "DUSK", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "targetRegulationOverrides" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 22, "stopMinutes" : 28, "startOffset" : 27, "stopOffset" : 25, "startAngle" : 21, "stopAngle" : 26, "startType" : "DAWN", "stopType" : "TIME", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "regulationHysteresis" : 1, "regulatedStateName" : "a regulated state name", "updateTargetFunctionName" : "a update target function name", "regulationBusyStateName" : "a regulation busy state name" } }
{ "ovpThermostatRegulationTrigger" : { "label" : "a OVPThermostat regulation trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "targetRegulationSchedulingIntervals" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 13, "stopMinutes" : 19, "startOffset" : 18, "stopOffset" : 16, "startAngle" : 12, "stopAngle" : 17, "startType" : "DAWN", "stopType" : "TIME", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "targetRegulationOverrides" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 38, "stopMinutes" : 44, "startOffset" : 43, "stopOffset" : 41, "startAngle" : 37, "stopAngle" : 42, "startType" : "TIME", "stopType" : "DUSK", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "regulationHysteresis" : 1 } }
{ "genericCommandSchedulingTrigger" : { "label" : "a generic command scheduling trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : false, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "usingTriggerModeFlag" : true, "commandFunctionName" : "a command function name", "commandSchedules" : [ { "scheduleTimes" : [ { "dailyTime" : { "minutesOfDay" : 1 } } ], "parameters" : [ "some parameters" ], "label" : "a command schedule label", "enabled" : false } ], "stateRestrictions" : [ { "stateName" : "a state name", "stateValue" : "a state value" } ] } }
{ "genericPointToPointRegulationTrigger" : { "label" : "a generic point to point regulation trigger label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 5, "stopMinutes" : 11, "startOffset" : 10, "stopOffset" : 8, "startAngle" : 4, "stopAngle" : 9, "startType" : "TIME", "stopType" : "DUSK", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : false, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "sourceStateName" : "a source state name", "targetDeviceURL" : "a target device URL", "targetCommandName" : "a target command name", "adaptationFunction" : "an adaptation function", "executionLabel" : "an execution label" } }
{ "discreteTrigger" : { "label" : "a discrete trigger label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 9, "stopMinutes" : 15, "startOffset" : 14, "stopOffset" : 12, "startAngle" : 8, "stopAngle" : 13, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : false, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "stateName" : "a state name", "objectPath" : "an object path", "effectsList" : [ { "key" : "a key", "effects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_ERROR", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 6 } ] } ] } } } ] } ], "executeAlways" : false, "usingTriggerModeFlag" : true, "activationDelays" : { "map" : { "a map" : 17 } }, "deactivationDelays" : { "map" : { "a map" : 20 } } } }
{ "sensorThreshold" : { "label" : "a sensor threshold label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 18, "stopMinutes" : 24, "startOffset" : 23, "stopOffset" : 21, "startAngle" : 17, "stopAngle" : 22, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : true, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "stateName" : "a state name", "objectPath" : "an object path", "upperBound" : 14, "lowerBound" : 30, "upperEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_ERROR", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 6 } ] } ] } } } ], "middleEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ALWAYS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 28 } ] } ] } } } ], "lowerEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_ERROR", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 12 } ] } ] } } } ], "upperActivationDelay" : 1, "middleActivationDelay" : 1, "lowerActivationDelay" : 1, "upperDeactivationDelay" : 2, "middleDeactivationDelay" : 8, "lowerDeactivationDelay" : 16, "usingTriggerModeFlag" : true } }
{ "ifThenSetupTrigger" : { "label" : "an if then setup trigger label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 9, "stopMinutes" : 15, "startOffset" : 14, "stopOffset" : 12, "startAngle" : 8, "stopAngle" : 13, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : false, "metadata" : "some metadata", "allowFromUnknownValue" : true, "rootConditionBlock" : { "orBlock" : { "activationDelay" : 1, "deactivationDelay" : 4, "subConditionBlocks" : [ { "staticDeviceStateCondition" : { "activationDelay" : 1, "deactivationDelay" : 7, "stateName" : "a state name", "operator" : "BETWEEN_INCLUSIVE", "value1" : "a value1", "value2" : "a value2", "objectPath" : "an object path", "type" : "EVENT_BASED", "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>" } } ] } }, "effects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_SUCCESS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 20 } ] } ] } } } ], "usingTriggerModeFlag" : false } }
{ "delayedCommandsSchedulingTrigger" : { "label" : "a delayed commands scheduling trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commandCalls" : [ { "commandFunctionName" : "a command function name", "commandParameters" : [ "some command parameters" ] } ], "commandLabel" : "a command label", "commandMinutes" : 1, "commandDay" : 1, "commandMonth" : 1, "commandYear" : 1, "stateRestrictions" : [ { "stateName" : "a state name", "stateValue" : "a state value" } ], "usingTriggerModeFlag" : false } }

POST

Setup Trigger

/triggers/test

application/json

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "ifThenSetupTrigger" : {
    "label" : "an if then setup trigger label",
    "serverSide" : true,
    "mode" : 1,
    "schedulingIntervals" : [ {
      "weeklySchedule" : {
        "startMinutes" : 9,
        "stopMinutes" : 15,
        "startOffset" : 14,
        "stopOffset" : 12,
        "startAngle" : 8,
        "stopAngle" : 13,
        "startType" : "DUSK",
        "stopType" : "DAWN",
        "startAlwaysBefore" : "07:50",
        "stopAlwaysBefore" : "23:50",
        "startAlwaysAfter" : "06:50",
        "stopAlwaysAfter" : "21:50",
        "startDay" : 2,
        "stopDay" : 6
      }
    } ],
    "allowExecuteOnEnabled" : false,
    "metadata" : "some metadata",
    "allowFromUnknownValue" : true,
    "rootConditionBlock" : {
      "orBlock" : {
        "activationDelay" : 1,
        "deactivationDelay" : 4,
        "subConditionBlocks" : [ {
          "staticDeviceStateCondition" : {
            "activationDelay" : 1,
            "deactivationDelay" : 7,
            "stateName" : "a state name",
            "operator" : "BETWEEN_INCLUSIVE",
            "value1" : "a value1",
            "value2" : "a value2",
            "objectPath" : "an object path",
            "type" : "EVENT_BASED",
            "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>"
          }
        } ]
      }
    },
    "effects" : [ {
      "actionGroupEffect" : {
        "actionGroupOID" : "an action group OID",
        "localActionGroup" : {
          "label" : "a managed action group label",
          "metadata" : "some metadata",
          "shortcut" : false,
          "notificationTypeMask" : 1,
          "notificationCondition" : "ON_SUCCESS",
          "notificationText" : "a notification text",
          "notificationTitle" : "a notification title",
          "targetEmailAddresses" : [ "some target email addresses" ],
          "targetPhoneNumbers" : [ "some target phone numbers" ],
          "targetPushSubscriptions" : [ "some target push subscriptions" ],
          "actions" : [ {
            "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
            "commands" : [ {
              "type" : 1,
              "name" : "a command name",
              "parameters" : [ "some parameters" ],
              "sensitiveParametersIndexes" : [ 1 ],
              "authentication" : "an authentication",
              "delay" : 1,
              "lockLevel" : 20
            } ]
          } ]
        }
      }
    } ],
    "usingTriggerModeFlag" : false
  }
}

Json description of the setup trigger to test

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

PUT

Setup Trigger

/triggers/test/discrete/{triggerOID}

application/json

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "targetValue" : "a target value" }	The name of the effect to test
Path Variable	triggerOID	"string value"

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

See Allowed Types

Scheduling Interval Type
Scheduling Interval Type
{ "annualSchedule" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 1, "startMonth" : 1, "stopDay" : 1, "stopMonth" : 1 } }
{ "weeklySchedule" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } }
{ "dailySchedule" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50" } }
{ "absoluteSchedule" : { "startMinutes" : 1, "startDay" : 1, "startMonth" : 1, "startYear" : 1, "stopMinutes" : 1, "stopDay" : 1, "stopMonth" : 1, "stopYear" : 1 } }
{ "dayType" : { "dayType" : "WORK_DAY", "mask" : "DAY_OFF_AT_HOME" } }
{ "weekDays" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "dayMask" : 1 } }
{ "weekHours" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "dayMask" : 1 } }
{ "annualWeekHours" : { "startMinutes" : 3, "stopMinutes" : 9, "startOffset" : 8, "stopOffset" : 6, "startAngle" : 2, "stopAngle" : 7, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "dayMask" : 255, "startDay" : 1, "startMonth" : 1, "stopDay" : 6, "stopMonth" : 1 } }

Setup Trigger Type
Setup Trigger Type
{ "genericStateRegulationTrigger" : { "label" : "a generic state regulation trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "targetRegulationSchedulingIntervals" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 5, "stopMinutes" : 11, "startOffset" : 10, "stopOffset" : 8, "startAngle" : 4, "stopAngle" : 9, "startType" : "TIME", "stopType" : "DUSK", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "targetRegulationOverrides" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 22, "stopMinutes" : 28, "startOffset" : 27, "stopOffset" : 25, "startAngle" : 21, "stopAngle" : 26, "startType" : "DAWN", "stopType" : "TIME", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "regulationHysteresis" : 1, "regulatedStateName" : "a regulated state name", "updateTargetFunctionName" : "a update target function name", "regulationBusyStateName" : "a regulation busy state name" } }
{ "ovpThermostatRegulationTrigger" : { "label" : "a OVPThermostat regulation trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "targetRegulationSchedulingIntervals" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 13, "stopMinutes" : 19, "startOffset" : 18, "stopOffset" : 16, "startAngle" : 12, "stopAngle" : 17, "startType" : "DAWN", "stopType" : "TIME", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "targetRegulationOverrides" : [ { "target" : "ECO", "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 38, "stopMinutes" : 44, "startOffset" : 43, "stopOffset" : 41, "startAngle" : 37, "stopAngle" : 42, "startType" : "TIME", "stopType" : "DUSK", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ] } ], "regulationHysteresis" : 1 } }
{ "genericCommandSchedulingTrigger" : { "label" : "a generic command scheduling trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : false, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "usingTriggerModeFlag" : true, "commandFunctionName" : "a command function name", "commandSchedules" : [ { "scheduleTimes" : [ { "dailyTime" : { "minutesOfDay" : 1 } } ], "parameters" : [ "some parameters" ], "label" : "a command schedule label", "enabled" : false } ], "stateRestrictions" : [ { "stateName" : "a state name", "stateValue" : "a state value" } ] } }
{ "genericPointToPointRegulationTrigger" : { "label" : "a generic point to point regulation trigger label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 5, "stopMinutes" : 11, "startOffset" : 10, "stopOffset" : 8, "startAngle" : 4, "stopAngle" : 9, "startType" : "TIME", "stopType" : "DUSK", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : false, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "sourceStateName" : "a source state name", "targetDeviceURL" : "a target device URL", "targetCommandName" : "a target command name", "adaptationFunction" : "an adaptation function", "executionLabel" : "an execution label" } }
{ "discreteTrigger" : { "label" : "a discrete trigger label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 9, "stopMinutes" : 15, "startOffset" : 14, "stopOffset" : 12, "startAngle" : 8, "stopAngle" : 13, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : false, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "stateName" : "a state name", "objectPath" : "an object path", "effectsList" : [ { "key" : "a key", "effects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_ERROR", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 6 } ] } ] } } } ] } ], "executeAlways" : false, "usingTriggerModeFlag" : true, "activationDelays" : { "map" : { "a map" : 17 } }, "deactivationDelays" : { "map" : { "a map" : 20 } } } }
{ "sensorThreshold" : { "label" : "a sensor threshold label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 18, "stopMinutes" : 24, "startOffset" : 23, "stopOffset" : 21, "startAngle" : 17, "stopAngle" : 22, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : true, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "stateName" : "a state name", "objectPath" : "an object path", "upperBound" : 14, "lowerBound" : 30, "upperEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_ERROR", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 6 } ] } ] } } } ], "middleEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ALWAYS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 28 } ] } ] } } } ], "lowerEffects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_ERROR", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 12 } ] } ] } } } ], "upperActivationDelay" : 1, "middleActivationDelay" : 1, "lowerActivationDelay" : 1, "upperDeactivationDelay" : 2, "middleDeactivationDelay" : 8, "lowerDeactivationDelay" : 16, "usingTriggerModeFlag" : true } }
{ "ifThenSetupTrigger" : { "label" : "an if then setup trigger label", "serverSide" : true, "mode" : 1, "schedulingIntervals" : [ { "weeklySchedule" : { "startMinutes" : 9, "stopMinutes" : 15, "startOffset" : 14, "stopOffset" : 12, "startAngle" : 8, "stopAngle" : 13, "startType" : "DUSK", "stopType" : "DAWN", "startAlwaysBefore" : "07:50", "stopAlwaysBefore" : "23:50", "startAlwaysAfter" : "06:50", "stopAlwaysAfter" : "21:50", "startDay" : 2, "stopDay" : 6 } } ], "allowExecuteOnEnabled" : false, "metadata" : "some metadata", "allowFromUnknownValue" : true, "rootConditionBlock" : { "orBlock" : { "activationDelay" : 1, "deactivationDelay" : 4, "subConditionBlocks" : [ { "staticDeviceStateCondition" : { "activationDelay" : 1, "deactivationDelay" : 7, "stateName" : "a state name", "operator" : "BETWEEN_INCLUSIVE", "value1" : "a value1", "value2" : "a value2", "objectPath" : "an object path", "type" : "EVENT_BASED", "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>" } } ] } }, "effects" : [ { "actionGroupEffect" : { "actionGroupOID" : "an action group OID", "localActionGroup" : { "label" : "a managed action group label", "metadata" : "some metadata", "shortcut" : false, "notificationTypeMask" : 1, "notificationCondition" : "ON_SUCCESS", "notificationText" : "a notification text", "notificationTitle" : "a notification title", "targetEmailAddresses" : [ "some target email addresses" ], "targetPhoneNumbers" : [ "some target phone numbers" ], "targetPushSubscriptions" : [ "some target push subscriptions" ], "actions" : [ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commands" : [ { "type" : 1, "name" : "a command name", "parameters" : [ "some parameters" ], "sensitiveParametersIndexes" : [ 1 ], "authentication" : "an authentication", "delay" : 1, "lockLevel" : 20 } ] } ] } } } ], "usingTriggerModeFlag" : false } }
{ "delayedCommandsSchedulingTrigger" : { "label" : "a delayed commands scheduling trigger label", "serverSide" : true, "mode" : 1, "metadata" : "some metadata", "allowFromUnknownValue" : true, "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "commandCalls" : [ { "commandFunctionName" : "a command function name", "commandParameters" : [ "some command parameters" ] } ], "commandLabel" : "a command label", "commandMinutes" : 1, "commandDay" : 1, "commandMonth" : 1, "commandYear" : 1, "stateRestrictions" : [ { "stateName" : "a state name", "stateValue" : "a state value" } ], "usingTriggerModeFlag" : false } }

GET

Setup Trigger

/triggers/{type}/{triggerOID}

application/json

Parameters
Type	Name	Value	Description
Path Variable	type	"string value"	Setup trigger type
Path Variable	triggerOID	"string value"	Setup trigger OID

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "ifThenSetupTrigger" : {
    "creationTime" : 1785140822181,
    "lastUpdateTime" : 1785140822203,
    "label" : "an if then setup trigger label",
    "serverSide" : true,
    "mode" : 1,
    "schedulingIntervals" : [ {
      "weeklySchedule" : {
        "startMinutes" : 9,
        "stopMinutes" : 15,
        "startOffset" : 14,
        "stopOffset" : 12,
        "startAngle" : 8,
        "stopAngle" : 13,
        "startType" : "DUSK",
        "stopType" : "DAWN",
        "startAlwaysBefore" : "07:50",
        "stopAlwaysBefore" : "23:50",
        "startAlwaysAfter" : "06:50",
        "stopAlwaysAfter" : "21:50",
        "startDay" : 2,
        "stopDay" : 6
      }
    } ],
    "allowExecuteOnEnabled" : false,
    "id" : "an id",
    "metadata" : "some metadata",
    "allowFromUnknownValue" : true,
    "rootConditionBlock" : {
      "orBlock" : {
        "blockId" : "a block id",
        "activationDelay" : 1,
        "deactivationDelay" : 4,
        "subConditionBlocks" : [ {
          "staticDeviceStateCondition" : {
            "blockId" : "a block id",
            "activationDelay" : 1,
            "deactivationDelay" : 7,
            "stateName" : "a state name",
            "operator" : "BETWEEN_INCLUSIVE",
            "value1" : "a value1",
            "value2" : "a value2",
            "objectPath" : "an object path",
            "type" : "EVENT_BASED",
            "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>"
          }
        } ]
      }
    },
    "effects" : [ {
      "actionGroupEffect" : {
        "id" : "an id",
        "actionGroupOID" : "an action group OID",
        "localActionGroup" : {
          "creationTime" : 1785140822203,
          "lastUpdateTime" : 1785140822203,
          "label" : "a managed action group label",
          "metadata" : "some metadata",
          "shortcut" : false,
          "notificationTypeMask" : 1,
          "notificationCondition" : "ON_SUCCESS",
          "notificationText" : "a notification text",
          "notificationTitle" : "a notification title",
          "targetEmailAddresses" : [ "some target email addresses" ],
          "targetPhoneNumbers" : [ "some target phone numbers" ],
          "targetPushSubscriptions" : [ "some target push subscriptions" ],
          "actions" : [ {
            "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
            "commands" : [ {
              "type" : 1,
              "name" : "a command name",
              "parameters" : [ "some parameters" ],
              "sensitiveParametersIndexes" : [ 1 ],
              "authentication" : "an authentication",
              "delay" : 1,
              "lockLevel" : 20
            } ]
          } ],
          "oid" : "the managed action group UUID"
        }
      }
    } ],
    "usingTriggerModeFlag" : false,
    "oid" : "the if then setup trigger UUID"
  }
}

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

See Allowed Values

Setup Trigger Type
Name	Code	Meaning
genericStateRegulationTrigger	genericStateRegulationTrigger	genericStateRegulationTrigger
ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger
genericCommandSchedulingTrigger	genericCommandSchedulingTrigger	genericCommandSchedulingTrigger
genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger
discreteTrigger	discreteTrigger	discreteTrigger
sensorThreshold	sensorThreshold	sensorThreshold
ifThenSetupTrigger	ifThenSetupTrigger	ifThenSetupTrigger
delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger
discreteSensorTrigger	discreteSensorTrigger	discreteSensorTrigger
eventTrigger	eventTrigger	eventTrigger
delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger

DELETE

Setup Trigger

/triggers/{type}/{triggerOID}

application/json

Parameters
Type	Name	Value	Description
Path Variable	type	"string value"	Setup trigger type
Path Variable	triggerOID	"string value"	If then setup trigger OID to delete

HTTP Status Code
Code	Message	Meaning
204	NO_CONTENT	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation

Generated events on method call

GatewaySynchronizationEndedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has completed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

GatewaySynchronizationStartedEvent
Field name	Field description
Description	A data synchronization sequence between the gateway and the server has started
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "type" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

SetupTriggerDeletedEvent
Field name	Field description
Description	A setup trigger has been deleted
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "setupTriggerType" : 1, "setupTriggerOID" : "a setup trigger OID", "type" : "SetupTriggerDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
setupTriggerOID	Setup trigger OID
setupTriggerType	Setup trigger type
siteOID	Site OID

See Allowed Values

Setup Trigger Type
Name	Code	Meaning
genericStateRegulationTrigger	genericStateRegulationTrigger	genericStateRegulationTrigger
ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger
genericCommandSchedulingTrigger	genericCommandSchedulingTrigger	genericCommandSchedulingTrigger
genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger
discreteTrigger	discreteTrigger	discreteTrigger
sensorThreshold	sensorThreshold	sensorThreshold
ifThenSetupTrigger	ifThenSetupTrigger	ifThenSetupTrigger
delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger
discreteSensorTrigger	discreteSensorTrigger	discreteSensorTrigger
eventTrigger	eventTrigger	eventTrigger
delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger

PUT

Setup Trigger activation mode

/triggers/{type}/{triggerOID}/activation/{mode}

application/json

Parameters
Type	Name	Value	Description
Path Variable	type	"string value"	Setup trigger type
Path Variable	mode	1	Activation mode. It can be one of : -> 1 : always on -> 2 : off -> 3 : scheduled
Path Variable	triggerOID	"string value"	Setup trigger OID to update
Request Parameter	allowExecuteOnUpdate	false	(Optional) Allow execution of trigger effects on update

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

SetupTriggerModeChangedEvent
Field name	Field description
Description	The scheduling mode of a setup trigger has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "setupTriggerType" : 1, "setupTriggerOID" : "a setup trigger OID", "newMode" : 1, "type" : "SetupTriggerModeChangedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
setupTriggerOID	Setup trigger OID
setupTriggerType	Setup trigger type
siteOID	Site OID

SetupTriggerModeChangeFailedEvent
Field name	Field description
Description	The scheduling mode of a setup trigger could not be changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartners" : [ "some owning partners" ], "setupTriggerType" : 1, "setupTriggerOID" : "a setup trigger OID", "type" : "SetupTriggerModeChangeFailedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
setupTriggerOID	Setup trigger OID
setupTriggerType	Setup trigger type
siteOID	Site OID

See Allowed Values

Setup Trigger Type
Name	Code	Meaning
genericStateRegulationTrigger	genericStateRegulationTrigger	genericStateRegulationTrigger
ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger
genericCommandSchedulingTrigger	genericCommandSchedulingTrigger	genericCommandSchedulingTrigger
genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger
discreteTrigger	discreteTrigger	discreteTrigger
sensorThreshold	sensorThreshold	sensorThreshold
ifThenSetupTrigger	ifThenSetupTrigger	ifThenSetupTrigger
delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger
discreteSensorTrigger	discreteSensorTrigger	discreteSensorTrigger
eventTrigger	eventTrigger	eventTrigger
delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger

GET

Setup Trigger status

/triggers/{type}/{triggerOID}/status

application/json

Parameters
Type	Name	Value	Description
Path Variable	type	"string value"	Setup trigger type
Path Variable	triggerOID	"string value"	Setup trigger OID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "triggerOID" : "a trigger OID", "mode" : 1, "schedulingIntervalsStatus" : [ false ], "subTriggersStatus" : [ { "triggerName" : "a trigger name", "active" : true, "executeAlways" : false } ] }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

See Allowed Values

Setup Trigger Type
Name	Code	Meaning
genericStateRegulationTrigger	genericStateRegulationTrigger	genericStateRegulationTrigger
ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger
genericCommandSchedulingTrigger	genericCommandSchedulingTrigger	genericCommandSchedulingTrigger
genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger
discreteTrigger	discreteTrigger	discreteTrigger
sensorThreshold	sensorThreshold	sensorThreshold
ifThenSetupTrigger	ifThenSetupTrigger	ifThenSetupTrigger
delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger
discreteSensorTrigger	discreteSensorTrigger	discreteSensorTrigger
eventTrigger	eventTrigger	eventTrigger
delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger

GET

Setup Triggers

/triggers

application/json

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "ifThenSetupTrigger" : {
    "creationTime" : 1785140822206,
    "lastUpdateTime" : 1785140822207,
    "label" : "an if then setup trigger label",
    "serverSide" : true,
    "mode" : 1,
    "schedulingIntervals" : [ {
      "weeklySchedule" : {
        "startMinutes" : 9,
        "stopMinutes" : 15,
        "startOffset" : 14,
        "stopOffset" : 12,
        "startAngle" : 8,
        "stopAngle" : 13,
        "startType" : "DUSK",
        "stopType" : "DAWN",
        "startAlwaysBefore" : "07:50",
        "stopAlwaysBefore" : "23:50",
        "startAlwaysAfter" : "06:50",
        "stopAlwaysAfter" : "21:50",
        "startDay" : 2,
        "stopDay" : 6
      }
    } ],
    "allowExecuteOnEnabled" : false,
    "id" : "an id",
    "metadata" : "some metadata",
    "allowFromUnknownValue" : true,
    "rootConditionBlock" : {
      "orBlock" : {
        "blockId" : "a block id",
        "activationDelay" : 1,
        "deactivationDelay" : 4,
        "subConditionBlocks" : [ {
          "staticDeviceStateCondition" : {
            "blockId" : "a block id",
            "activationDelay" : 1,
            "deactivationDelay" : 7,
            "stateName" : "a state name",
            "operator" : "BETWEEN_INCLUSIVE",
            "value1" : "a value1",
            "value2" : "a value2",
            "objectPath" : "an object path",
            "type" : "EVENT_BASED",
            "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>"
          }
        } ]
      }
    },
    "effects" : [ {
      "actionGroupEffect" : {
        "id" : "an id",
        "actionGroupOID" : "an action group OID",
        "localActionGroup" : {
          "creationTime" : 1785140822207,
          "lastUpdateTime" : 1785140822207,
          "label" : "a managed action group label",
          "metadata" : "some metadata",
          "shortcut" : false,
          "notificationTypeMask" : 1,
          "notificationCondition" : "ON_SUCCESS",
          "notificationText" : "a notification text",
          "notificationTitle" : "a notification title",
          "targetEmailAddresses" : [ "some target email addresses" ],
          "targetPhoneNumbers" : [ "some target phone numbers" ],
          "targetPushSubscriptions" : [ "some target push subscriptions" ],
          "actions" : [ {
            "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
            "commands" : [ {
              "type" : 1,
              "name" : "a command name",
              "parameters" : [ "some parameters" ],
              "sensitiveParametersIndexes" : [ 1 ],
              "authentication" : "an authentication",
              "delay" : 1,
              "lockLevel" : 20
            } ]
          } ],
          "oid" : "the managed action group UUID"
        }
      }
    } ],
    "usingTriggerModeFlag" : false,
    "oid" : "the if then setup trigger UUID"
  }
} ]

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

GET

Setup Triggers by type

/triggers/{type}

application/json

Parameters
Type	Name	Value	Description
Path Variable	type	"string value"	Setup trigger type

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "ifThenSetupTrigger" : {
    "creationTime" : 1785140822206,
    "lastUpdateTime" : 1785140822207,
    "label" : "an if then setup trigger label",
    "serverSide" : true,
    "mode" : 1,
    "schedulingIntervals" : [ {
      "weeklySchedule" : {
        "startMinutes" : 9,
        "stopMinutes" : 15,
        "startOffset" : 14,
        "stopOffset" : 12,
        "startAngle" : 8,
        "stopAngle" : 13,
        "startType" : "DUSK",
        "stopType" : "DAWN",
        "startAlwaysBefore" : "07:50",
        "stopAlwaysBefore" : "23:50",
        "startAlwaysAfter" : "06:50",
        "stopAlwaysAfter" : "21:50",
        "startDay" : 2,
        "stopDay" : 6
      }
    } ],
    "allowExecuteOnEnabled" : false,
    "id" : "an id",
    "metadata" : "some metadata",
    "allowFromUnknownValue" : true,
    "rootConditionBlock" : {
      "orBlock" : {
        "blockId" : "a block id",
        "activationDelay" : 1,
        "deactivationDelay" : 4,
        "subConditionBlocks" : [ {
          "staticDeviceStateCondition" : {
            "blockId" : "a block id",
            "activationDelay" : 1,
            "deactivationDelay" : 7,
            "stateName" : "a state name",
            "operator" : "BETWEEN_INCLUSIVE",
            "value1" : "a value1",
            "value2" : "a value2",
            "objectPath" : "an object path",
            "type" : "EVENT_BASED",
            "deviceURL" : "<protocol>://<gatewayId>/<deviceAddress>"
          }
        } ]
      }
    },
    "effects" : [ {
      "actionGroupEffect" : {
        "id" : "an id",
        "actionGroupOID" : "an action group OID",
        "localActionGroup" : {
          "creationTime" : 1785140822207,
          "lastUpdateTime" : 1785140822207,
          "label" : "a managed action group label",
          "metadata" : "some metadata",
          "shortcut" : false,
          "notificationTypeMask" : 1,
          "notificationCondition" : "ON_SUCCESS",
          "notificationText" : "a notification text",
          "notificationTitle" : "a notification title",
          "targetEmailAddresses" : [ "some target email addresses" ],
          "targetPhoneNumbers" : [ "some target phone numbers" ],
          "targetPushSubscriptions" : [ "some target push subscriptions" ],
          "actions" : [ {
            "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
            "commands" : [ {
              "type" : 1,
              "name" : "a command name",
              "parameters" : [ "some parameters" ],
              "sensitiveParametersIndexes" : [ 1 ],
              "authentication" : "an authentication",
              "delay" : 1,
              "lockLevel" : 20
            } ]
          } ],
          "oid" : "the managed action group UUID"
        }
      }
    } ],
    "usingTriggerModeFlag" : false,
    "oid" : "the if then setup trigger UUID"
  }
} ]

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

See Allowed Values

Setup Trigger Type
Name	Code	Meaning
genericStateRegulationTrigger	genericStateRegulationTrigger	genericStateRegulationTrigger
ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger
genericCommandSchedulingTrigger	genericCommandSchedulingTrigger	genericCommandSchedulingTrigger
genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger
discreteTrigger	discreteTrigger	discreteTrigger
sensorThreshold	sensorThreshold	sensorThreshold
ifThenSetupTrigger	ifThenSetupTrigger	ifThenSetupTrigger
delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger
discreteSensorTrigger	discreteSensorTrigger	discreteSensorTrigger
eventTrigger	eventTrigger	eventTrigger
delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger

GET

Setup Triggers status

/triggers/{type}/status

application/json

Parameters
Type	Name	Value	Description
Path Variable	type	"string value"	Setup trigger type

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "triggerOID" : "a trigger OID", "mode" : 1, "schedulingIntervalsStatus" : [ false ], "subTriggersStatus" : [ { "triggerName" : "a trigger name", "active" : true, "executeAlways" : false } ] } ]

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

See Allowed Values

Setup Trigger Type
Name	Code	Meaning
genericStateRegulationTrigger	genericStateRegulationTrigger	genericStateRegulationTrigger
ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger	ovpThermostatRegulationTrigger
genericCommandSchedulingTrigger	genericCommandSchedulingTrigger	genericCommandSchedulingTrigger
genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger	genericPointToPointRegulationTrigger
discreteTrigger	discreteTrigger	discreteTrigger
sensorThreshold	sensorThreshold	sensorThreshold
ifThenSetupTrigger	ifThenSetupTrigger	ifThenSetupTrigger
delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger	delayedCommandsSchedulingTrigger
discreteSensorTrigger	discreteSensorTrigger	discreteSensorTrigger
eventTrigger	eventTrigger	eventTrigger
delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger	delayedCommandSchedulingTrigger

GET

Setup trigger status

/triggers/status

application/json

PUT Setup trigger status /triggers/status application/json

Update trigger status.

Access scope : enduser/*

> Test operation

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "enabled" : false }	Setup trigger status

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

Generated events on method call

GatewayFunctionChangedEvent
Field name	Field description
Description	One of the gateway function has changed
JSON	{ "eventTime" : 2, "siteOID" : "a site OID", "setupOID" : "a setup OID", "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "functionType" : 1, "enabled" : false, "type" : "GatewayFunctionChangedEvent" }
enabled	Indicate if function is enabled or disabled
functionType	Updated function
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
setupOID	Setup OID
siteOID	Site OID

Terms of use

Expand commands

Accounts management

Expand commands

POST

TermsOfUse

/termsOfUse/{gatewayId}/accept/{token}

application/json

POST

TermsOfUse

/termsOfUse/{gatewayId}/decline/{token}

application/json

Utils

Expand commands

Location utils

Expand commands

GET

Location Details by postcode

/utils/location/countries/{countryNameOrCode}/postcodes/{postcode}/cities

application/json

Parameters
Type	Name	Value	Description
Path Variable	countryNameOrCode	"string value"	The country name or code
Path Variable	postcode	"string value"	The postcode

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "city" : "a city", "country" : "a country", "postalCode" : "a postal code", "secondaryZone" : false, "latitude" : 0.12345, "longitude" : 0.12345 } ]

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

See Allowed Values

Supported countries names/codes
Name	Code	Meaning
Albania	AL	Albania
Algeria	DZ	Algeria
Andorra	AD	Andorra
Armenia	AM	Armenia
Australia	AU	Australia
Austria	AT	Austria
Azerbaijan	AZ	Azerbaijan
Belarus	BY	Belarus
Belgium	BE	Belgium
Bosnia and Herzegovina	BA	Bosnia and Herzegovina
Brazil	BR	Brazil
Bulgaria	BG	Bulgaria
Canada	CA	Canada
Chile	CL	Chile
China	CN	China
Croatia	HR	Croatia
Cyprus	CY	Cyprus
CzechRepublic	CZ	Czech Republic
Denmark	DK	Denmark
Egypt	EG	Egypt
Estonia	EE	Estonia
Fiji	FJ	Fiji
Finland	FI	Finland
France	FR	France
French Guiana	GF	French Guiana
French Polynesia	PF	French Polynesia
Georgia	GE	Georgia
Germany	DE	Germany
Greece	GR	Greece
Guadeloupe	GP	Guadeloupe
Hungary	HU	Hungary
Hong Kong	HK	Hong Kong
India	IN	India
Indonesia	ID	Indonesia
Ireland	IE	Ireland
Israel	IL	Israel
Italy	IT	Italy
Japan	JP	Japan
Jordan	JO	Jordan
Kazakhstan	KZ	Kazakhstan
Kuwait	KW	Kuwait
Kyrgyzstan	KG	Kyrgyzstan
Latvia	LV	Latvia
Lebanon	LB	Lebanon
Liechtenstein	LI	Liechtenstein
Lithuania	LT	Lithuania
Luxembourg	LU	Luxembourg
Macedonia	MK	Macedonia
Malaysia	MY	Malaysia
Malta	MT	Malta
Martinique	MQ	Martinique
Mauritius Island	MU	Mauritius
Mayotte	YT	Mayotte
Mexico	MX	Mexico
Moldova	MD	Moldova
Monaco	MC	Monaco
Montenegro	ME	Montenegro
Morocco	MA	Morocco
Netherlands	NL	Netherlands
New Caledonia	NC	New Caledonia
New Zealand	NZ	New Zealand
Norway	NO	Norway
State of Palestine	PS	Palestine
Republic of the Philippines	PH	Philippines
Poland	PL	Poland
Portugal	PT	Portugal
Qatar	QA	Qatar
Reunion Island	RE	Reunion
Romania	RO	Romania
Russia	RU	Russia
Saint Barthelemy	BL	Saint Barth�lemy
SaudiArabia	SA	Saudi Arabia
Serbia	RS	Serbia
Singapore	SG	Singapore
Slovakia	SK	Slovakia
Slovenia	SI	Slovenia
SouthAfrica	ZA	South Africa
South Korea	KR	South Korea
Spain	ES	Spain
Sweden	SE	Sweden
Switzerland	CH	Switzerland
Ta�wan	TW	Taiwan
Tajikistan	TJ	Tajikistan
Thailand	TH	Thailand
Tunisia	TN	Tunisia
Turkey	TR	Turkey
Ukraine	UA	Ukraine
UnitedArabEmirates	AE	United Arab Emirates
UnitedKingdom	GB	United Kingdom
USA	US	United States
Uzbekistan	UZ	Uzbekistan
Vietnam	VN	Vietnam

GET

Location Details by prefix

/utils/location/countries/{countryNameOrCode}/cities/{prefix}

application/json

Parameters
Type	Name	Value	Description
Path Variable	countryNameOrCode	"string value"	The country name or code
Path Variable	prefix	"string value"	The city name prefix

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "city" : "a city", "country" : "a country", "postalCode" : "a postal code", "secondaryZone" : false, "latitude" : 0.12345, "longitude" : 0.12345 } ]

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

See Allowed Values

Supported countries names/codes
Name	Code	Meaning
Albania	AL	Albania
Algeria	DZ	Algeria
Andorra	AD	Andorra
Armenia	AM	Armenia
Australia	AU	Australia
Austria	AT	Austria
Azerbaijan	AZ	Azerbaijan
Belarus	BY	Belarus
Belgium	BE	Belgium
Bosnia and Herzegovina	BA	Bosnia and Herzegovina
Brazil	BR	Brazil
Bulgaria	BG	Bulgaria
Canada	CA	Canada
Chile	CL	Chile
China	CN	China
Croatia	HR	Croatia
Cyprus	CY	Cyprus
CzechRepublic	CZ	Czech Republic
Denmark	DK	Denmark
Egypt	EG	Egypt
Estonia	EE	Estonia
Fiji	FJ	Fiji
Finland	FI	Finland
France	FR	France
French Guiana	GF	French Guiana
French Polynesia	PF	French Polynesia
Georgia	GE	Georgia
Germany	DE	Germany
Greece	GR	Greece
Guadeloupe	GP	Guadeloupe
Hungary	HU	Hungary
Hong Kong	HK	Hong Kong
India	IN	India
Indonesia	ID	Indonesia
Ireland	IE	Ireland
Israel	IL	Israel
Italy	IT	Italy
Japan	JP	Japan
Jordan	JO	Jordan
Kazakhstan	KZ	Kazakhstan
Kuwait	KW	Kuwait
Kyrgyzstan	KG	Kyrgyzstan
Latvia	LV	Latvia
Lebanon	LB	Lebanon
Liechtenstein	LI	Liechtenstein
Lithuania	LT	Lithuania
Luxembourg	LU	Luxembourg
Macedonia	MK	Macedonia
Malaysia	MY	Malaysia
Malta	MT	Malta
Martinique	MQ	Martinique
Mauritius Island	MU	Mauritius
Mayotte	YT	Mayotte
Mexico	MX	Mexico
Moldova	MD	Moldova
Monaco	MC	Monaco
Montenegro	ME	Montenegro
Morocco	MA	Morocco
Netherlands	NL	Netherlands
New Caledonia	NC	New Caledonia
New Zealand	NZ	New Zealand
Norway	NO	Norway
State of Palestine	PS	Palestine
Republic of the Philippines	PH	Philippines
Poland	PL	Poland
Portugal	PT	Portugal
Qatar	QA	Qatar
Reunion Island	RE	Reunion
Romania	RO	Romania
Russia	RU	Russia
Saint Barthelemy	BL	Saint Barth�lemy
SaudiArabia	SA	Saudi Arabia
Serbia	RS	Serbia
Singapore	SG	Singapore
Slovakia	SK	Slovakia
Slovenia	SI	Slovenia
SouthAfrica	ZA	South Africa
South Korea	KR	South Korea
Spain	ES	Spain
Sweden	SE	Sweden
Switzerland	CH	Switzerland
Ta�wan	TW	Taiwan
Tajikistan	TJ	Tajikistan
Thailand	TH	Thailand
Tunisia	TN	Tunisia
Turkey	TR	Turkey
Ukraine	UA	Ukraine
UnitedArabEmirates	AE	United Arab Emirates
UnitedKingdom	GB	United Kingdom
USA	US	United States
Uzbekistan	UZ	Uzbekistan
Vietnam	VN	Vietnam

POST

Location Details by prefix

/utils/location/countries/{countryNameOrCode}/cities/{prefix}

application/json

Parameters
Type	Name	Value	Description
Path Variable	countryNameOrCode	"string value"	The country name or code
Path Variable	prefix	"string value"	The city name prefix
Request Body	(JSON)	{ "includeSecondaryZones" : false }	(Optional) Location options

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "city" : "a city", "country" : "a country", "postalCode" : "a postal code", "secondaryZone" : false, "latitude" : 0.12345, "longitude" : 0.12345 } ]

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

See Allowed Values

Supported countries names/codes
Name	Code	Meaning
Albania	AL	Albania
Algeria	DZ	Algeria
Andorra	AD	Andorra
Armenia	AM	Armenia
Australia	AU	Australia
Austria	AT	Austria
Azerbaijan	AZ	Azerbaijan
Belarus	BY	Belarus
Belgium	BE	Belgium
Bosnia and Herzegovina	BA	Bosnia and Herzegovina
Brazil	BR	Brazil
Bulgaria	BG	Bulgaria
Canada	CA	Canada
Chile	CL	Chile
China	CN	China
Croatia	HR	Croatia
Cyprus	CY	Cyprus
CzechRepublic	CZ	Czech Republic
Denmark	DK	Denmark
Egypt	EG	Egypt
Estonia	EE	Estonia
Fiji	FJ	Fiji
Finland	FI	Finland
France	FR	France
French Guiana	GF	French Guiana
French Polynesia	PF	French Polynesia
Georgia	GE	Georgia
Germany	DE	Germany
Greece	GR	Greece
Guadeloupe	GP	Guadeloupe
Hungary	HU	Hungary
Hong Kong	HK	Hong Kong
India	IN	India
Indonesia	ID	Indonesia
Ireland	IE	Ireland
Israel	IL	Israel
Italy	IT	Italy
Japan	JP	Japan
Jordan	JO	Jordan
Kazakhstan	KZ	Kazakhstan
Kuwait	KW	Kuwait
Kyrgyzstan	KG	Kyrgyzstan
Latvia	LV	Latvia
Lebanon	LB	Lebanon
Liechtenstein	LI	Liechtenstein
Lithuania	LT	Lithuania
Luxembourg	LU	Luxembourg
Macedonia	MK	Macedonia
Malaysia	MY	Malaysia
Malta	MT	Malta
Martinique	MQ	Martinique
Mauritius Island	MU	Mauritius
Mayotte	YT	Mayotte
Mexico	MX	Mexico
Moldova	MD	Moldova
Monaco	MC	Monaco
Montenegro	ME	Montenegro
Morocco	MA	Morocco
Netherlands	NL	Netherlands
New Caledonia	NC	New Caledonia
New Zealand	NZ	New Zealand
Norway	NO	Norway
State of Palestine	PS	Palestine
Republic of the Philippines	PH	Philippines
Poland	PL	Poland
Portugal	PT	Portugal
Qatar	QA	Qatar
Reunion Island	RE	Reunion
Romania	RO	Romania
Russia	RU	Russia
Saint Barthelemy	BL	Saint Barth�lemy
SaudiArabia	SA	Saudi Arabia
Serbia	RS	Serbia
Singapore	SG	Singapore
Slovakia	SK	Slovakia
Slovenia	SI	Slovenia
SouthAfrica	ZA	South Africa
South Korea	KR	South Korea
Spain	ES	Spain
Sweden	SE	Sweden
Switzerland	CH	Switzerland
Ta�wan	TW	Taiwan
Tajikistan	TJ	Tajikistan
Thailand	TH	Thailand
Tunisia	TN	Tunisia
Turkey	TR	Turkey
Ukraine	UA	Ukraine
UnitedArabEmirates	AE	United Arab Emirates
UnitedKingdom	GB	United Kingdom
USA	US	United States
Uzbekistan	UZ	Uzbekistan
Vietnam	VN	Vietnam

GET

Location postcode pattern Details

/utils/location/countries/{countryNameOrCode}/postcodePattern

application/json

Parameters
Type	Name	Value	Description
Path Variable	countryNameOrCode	"string value"	The country name or code

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "country" : "a country", "countryCode" : "a country code", "readablePattern" : "a readable pattern" }

HTTP Status Code
Code	Message	Meaning
200	OK	The request has succeeded

See Allowed Values

Supported countries names/codes
Name	Code	Meaning
Albania	AL	Albania
Algeria	DZ	Algeria
Andorra	AD	Andorra
Armenia	AM	Armenia
Australia	AU	Australia
Austria	AT	Austria
Azerbaijan	AZ	Azerbaijan
Belarus	BY	Belarus
Belgium	BE	Belgium
Bosnia and Herzegovina	BA	Bosnia and Herzegovina
Brazil	BR	Brazil
Bulgaria	BG	Bulgaria
Canada	CA	Canada
Chile	CL	Chile
China	CN	China
Croatia	HR	Croatia
Cyprus	CY	Cyprus
CzechRepublic	CZ	Czech Republic
Denmark	DK	Denmark
Egypt	EG	Egypt
Estonia	EE	Estonia
Fiji	FJ	Fiji
Finland	FI	Finland
France	FR	France
French Guiana	GF	French Guiana
French Polynesia	PF	French Polynesia
Georgia	GE	Georgia
Germany	DE	Germany
Greece	GR	Greece
Guadeloupe	GP	Guadeloupe
Hungary	HU	Hungary
Hong Kong	HK	Hong Kong
India	IN	India
Indonesia	ID	Indonesia
Ireland	IE	Ireland
Israel	IL	Israel
Italy	IT	Italy
Japan	JP	Japan
Jordan	JO	Jordan
Kazakhstan	KZ	Kazakhstan
Kuwait	KW	Kuwait
Kyrgyzstan	KG	Kyrgyzstan
Latvia	LV	Latvia
Lebanon	LB	Lebanon
Liechtenstein	LI	Liechtenstein
Lithuania	LT	Lithuania
Luxembourg	LU	Luxembourg
Macedonia	MK	Macedonia
Malaysia	MY	Malaysia
Malta	MT	Malta
Martinique	MQ	Martinique
Mauritius Island	MU	Mauritius
Mayotte	YT	Mayotte
Mexico	MX	Mexico
Moldova	MD	Moldova
Monaco	MC	Monaco
Montenegro	ME	Montenegro
Morocco	MA	Morocco
Netherlands	NL	Netherlands
New Caledonia	NC	New Caledonia
New Zealand	NZ	New Zealand
Norway	NO	Norway
State of Palestine	PS	Palestine
Republic of the Philippines	PH	Philippines
Poland	PL	Poland
Portugal	PT	Portugal
Qatar	QA	Qatar
Reunion Island	RE	Reunion
Romania	RO	Romania
Russia	RU	Russia
Saint Barthelemy	BL	Saint Barth�lemy
SaudiArabia	SA	Saudi Arabia
Serbia	RS	Serbia
Singapore	SG	Singapore
Slovakia	SK	Slovakia
Slovenia	SI	Slovenia
SouthAfrica	ZA	South Africa
South Korea	KR	South Korea
Spain	ES	Spain
Sweden	SE	Sweden
Switzerland	CH	Switzerland
Ta�wan	TW	Taiwan
Tajikistan	TJ	Tajikistan
Thailand	TH	Thailand
Tunisia	TN	Tunisia
Turkey	TR	Turkey
Ukraine	UA	Ukraine
UnitedArabEmirates	AE	United Arab Emirates
UnitedKingdom	GB	United Kingdom
USA	US	United States
Uzbekistan	UZ	Uzbekistan
Vietnam	VN	Vietnam

Time utils

Expand commands

GET

Timezone Details

/utils/time/{timeZoneName}

application/json

End-User RESTful API Operations

Expand/collapse all

Hide/show deprecated

Action Groups

Generated events on method call

Generated events on method call

Generated events on method call

Action Groups Execution

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Authentication

Condition Groups

Generated events on method call

Generated events on method call

Generated events on method call

Configuration

August protocol

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Camera

Generated events on method call

Generated events on method call

Device Pairing Operations

Generated events on method call

Generated events on method call

Eliot protocol

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

EnOcean protocol

Generated events on method call

Generated events on method call

Generated events on method call

IO HomeControl protocol

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

KNX Over OGP Protocol

Modbus Protocol

Generated events on method call

OGCP cloud protocol

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

Generated events on method call

OpenDoors protocol

Generated events on method call