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

Create an action group

Access scope : Public

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

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

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

ActionGroupCreatedEvent
Field name	Field description
Description	An action group has been created
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ] } ] } ], "name" : "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

PUT

Action group

/actionGroups

application/json

Update an action group

Access scope : Public

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

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

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

ActionGroupUpdatedEvent
Field name	Field description
Description	An action group has been updated
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ] } ] } ], "name" : "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

GET

Action group

/actionGroups/{oid}

application/json

Retrieve a user-defined action group by OID

Access scope : Public

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

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1774337683190,
  "lastUpdateTime" : 1774337683190,
  "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

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

Delete an action group by OID

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

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

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

GET

Action groups

/actionGroups

application/json

Retrieve all user-defined actions groups

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "creationTime" : 1774337683190,
  "lastUpdateTime" : 1774337683190,
  "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

Action Groups Execution

Expand commands

POST

Action group execution

/exec/{actionGroupOID}

application/json

Launch a persistent action group by OID

Per-session rate-limit : 1 calls per 28min 48s period for all operations of the same category (exec)

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "name" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

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

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

POST

Action group execution

/exec/{actionGroupOID}/geolocated

application/json

Launch a persistent action group by OID in geolocated mode

The action group execution will be flagged as geolocated.

Per-session rate-limit : 1 calls per 28min 48s period for all operations of the same category (exec)

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

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

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

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

POST

Action group execution

/exec/{actionGroupOID}/internal

application/json

Launch a persistent action group by OID in internal mode

The action group execution will be flagged as internal and its result will not be stored in the setup execution history.
This is useful for automatic refresh operations that should not appear in the user history.

Per-session rate-limit : 1 calls per 28min 48s period for all operations of the same category (exec)

Access scope : Public

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

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

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

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

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

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

Cancel a running setup-level execution

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

GET

Current execution

/exec/current/{execId}

application/json

Get an action group execution currently running

Access scope : Public

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" : 1774337683185,
    "lastUpdateTime" : 1774337683185,
    "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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

GET

Current executions

/exec/current

application/json

Get action groups executions currently running

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "startTime" : 2,
  "owner" : "an owner",
  "actionGroup" : {
    "creationTime" : 1774337683184,
    "lastUpdateTime" : 1774337683184,
    "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 executions [DEPRECATED] since version 2018.3.3 /exec/current application/json

Cancel all running executions

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

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

Cancel all running setup-level executions

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

GET

Current executions

/exec/internalCurrent

application/json

Get action groups currently running

Allows fetching internal action group executions

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "startTime" : 2,
  "owner" : "an owner",
  "actionGroup" : {
    "creationTime" : 1774337683184,
    "lastUpdateTime" : 1774337683184,
    "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 technical execution [DEPRECATED] since version 2018.3.3

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

application/json

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

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

GET

Delayed trigger schedule execution

/exec/delayedTriggerSchedule/{triggerId}

application/json

Get a scheduled execution of delayed trigger

Access scope : Public

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

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "triggerId" : "a trigger id",
  "label" : "an action group scheduled execution label",
  "utcTime" : 2,
  "actionGroupOID" : "an action group OID",
  "randomTimeRange" : 1,
  "serverSideManaged" : false,
  "executionType" : "Immediate execution",
  "executionSubType" : "MANUAL_CONTROL"
}

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

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

Cancel a delayed trigger

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "triggerId" : "a trigger id", "name" : "DelayedTriggerCancelledEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
triggerId	Trigger id

GET

Delayed trigger schedule executions

/exec/delayedTriggerSchedule

application/json

Get the list of all scheduled executions of delayed trigger

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "triggerId" : "a trigger id",
  "label" : "an action group scheduled execution label",
  "utcTime" : 2,
  "actionGroupOID" : "an action group OID",
  "randomTimeRange" : 1,
  "serverSideManaged" : false,
  "executionType" : "Immediate execution",
  "executionSubType" : "MANUAL_CONTROL"
} ]

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

POST

Execute action group

/exec/apply

application/json

Execute a non-persistent action group

The executed action group does not have to be persisted on the server before use.

Per-session rate-limit : 1 calls per 28min 48s period for all operations of the same category (exec)

Access scope : Public

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

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

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

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

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

POST

Execute action group

/exec/apply/geolocated

application/json

Execute a non-persistent action group in geolocated mode

The executed action group does not have to be persisted on the server before use.
The action group execution will be flagged as geolocated.

Per-session rate-limit : 1 calls per 28min 48s period for all operations of the same category (exec)

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

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

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

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

POST

Execute action group

/exec/apply/highPriority

application/json

Execute a non-persistent action group in high-priority mode

The executed action group does not have to be persisted on the server before use.
The action group execution will have an higher priority, allowing to bypass some restrictions like forcing a blocked device.

Per-session rate-limit : 1 calls per 28min 48s period for all operations of the same category (exec)

Access scope : Public

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

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

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

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

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

POST

Execute action group

/exec/apply/internal

application/json

Execute a non-persistent action group in internal mode

The executed action group does not have to be persisted on the server before use.
The action group execution will be flagged as internal and its result will not be stored in the setup execution history.
This is useful for automatic refresh operations that should not appear in the user history.

Per-session rate-limit : 1 calls per 28min 48s period for all operations of the same category (exec)

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

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

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

POST

Optimize action group

/exec/optimizeWithProtocolGroups

application/json

Compute optimized version of a given execution: replace individual devices sharing the same command (name + parameters) by matching existing protocol groups to improve execution speed

Optimize action group

Access scope : Public

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" : 1774337683189,
  "lastUpdateTime" : 1774337683189,
  "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

Retrieve all scheduled action group executions

Get the list of all scheduled executions:
-> with a delay (executionType=?Delayed execution?)
-> at a time of the current day of the weekly planning (executionType=?Weekly planning? executionSubType=?TIME_TRIGGER?)
-> at dawn or dusk of the current day (executionType=?Weekly planning? executionSubType=?DAWN_TRIGGER? or executionSubType=?DUSK_TRIGGER?)

Access scope : Public

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

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "triggerId" : "a trigger id",
  "label" : "an action group scheduled execution label",
  "utcTime" : 2,
  "actionGroupOID" : "an action group OID",
  "randomTimeRange" : 1,
  "serverSideManaged" : false,
  "executionType" : "Immediate execution",
  "executionSubType" : "MANUAL_CONTROL"
} ]

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

POST

Schedule execution

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

application/json

Schedule an action group execution with a delay

Per-session rate-limit : 1 calls per 28min 48s period for all operations of the same category (exec)

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

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

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

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

GroupTriggeredEvent
Field name	Field description
Description	An action group has been triggered and is currently in execution
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "triggerId" : "a trigger id", "triggerType" : "a trigger type", "actionGroupOID" : "an action group OID", "execId" : "an exec id", "name" : "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
triggerId	Trigger id
triggerType	Trigger type

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

GET

Schedule executions

/exec/schedule

application/json

Retrieve all scheduled action groups executions

Get the list of all scheduled executions:
-> with a delay (executionType=?Delayed execution?)
-> at a time of the current day of the weekly planning (executionType=?Weekly planning? executionSubType=?TIME_TRIGGER?)
-> at dawn or dusk of the current day (executionType=?Weekly planning? executionSubType=?DAWN_TRIGGER? or executionSubType=?DUSK_TRIGGER?)

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "triggerId" : "a trigger id",
  "label" : "an action group scheduled execution label",
  "utcTime" : 2,
  "actionGroupOID" : "an action group OID",
  "randomTimeRange" : 1,
  "serverSideManaged" : false,
  "executionType" : "Immediate execution",
  "executionSubType" : "MANUAL_CONTROL"
} ]

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

Authentication

Expand commands

GET

Authorization

/oauth2/applications/authorized

application/json

Get a list of all authorized applications for the current setup

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "clientName" : "a client name",
  "clientId" : "a client id",
  "scopes" : "some scopes",
  "accessTokenNextExpirationTime" : 1774337683200,
  "refreshTokenNextExpirationTime" : 1774337683200,
  "enabled" : false
} ]

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

DELETE

Authorization

/oauth2/applications/authorized/{clientId}

application/json

Revoke an authorized application

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	clientId	"string value"	oauth2 client 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

PUT

Authorization

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

application/json

Disable an authorized application

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	clientId	"string value"	oauth2 client ID

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

PUT

Authorization

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

application/json

Enable an authorized application

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	clientId	"string value"	oauth2 client ID

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

GET

Authorization

/oauth2/authorization

application/json

Get an OAuth2 authorization code

Access scope : Public

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

Create a condition group

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" ] } } ], "name" : "ConditionGroupCreatedEvent" }
conditionGroupOID	Condition group OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

PUT Condition group /conditionGroups application/json

Update a condition group

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" ] } } ], "name" : "ConditionGroupUpdatedEvent" }
conditionGroupOID	Condition group OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Condition group

/conditionGroups/{oid}

application/json

Retrieve a condition group by OID

Access scope : Public

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

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1774337682751,
  "lastUpdateTime" : 1774337682755,
  "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"
}

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

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

Delete a condition group by OID

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "conditionGroupOID" : "a condition group OID", "name" : "ConditionGroupDeletedEvent" }
conditionGroupOID	Condition group OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Condition group

/conditionGroups/{oid}/evaluate

application/json

Evaluate a condition group

Access scope : Public

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

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "evaluationStatus" : "FAILED",
  "evaluationTime" : 1774337682757,
  "failedDevices" : [ "some failed devices" ],
  "invalidatingDevices" : [ "some invalidating devices" ],
  "ignoredControllables" : [ "some ignored controllables" ]
}

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

GET

Condition groups

/conditionGroups

application/json

Retrieve all user-defined condition groups

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "creationTime" : 1774337682755,
  "lastUpdateTime" : 1774337682755,
  "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"
} ]

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

Configuration

Expand commands

August protocol

Private tags : [ august-config ]

Expand commands

POST

August create authentication URL

/config/august/createAuthenticationURL/{redirectURL}

application/json

Return an URL to use for August authentication. At the end of the authentication process, the user will be redirected to the given {redirectURL}

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	redirectURL	"string value"	OAuth redirect URL
Request Body	(JSON)	{ "applicationId" : "an application id" }	(Optional)

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

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

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

Return the list of the gateways candidates

Access scope : Public

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

Generated events on method call

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

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

PUT Authentication /config/august/tokens application/json

Refresh current access token if necessary

Access scope : Public

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

Generated events on method call

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

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

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

Start a discover August gateway

Access scope : Public

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

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

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

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

Start discover August devices

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

Camera

Private tags : [ camera-config ]

Expand commands

POST

Camera

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

application/json

Pair and configure a camera

Access scope : Public

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

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

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

DELETE

Camera

/config/{gatewayId}/camera/unused

application/json

Delete discovered but unpaired cameras for a given gateway

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	Gateway 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

POST

Camera

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

application/json

Set Wifi settings of a paired camera

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

GET

Camera candidates

/config/{gatewayId}/camera/candidates

application/json

Get discovered cameras that may be paired to the gateway. This operation should be started after the LAN discovery completes.

Data on camera are:
	 -> name: camera name
	 -> description: camera descrip
	 -> deviceAddress: camera address on the gateway
	 -> cameraIpOrFqdn: indicates the IP address or the FQDN of the camera on the LAN
	 -> type: camera type. 1 stands for generic camera, 2 for Domis camera
	 -> lockType: lock type. 0 stands for available (not locked), 1 for locked by an alarm system, 2 for locked by a gateway and 3 indicates that camera version is outdated
	 -> wifiEnabled: indicates if wifi is enabled on the camera

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	Gateway id to which camera has to be paired

Response

Type

Name

Value

Description

Response 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
} ]

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

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

Get active commissioning codes on given protocol

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "code" : "a code", "metadata" : "some metadata", "extraFields" : { "some extra fields" : "some extra fields" } } ]

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

POST

Commissioning

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

application/json

Add one or more device commissioning code(s) on given protocol for a future pairing procedure. The limit for zigbee protocol is 127

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID
Request Body	(JSON)	[ { "code" : "a code", "metadata" : "some metadata", "commissioningId" : "a commissioning id" } ]	The device commissioning codes to add

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

DELETE

Commissioning

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

application/json

Remove all device commissioning codes on given protocol

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID

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

DELETE

Commissioning

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

application/json

Remove a device commissioning code on given protocol

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	code	"string value"	The device commissioning code to remove

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

POST

Commissioning

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

application/json

Import saved device commissioning codes to the actual codes list

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID

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

GET

Commissioning

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

application/json

Get saved commissioning codes on given protocol

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "code" : "a code", "metadata" : "some metadata", "extraFields" : { "some extra fields" : "some extra fields" } } ]

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

POST

Commissioning

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

application/json

Add one or more device saved commissioning code(s) on given protocol for a future pairing procedure

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID
Request Body	(JSON)	[ { "code" : "a code", "metadata" : "some metadata", "commissioningId" : "a commissioning id" } ]	The device commissioning codes to add

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

DELETE

Commissioning

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

application/json

Remove all saved device commissioning codes on given protocol

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID

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

DELETE

Commissioning

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

application/json

Remove a device saved commissioning code on given protocol

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	code	"string value"	The device commissioning code to remove

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

POST

Device

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

application/json

This operation allows to create a device. This operation is useful to add RTS devices, RTD alarm system and EnOcean actuators

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Devices

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

application/json

Get addresses of partial devices on given protocol

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "address" : "an address", "creationTime" : 1774337683205 } ]

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

DELETE

Devices

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

application/json

This operation allows to purge partially discovered raw devices (with status PARTIAL)

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
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

PurgePartialRawDevicesEvent
Field name	Field description
Description	Partial raw device purge is complete
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "deletedRawDevicesCount" : 1, "name" : "PurgePartialRawDevicesEvent" }
deletedRawDevicesCount	Deleted devices count
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type

DELETE

Devices

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

application/json

This operation allows to purge a partial raw device

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	deviceAddress	"string value"	The device address to purge

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

POST

Initialization

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

application/json

Initialize the protocol, and create a stack if needed

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	protocolType	1	The protocol type
Path Variable	gatewayId	"string value"	The gateway ID

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "type" : "GATEWAY_EXEC", "parentRef" : "a parent ref", "id" : "an id", "context" : "a context" }

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

Eliot protocol

Private tags : [ eliot-config ]

Expand commands

PUT Authentication /config/eliot/tokens application/json

Refresh current access token if necessary

Access scope : Public

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

Generated events on method call

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

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

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

Start a discover Eliot gateway

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "name" : "EliotDiscoverGatewayFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

POST Configuration /config/eliot/discoverGateways application/json

Send get a list of all user's gateways

Access scope : Public

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

Generated events on method call

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

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

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

Start discover Eliot devices

Access scope : Public

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

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

POST

Eliot create authentication URL

/config/eliot/createAuthenticationURL/{redirectURL}

application/json

Return an URL to use for Eliot authentication. At the end of the authentication process, the user will be redirected to the given {redirectURL}

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	redirectURL	"string value"	OAuth redirect URL
Request Body	(JSON)	{ "applicationId" : "an application id" }	(Optional)

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

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

EnOcean protocol

Private tags : [ enocean-config ]

Expand commands

GET

Device address

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

application/json

Return next available EnOcean device address for a given device type

Access scope : Public

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

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

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

POST

Learning device procedure [DEPRECATED] since version 2018.3.4

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

application/json

Start an EnOcean learning device procedure (pair a new device indicating the device reference). Useful for devices using generic profiles (require a manual specification).
DEPRECATED: use commands on enocean stack

Access scope : Public

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

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

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

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

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

Start an EnOcean learning procedure.
DEPRECATED: use commands on enocean stack

Access scope : Public

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

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

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

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

IO HomeControl protocol

Private tags : [ io-config ]

Expand commands

POST

Actuators

/config/{gatewayId}/io/setConfigState

application/json

This operation allows to set configuration state of one or more IO node

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Request Body	(JSON)	{ "actuatorAddresses" : [ "some actuator addresses" ], "searchForController" : false, "state" : 1 }	Options

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

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

POST

Atlantic

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

application/json

This operation forces a device to stop twinning procedure (only supported by Atlantic Electrical heater with adjustable temperature setpoint devices)

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	deviceAddress	"string value"	The device address (must be an Atlantic Electrical heater with adjustable temperature setpoint device)

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

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

POST

Controller

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

application/json

This operation allows to send a system table to a controller

Access scope : Public

Parameters

Type

Name

Value

Description

Path Variable

gatewayId

"string value"

The gateway ID

Path Variable

controllerAddress

"string value"

Controller address (or an associated actuator address for multi-node systems)

Request Body

(JSON)

{
  "actuatorAddresses" : [ "some actuator addresses" ],
  "sendStackMaster" : false
}

Options

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

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

POST

Device

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

application/json

This operation asks the device to open itself in RCM

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

POST

Gas Pulse Sensor

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

application/json

Set the settings of a IO gas pulse sensor

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	deviceAddress	"string value"	Gas pulse sensor device address
Request Body	(JSON)	{ "usedForCooking" : false, "usedForDHW" : true, "peopleCount" : 1 }	Json description of the gas pulse sensor settings

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "changed" : false }

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

POST

Generic Pulse Sensor

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

application/json

Start the IO generic pulse sensor discover procedure

Access scope : Public

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

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

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup 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

This operation allows to retrieve the IO security key from a control point with feedback function and to send it to the entire installation

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

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

This operation allows to send the current IO security key

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "name" : "IOChangedKeyEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type

POST

Key

/config/{gatewayId}/io/sendIOKeyToDevices

application/json

This operation allows to send the current IO security key to specified devices

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

POST

Sensor

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

application/json

Unsubscribe an IO sensor from the installation

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

KNX Over OGP Protocol

Private tags : [ ogpknx-config ]

Expand commands

POST

KNX over OGP import

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

application/json

Import KNX installation file

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	Id of the gateway
Request Parameter	file	<Uploaded File> (multipart encoded body)

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

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

Modbus Protocol

Private tags : [ modbus-config ]

Expand commands

POST

Discover

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

application/json

Start the Modbus actuators discover procedure

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

POST

Discover modules

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

application/json

Start the Modbus modules discover procedure

Access scope : Public

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

OGCP cloud protocol

Expand commands

POST

Create OAuth2 authorization URL

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

application/json

Return an URL to use for OAuth2 authorization workflow. At the end of the authentication process, the user will be redirected to the given {redirectUrl}

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	cloudId	"string value"	The OGCP cloud ID
Request Body	(JSON)	{ "redirectURL" : "a redirect URL", "applicationId" : "an application id" }

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

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

POST

Discover Device

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

application/json

Start a discovery of a device. Device commissioning key must be passed in request body. Only works on clouds using device-level integration mode.

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "cloudId" : "a cloud id", "deviceId" : "a device id", "name" : "OGCPDiscoverDeviceCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

POST

Discover Site

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

application/json

Start a discovery of a specific site. If multi-sites is not supported, siteId should be 'default'. Only works on clouds using site-level integration mode.

Access scope : Public

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

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

OGCPDiscoverSiteFailedEvent
Field name	Field description
Description	A device discovery operation has failed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "cloudId" : "a cloud id", "siteId" : "a site id", "name" : "OGCPDiscoverSiteFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup 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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "cloudId" : "a cloud id", "sites" : [ { "siteId" : "a site id", "label" : "a OGCPSite reference label" } ], "name" : "OGCPDiscoverSitesCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

GET

List Instances

/config/ogcp/instances

application/json

Get a list of all available OGCP instances on that server

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "integrationMode" : "DEVICE_LEVEL",
  "cloudId" : "a cloud id",
  "authMode" : "OAUTH2_PASSWORD_GRANT",
  "eventSupport" : false,
  "multiSiteSupport" : false,
  "cloudAdapter" : true,
  "offerName" : "an offer name"
} ]

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

POST

OAuth2 Password grant

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

application/json

Get new oauth tokens from user credentials. Only works on clouds using site-level integration mode

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	cloudId	"string value"	The OGCP cloud ID
Request Body	(JSON)	{ "userName" : "a user name", "userPassword" : "a user password", "applicationId" : "an application id" }

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

POST

Pair Device

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

application/json

Transmit device pairing informations to the third-party Cloud. Only works on clouds using device-level integration mode and supporting pairing requests.

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" }, "name" : "OGCPDevicePairingCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

POST

Pair Devices

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

application/json

Transmit device pairing informations to the third-party Cloud. Only works on clouds using device-level integration mode and supporting pairing requests.

Access scope : Public

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

OGCPDevicePairingCompletedEvent
Field name	Field description
Description	A device pairing operation has successfully completed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" }, "name" : "OGCPDevicePairingCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

OGCPDevicePairingFailedEvent
Field name	Field description
Description	A device pairing operation has failed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "cloudId" : "a cloud id", "deviceId" : "a device id", "name" : "OGCPDevicePairingFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup 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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "cloudId" : "a cloud id", "name" : "OGCPTokensRefreshCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

OpenDoors protocol

Private tags : [ opendoors-config ]

Expand commands

POST Authentication /config/opendoors/tokens application/json

Generate OAuth2 tokens from credentials

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "name" : "OpenDoorsGenerateOAuthTokensFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

POST

Discover [DEPRECATED] since version 2019.1

/config/opendoors/discover

application/json

Test an OpenDoors account, create and attach a cloud gateway to the current setup then discover devices on that gateway

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "userId" : "a user id", "name" : "OpenDoorsDiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
userId	User login

OpenDoorsDiscoverCompletedEvent
Field name	Field description
Description
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "gatewayId" : "a gateway id", "candidates" : [ { "deviceLabel" : "a device label", "deviceAddress" : "a device address", "deviceType" : 2 } ], "name" : "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

POST

Discover

/config/opendoors/discoverGateway

application/json

Test an OpenDoors account, create and attach a cloud gateway to the current setup then discover devices on that gateway

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "gatewayId" : "a gateway id", "candidates" : [ { "deviceLabel" : "a device label", "deviceAddress" : "a device address", "deviceType" : 2 } ], "name" : "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

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

POST

Discover devices

/config/opendoors/{gatewayId}/discoverDevices

application/json

Discover OpenDoors devices on given gateway

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "gatewayId" : "a gateway id", "candidates" : [ { "deviceLabel" : "a device label", "deviceAddress" : "a device address", "deviceType" : 2 } ], "name" : "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

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

POST

OpenDoors create authentication URL

/config/opendoors/createAuthenticationURL/{redirectURL}

application/json

Return an URL to use for OpenDoors authentication. At the end of the authentication process, the user will be redirected to the given {redirectURL}

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	redirectURL	"string value"	OAuth redirect URL
Request Body	(JSON)	{ "applicationId" : "an application id" }	(Optional)

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

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

Overkiz Protocol

Private tags : [ ovp-config ]

Expand commands

POST

Actuators

/config/{gatewayId}/ovp/discover

application/json

Start the OVP actuators discover full procedure (discover actuators that share the same key and actuators that are in config state)

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "name" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

POST

Actuators

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

application/json

Start the OVP actuators discover in system procedure (discover only actuators that share the same system key)

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "name" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

ExecutionStateChangedEvent
Field name	Field description
Description	An execution state has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

POST

Actuators

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

application/json

Start the OVP actuators discover simple procedure (discover only actuators that are in config state)

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

POST

Module

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

application/json

Start an OVP sensors discover modules on a modbus gateway

Access scope : Public

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

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

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

POST

Sensor

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

application/json

Start the OVP sensors discover full procedure (discover sensors that share the same key and actuators that are in config state)

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

POST

Sensor

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

application/json

Start the OVP sensor discover simple procedure (discover only sensors that are in config state)

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

Philips HUE

Private tags : [ hue-config ]

Expand commands

PUT

Create HUE bridge user

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

application/json

Create a bridge user on the Philips HUE bridge. Does nothing if the user already exists.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	hueBridgeAddress	"string value"	The HUE bridge 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

POST

Discover HUE bridge

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

application/json

Start a discover for a Philips HUE bridge

Access scope : Public

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

POST

Discover HUE bridge configuration

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

application/json

Start a configuration discover on the target Philips HUE bridge

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	hueBridgeAddress	"string value"	The HUE bridge 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

Profalux868 protocol

Private tags : [ profalux868-config ]

Expand commands

GET

Device Address

/config/{gatewayId}/profalux868/address

application/json

This operation give the next available address

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "nextFreeAddress" : 1 }

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

POST

Profalux868 pair

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

application/json

Pair profalux device

Access scope : Public

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

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

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

POST

Profalux868 unpair

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

application/json

Unpair profalux device

Access scope : Public

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

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

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

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

Retrieve all protocol groups and their devices present in a given setup

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "configurationURL" : "a configuration URL", "supervisionURL" : "a supervision URL", "deviceURLs" : [ "some device URLs" ] } ]	List of protocol groups with their devices in the setup

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

POST

Other

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

application/json

Create a group node for a protocol

Access scope : Public

Parameters

Type

Name

Value

Description

Path Variable

gatewayId

"string value"

The gateway ID

Path Variable

protocolType

The protocol type

Request Body

(JSON)

{
  "label" : "group label after creation",
  "capability" : "capability of group, example: zigbee:OnOffComponent, zigbee:LightComponent or any controllable work with group"
}

Response
Type	Name	Value	Description
Response Body	(JSON)	[ "string value" ]	List of deviceURL created

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

GET

Other

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

application/json

Retrieve all controllables allowed in protocol group creation

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	protocolType	1	The protocol type

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "controllableName" : "a controllable name", "controllableType" : "a controllable type" } ]	List of controllables allowed in protocol group creation

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

GET

Protocol Group Devices

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

application/json

Retrieve the urls of the devices present in a given protocol group

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	the gateway Id
Path Variable	groupAddress	"string value"	the group address
Path Variable	protocolType	1	The protocol type

Response
Type	Name	Value	Description
Response Body	(JSON)	[ "string value" ]	List of devices url present in the protocol group

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

RTD protocol

Private tags : [ rtd-config ]

Expand commands

GET

Device address

/config/{gatewayId}/rtd/deviceAddress

application/json

Return an available RTD device address

Access scope : Public

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

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

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

POST

Discover

/config/{gatewayId}/rtd/discover

application/json

Start a RTD sensor discover procedure

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Key

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

application/json

This operation allows to retrieve the RTD key from an alarm system

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

RTS protocol

Private tags : [ rts-config ]

Expand commands

GET

Channel

/config/{gatewayId}/rts/channel

application/json

This operation allows to retrieve an available RTS channel

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "rtsChannelId" : 1 }

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

GET

Key

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

application/json

This operation allows to retrieve the RTS key from a control point

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

Ramses protocol

Private tags : [ ramses-config ]

Expand commands

POST

Discover master nodes

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

application/json

This operation allows to discover a Ramses gateway

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

POST

Discover master nodes

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

application/json

This operation allows to discover nodes of a Ramses master device, like an EvoHome

Access scope : Public

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

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Master destination address

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

application/json

This operation allows to test the Ramses master device address

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	evoHomeAddress	"string value"	The evoHome address (in hexadecimal format)

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

Generated events on method call

ValidAddressEvent
Field name	Field description
Description	A device address has been validated
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "address" : "an address", "name" : "ValidAddressEvent" }
address	Device address
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type

GET

Test gateway destination address

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

application/json

This operation allows to test the Ramses gateway address

Access scope : Public

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

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

Generated events on method call

ValidAddressEvent
Field name	Field description
Description	A device address has been validated
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "address" : "an address", "name" : "ValidAddressEvent" }
address	Device address
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
protocolType	Device protocol type

Somfy Thermostat protocol

Private tags : [ somfy-thermostat-config ]

Expand commands

POST Authentication /config/somfythermostat/tokens application/json

Generate OAuth2 tokens from credentials

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "name" : "SomfyThermostatGenerateOAuthTokensCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

PUT Authentication /config/somfythermostat/tokens application/json

Refresh current access token if necessary

Access scope : Public

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

Generated events on method call

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

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

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

Start a SomfyThermostat discover devices procedure

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

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

Start a discover gateways

Access scope : Public

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

Generated events on method call

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

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

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

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

discover the gateway corresponding to the gatewayId

Access scope : Public

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

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

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

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

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

discover gateways candidates

Access scope : Public

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

Generated events on method call

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

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

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

POST

Somfy thermostat create authentication URL

/config/somfythermostat/createAuthenticationURL/{redirectURL}

application/json

Return an URL to use for Somfy thermostat authentication. At the end of the authentication process, the user will be redirected to the given {redirectURL}

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	redirectURL	"string value"	OAuth redirect URL
Request Body	(JSON)	{ "username" : "a username", "password" : "a password", "applicationId" : "an application id" }	(Optional)

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

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

POST

Webhooks

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

application/json

Register webhook for events

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "name" : "SomfyThermostatRegisterWebhookSuccessEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

DELETE

Webhooks

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

application/json

Delete webhook for events

Access scope : Public

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

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

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

SomfyProtect protocol

Private tags : [ somfyprotect-config ]

Expand commands

POST Authentication /config/somfyprotect/tokens application/json

Generate OAuth2 tokens from credentials

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "name" : "SomfyProtectGenerateOAuthTokensFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

PUT Authentication /config/somfyprotect/tokens application/json

Refresh current access token if necessary

Access scope : Public

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

Generated events on method call

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

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

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

Start a SomfyProtect discover devices procedure

Access scope : Public

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

DiscoverCompleteEvent
Field name	Field description
Description	Discover is complete
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

DiscoverFailedEvent
Field name	Field description
Description	Discover has failed
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "protocolType" : 1, "ref" : "a ref", "name" : "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

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

Start a discover of the gateway with the siteID

Access scope : Public

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

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

SomfyProtectDiscoverCompletedEvent
Field name	Field description
Description
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "name" : "SomfyProtectDiscoverCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup 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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "name" : "SomfyProtectDiscoverFailedEvent", "failureType" : "NON_EXECUTING" }
failureType	Failure type
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

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

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

Discover gateways candidates

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "SomfyProtectGetSitesCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

SomfyProtectGetSitesFailedEvent
Field name	Field description
Description
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "name" : "SomfyProtectGetSitesFailedEvent", "failureType" : "NON_EXECUTING" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup 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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "SomfyProtectGetSitesCompletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

POST

SomfyProtect create authentication URL

/config/somfyprotect/createAuthenticationURL/{redirectUrl}

application/json

Return an URL to use for SomfyProtect authentication. At the end of the authentication process, the user will be redirected to the given {redirectUrl}

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	redirectUrl	"string value"	OAuth redirect URL
Request Body	(JSON)	{ "applicationId" : "an application id" }	(Optional)

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

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

UPnP Control protocol

Private tags : [ upnpcontrol-config ]

Expand commands

GET

Topology

/config/{gatewayId}/upnpcontrol/sonos/checkActionGroups

application/json

Check if action groups are consistent with the topology

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "impactedElements" : { "actionGroupsOID" : [ "some action groups OID" ], "calendarDaysOID" : [ "some calendar days OID" ], "setupTriggersOID" : [ "some setup triggers OID" ] } }

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

POST

Topology

/config/{gatewayId}/upnpcontrol/sonos/topology/{deviceURL}

application/json

Get sonos topology

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway id
Path Variable	deviceURL	"string value"	The device url

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

Generated events on method call

SonosGetTopologySuccessEvent
Field name	Field description
Description	Sonos get topology successfully finished
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "name" : "SonosGetTopologySuccessEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

SonosTopologyChangedEvent
Field name	Field description
Description	Sonos get topology changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "actionGroupOIDsToUpdate" : [ "an action group OIDs to update" ], "name" : "SonosTopologyChangedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

Wiser protocol

Private tags : [ wiser-config ]

Expand commands

POST

discover devices

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

application/json

Start a discover devices on a gateway

Access scope : Public

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

POST

wiser create authentication URL

/config/wiser/createAuthenticationURL/{redirectURL}

application/json

Return an URL to use for wiser authentication. At the end of the authentication process, the user will be redirected to the given {redirectURL}

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	redirectURL	"string value"	OAuth redirect URL
Request Body	(JSON)	{ "applicationId" : "an application id" }	(Optional)

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

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

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

discover a site by id

Access scope : Public

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

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

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

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

Return the list of the gateways candidates

Access scope : Public

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

Generated events on method call

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

WiserSitesCandidatesDiscoveredEvent
Field name	Field description
Description
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "candidates" : [ { "id" : "an id", "name" : "a wiser site name" } ], "name" : "WiserSitesCandidatesDiscoveredEvent" }
candidates	List of Wiser sites candidates
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup 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

Launch the refresh operation on the corresponding association group.

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

POST

Refresh association groups

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

application/json

Launch the refresh operation on all the association groups available on the node.

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

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

Start a Z-Wave reset procedure.

Access scope : Public

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

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

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

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

GET

Retrieve association group

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

application/json

Retrieve the last association information sent by the product for the corresponding groupId. Be aware that this information might no be up to date. The 'Association refresh' APIs shall be called to explicitly retrieve the association information from the product.

Access scope : Public

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)	{ "maxNode" : 4, "groupId" : 3, "nodeList" : [ 5 ] }

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

GET

Retrieve association groups

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

application/json

Retrieve the last association information sent by the product. Be aware that this information might no be up to date. The 'Association refresh' APIs shall be called to explicitly retrieve the association information from the product.

Access scope : Public

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)	{ "maxAssociationGroup" : 1, "associationGroups" : [ { "maxNode" : 4, "groupId" : 3, "nodeList" : [ 5 ] } ] }

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

POST

Set association group

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

application/json

Set the corresponding association group.

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "execId" : "an exec id", "newState" : "IN_PROGRESS", "ownerKey" : "an owner key", "type" : 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, "name" : "ExecutionStateChangedEvent", "failureType" : "NON_EXECUTING" }
execId	Execution id
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
subType	Execution sub type
timeToNextState	Remaining time until next execution state
type	Execution type

Zigbee protocol

Private tags : [ zigbee-config ]

Expand commands

POST

BindNetwork

/config/{gatewayId}/zigbee/bindNetwork

application/json

Bind all device state

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "ZigbeeBindNetworkCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

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

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

POST

CreateNetwork

/config/{gatewayId}/zigbee/createNetwork

application/json

Create a new network (leave any existing network before calling this api)

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "ZigbeeCreateNetworkCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

POST

CreateNetwork with channels

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

application/json

Create a new network on restricted channels (leave any existing network before calling this api)

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "ZigbeeCreateNetworkFailedEvent", "failureType" : "NON_EXECUTING" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

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

DeviceCreatedEvent
Field name	Field description
Description	A new device has been added to the setup
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

POST

JoinNetwork

/config/{gatewayId}/zigbee/joinNetwork

application/json

Join a open network

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

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

POST

LeaveNetwork

/config/{gatewayId}/zigbee/leaveNetwork

application/json

Leave the network

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "ZigbeeLeaveNetworkCompletedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

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

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

POST

RefreshNetwork

/config/{gatewayId}/zigbee/refreshNetwork

application/json

Refresh all device state

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" } ], "name" : "DeviceCreatedEvent" }
deviceAttributes	Compatible device attributes
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

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

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

Documentation

Expand commands

GET

Doc

/doc

text/html

Get this documentation page

Access scope : Public

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

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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "userId" : "a user id", "locked" : true, "owner" : false, "templateName" : "a template 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", "name" : "EndUserAccountUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

POST

End-user Account

/enduser/email/validation

application/json

Ask a single-use token for logged-in user email validation. A token can only be used once. Asking for a new token will cancel the previous one.

Access scope : Public

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

POST

End-user Account

/enduser/email/validation/{token}

application/json

Validate logged-in user email given a token. A token can only be used once.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	token	"string value"	The token

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "emailValidated" : false }

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

POST

End-user Account

/enduser/jwt/createToken

application/json

Create a short-lived Json Web Token representing the current user authority, to be used by external services to access the API on behalf of the user

Access scope : Public

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

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

POST

End-user Account

/enduser/password

application/json

Change logged-in user password, given the old password and a new password

Access scope : Public

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "oldPassword" : "an old password", "newPassword" : "a new password" }	Information to change the end-user password

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

POST

End-user Account

/enduser/password/reset

application/json

Reset an end-user password, given the user name and email address

Access scope : Public

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "userId" : "a user id", "email" : "an email" }	Information to reset the end-user password

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

POST

End-user Account

/enduser/{userId}/validation

application/json

Ask a single-use token for user account and email validation. A token can only be used once. Asking for a new token will cancel the previous one.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	userId	"string value"	The user id

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

POST

End-user Account

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

application/json

Validate user account and email given a token. A token can only be used once.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	userId	"string value"	The user id
Path Variable	token	"string value"	The token

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "emailAndAccountValidated" : false }

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

POST

End-user Setup

/enduser/setup

application/json

Create a new setup and attach it to connected end user

Access scope : Public

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" : "SOLAR",
    "twilightCity" : "a twilight city",
    "summerSolsticeDuskMinutes" : 1,
    "winterSolsticeDuskMinutes" : 1,
    "twilightOffsetEnabled" : true,
    "dawnOffset" : 1,
    "duskOffset" : 1,
    "tariffSettings" : {
      "tariffMode" : "offPeakHours",
      "tariffs" : [ {
        "name" : "tariff0",
        "startTime" : "00:01"
      } ]
    }
  },
  "label" : "a new setup creation label",
  "templateName" : "a template name",
  "applicationId" : "an application id",
  "activationTimestamp" : 120123456790,
  "expirationTimestamp" : 120123456791,
  "gatewayIds" : [ "some gateway ids" ]
}

Create setup options

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

GET

End-user setup

/enduser/defaultSetupOID

application/json

Get default setup OID for the connected user

Access scope : Public

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

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

POST

End-user setup

/enduser/defaultSetupOID

application/json

Set default setup OID for the connected user

Access scope : Public

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

GET

End-user setup

/enduser/setupLabel

application/json

Get setup label

Access scope : Public

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

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

PUT

End-user setup

/enduser/setupLabel

application/json

Update setup label

Access scope : Public

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "label" : "a setup label label" }	New setup label

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

GET

End-user setup

/enduser/setups

application/json

Get all setup information for the connected user. Activation/Expiration timestamps are expressed as milliseconds since EPOCH.

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "setupOID" : "a setup OID",
  "userId" : "a user id",
  "templateName" : "a template name",
  "owner" : false,
  "defaultSetup" : true,
  "label" : "a setup end user label",
  "activationTimestamp" : 1774337682780,
  "expirationTimestamp" : 1774337682780
} ]

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

PUT

End-user setup

/enduser/{userId}/accessPeriod

application/json

Set or update activation date and expiration date for user access on setup.
Activation/Expiration timestamps are optional and expressed as milliseconds since EPOCH.
If a timestamp is omitted, the associated bound is not applied : one can set an activation date only, an expiration date only, or remove both by sending an empty object.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	userId	"string value"	User id
Request Body	(JSON)	{ "activationTimestamp" : 120123456790, "expirationTimestamp" : 120123456791 }	Access period

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

DELETE

End-user setup

/enduser/{userId}/accessPeriod

application/json

Delete activation date and expiration date for user access on setup

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	userId	"string value"	User id

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

GET

Enduser

/enduser/existingUserIds/{userId}

application/json

Check if the given 'userId' exist. (This operation is rate limited, do not abuse it)

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	userId	"string value"	The id of the user

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "userExists" : false }

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

GET

Main end-user Account

/enduser/mainAccount

application/json

Get all data about the connected user:

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

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1774337682762,
  "lastUpdateTime" : 1774337682765,
  "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",
  "emailValidated" : false,
  "commercialMailAgreement" : false,
  "technicalAccount" : true,
  "extraEmails" : [ {
    "email" : "an email",
    "validated" : true
  } ]
}

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

POST

Main end-user Account

/enduser/mainAccount

application/json

Create enduser main account

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

Access scope : Public

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",
  "templateName" : "a template 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"
}

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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "name" : "MainAccountUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

POST

Password quality check

/enduser/password/check

application/json

Check the quality of a given username/password pair. A negative score means the password will be rejected.

Access scope : Public

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "userId" : "user1", "userPassword" : "p4ssw0rd!" }

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "score" : 52, "weaknesses" : [ { "key" : "PWD_COMMON_TOKEN", "label" : "Password contains a word or sequence which is too common" } ], "qualityClass" : "Medium" }

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

POST

Secondary end-users account

/enduser/secondaryAccounts

application/json

Add a secondary enduser account

Access scope : Public

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "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",
  "label" : "a secondary enduser account label",
  "templateName" : "a template name",
  "activationTimestamp" : 120123456790,
  "expirationTimestamp" : 120123456794
}

All information about the secondary account

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

GET

Secondary end-users account

/enduser/secondaryAccounts/{secondaryEndUserId}

application/json

Get the secondary account for the given userId

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	secondaryEndUserId	"string value"	The user id of the secondary account

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "userId" : "a user id" }

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

GET

Secondary end-users accounts

/enduser/secondaryAccounts

application/json

Get secondary accounts

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

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "userId" : "a user id" } ]

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

Custom role

Expand commands

GET

End-user custom role

/setup/roles

application/json

Get custom roles

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

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "name" : "an end user custom role response name", "permissions" : [ { "type" : "deviceControl", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ] } ]

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

POST

End-user custom role

/setup/roles

application/json

Create or update custom role

Access scope : Public

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "name" : "an end user custom role request name",
  "permissions" : [ {
    "type" : "deviceControl",
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
  } ]
}

A custom role definition

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

GET

End-user custom role

/setup/roles/{roleName}

application/json

Get custom role

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	roleName	"string value"	The role name

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "name" : "an end user custom role response name", "permissions" : [ { "type" : "deviceControl", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ] }

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

DELETE

End-user custom role

/setup/roles/{roleName}

application/json

Delete a custom role

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	roleName	"string value"	Role Name

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

Permissions

Expand commands

GET

End-user permissions

/enduser/permissions

application/json

Get end-user permissions

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "permissionType" : "endUserDeviceViewPermission" } ]

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

GET

End-user permissions

/enduser/permissions/control

application/json

Get end-user device control permissions

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "permissionType" : "endUserDeviceViewPermission" } ]

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

GET

End-user permissions

/enduser/permissions/view

application/json

Get end-user device view permissions

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "permissionType" : "endUserDeviceViewPermission" } ]

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

GET

End-user permissions

/enduser/{secondaryUserId}/permissions

application/json

Get a secondary end-user permissions

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	secondaryUserId	"string value"	One of the secondary account

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "permissionType" : "endUserDeviceViewPermission" } ]

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

GET

End-user permissions

/enduser/{secondaryUserId}/permissions/control

application/json

Get a secondary end-user device control permissions

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	secondaryUserId	"string value"	One of the secondary account

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "permissionType" : "endUserDeviceViewPermission" } ]

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

POST

End-user permissions

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

application/json

Add a secondary end-user device control permissions

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	target	"string value"	The new target
Path Variable	action	"string value"	The new action
Path Variable	secondaryUserId	"string value"	One of the secondary account

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

DELETE

End-user permissions

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

application/json

Remove a secondary end-user device control permissions

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	target	"string value"	The new target
Path Variable	action	"string value"	The new action
Path Variable	secondaryUserId	"string value"	One of the secondary account

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

GET

End-user permissions

/enduser/{secondaryUserId}/permissions/view

application/json

Get a secondary end-user device view permissions

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	secondaryUserId	"string value"	One of the secondary account

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "permissionType" : "endUserDeviceViewPermission" } ]

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

POST

End-user permissions

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

application/json

Add a secondary end-user device view permissions

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	target	"string value"	The new target
Path Variable	secondaryUserId	"string value"	One of the secondary account

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

DELETE

End-user permissions

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

application/json

Remove a secondary end-user device view permissions

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	target	"string value"	The new target
Path Variable	secondaryUserId	"string value"	One of the secondary account

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

Preferences

Expand commands

GET

End-user preferences

/enduser/preferences

application/json

Get user preferences

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

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "name" : "an end user preference name", "value" : "an end user preference value", "oid" : "the end user preference UUID" } ]

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

POST

End-user preferences

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

application/json

Create a user preference

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "preferenceOID" : "a preference OID", "userId" : "a user id", "preferenceName" : "a preference name", "preferenceValue" : "a preference value", "name" : "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
userId	User id

GET

End-user preferences

/enduser/preferences/{preferenceId}

application/json

Get a user preference

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	preferenceId	"string value"	The id of the preference to retrieve

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "name" : "an end user preference name", "value" : "an end user preference value", "oid" : "the end user preference UUID" }

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

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

Delete a user preference

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "preferenceOID" : "a preference OID", "userId" : "a user id", "preferenceName" : "a preference name", "name" : "EndUserPreferenceDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
preferenceName	Preference name
preferenceOID	Preference OID
setupOID	Setup OID
userId	User id

PUT

End-user preferences

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

application/json

Update a user preference

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "preferenceOID" : "a preference OID", "userId" : "a user id", "preferenceName" : "a preference name", "preferenceValue" : "a preference value", "name" : "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
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

Register an event listener

Register a new setup event listener on the current session and return a new listener id. Only one listener may be registered on a given session. Registering an new listener will invalidate the previous one if any. Note that registering an event listener drastically reduces the session timeout : listening sessions are expected to call the /events/{listenerId}/fetch API on a regular basis.

Access scope : Public

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

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

POST

Events Unregistration

/events/{listenerId}/unregister

application/json

Unregister an event listener

Register a new setup event listener on the current session and return a new listener id. Only one listener may be registered on a given session. Registering an new listener will invalidate the previous one if any. Default session timeout is restored.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	listenerId	"string value"	Listener ID obtained at the registration stage

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

POST

Fetching Events

/events/{listenerId}/fetch

application/json

Fetch new events

Fetch new events from a registered event listener. Fetched events are removed from the listener buffer. Return an empty response if no event is available.

Per-session rate-limit : 1 calls per 1s period for this particular operation (polling)

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	listenerId	"string value"	Listener ID obtained at the registration stage

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "timestamp" : 2,
  "owningPartners" : [ "some owning partners" ],
  "setupOID" : "a setup OID",
  "execId" : "an exec id",
  "newState" : "IN_PROGRESS",
  "ownerKey" : "an owner key",
  "type" : 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,
  "name" : "ExecutionStateChangedEvent",
  "failureType" : "NON_EXECUTING"
} ]

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

History

Expand commands

GET

Device event history

/history/devicesEvent/{eventId}

application/json

Retrieve a device event by ID

Get a device event that occurred on an actuator or a sensor (fault or warning)

Access scope : Public

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

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "deviceEvent" : {
    "eventTime" : 1774337682819,
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
    "value" : "a device event log value",
    "id" : "an event id",
    "subType" : "UNKNOWN_ERROR",
    "type" : "FAULT"
  }
}

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

GET

Device events history

/history/devicesEvent

application/json

Retrieve device events history

Get the history of all specific events that occurred on actuators or sensors (fault or warning)

Per-session rate-limit : 1 calls per 28min 48s period for this particular operation (bulk-history)

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "eventTime" : 1774337682819,
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
  "value" : "a device event log value",
  "id" : "an event id",
  "subType" : "UNKNOWN_ERROR",
  "type" : "FAULT"
} ]

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

GET

Execution history

/history/executions/{execId}

application/json

Retrieve a completed execution

Get a completed execution instance by ID

Access scope : Public

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" : 1774337682830,
    "actionGroupOID" : "an action group OID",
    "actionGroupMetadata" : "an action group metadata",
    "owner" : "an owner",
    "source" : "a source",
    "endTime" : 1774337682838,
    "effectiveStartTime" : 1774337682830,
    "duration" : 8,
    "id" : "an exec id",
    "label" : "an action group label",
    "metaData" : "an execution meta data",
    "type" : "Immediate execution - MANUAL_CONTROL",
    "state" : "COMPLETED",
    "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"
    } ],
    "executionType" : "Immediate execution",
    "executionSubType" : "MANUAL_CONTROL"
  }
}

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

GET

Executions history

/history/lastExecutions

application/json

Retrieve completed executions

Get the history of all completed executions .

Per-session rate-limit : 1 calls per 28min 48s period for this particular operation (bulk-history)

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "eventTime" : 1774337682838,
  "actionGroupOID" : "an action group OID",
  "actionGroupMetadata" : "an action group metadata",
  "owner" : "an owner",
  "source" : "a source",
  "endTime" : 1774337682839,
  "effectiveStartTime" : 1774337682838,
  "duration" : 1,
  "id" : "an exec id",
  "label" : "an action group label",
  "metaData" : "an execution meta data",
  "type" : "Immediate execution - MANUAL_CONTROL",
  "state" : "COMPLETED",
  "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"
  } ],
  "executionType" : "Immediate execution",
  "executionSubType" : "MANUAL_CONTROL"
} ]

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

GET

History

/history

application/json

Retrieve completed executions and device events history (mixed)

Get the history of all completed executions and specific events that occurred on an actuator or a sensor (fault or warning)

Per-session rate-limit : 1 calls per 28min 48s period for this particular operation (bulk-history)

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "execution" : {
    "eventTime" : 1774337682839,
    "actionGroupOID" : "an action group OID",
    "actionGroupMetadata" : "an action group metadata",
    "owner" : "an owner",
    "source" : "a source",
    "endTime" : 1774337682839,
    "effectiveStartTime" : 1774337682839,
    "duration" : 0,
    "id" : "an exec id",
    "label" : "an action group label",
    "metaData" : "an execution meta data",
    "type" : "Immediate execution - MANUAL_CONTROL",
    "state" : "COMPLETED",
    "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"
    } ],
    "executionType" : "Immediate execution",
    "executionSubType" : "MANUAL_CONTROL"
  }
} ]

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

DELETE History /history application/json

Clear history

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

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "name" : "HistoryDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Notification events history

/history/notificationEvents

application/json

Retrieve notification events history

Per-session rate-limit : 1 calls per 28min 48s period for this particular operation (bulk-history)

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "eventTime" : 1774337682822,
  "text" : "a text",
  "originatorType" : "an originator type",
  "originatorRef" : "TRIGGER/<triggerjsonClass> or PARTNER",
  "id" : "an event id",
  "type" : "INFO",
  "level" : "INFO"
} ]

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

GET

Setup Access Audit

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

application/json

Retrieve enduser access history on a setup within a time range

History values

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "events" : [ "some events" ], "from" : 2, "to" : 2, "limitReached" : false }

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

Login & Session

Establishing or terminating an API session

Expand commands

GET

Current user

/authenticated

application/json

Test if the current session is authenticated

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "authenticated" : false }

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

GET

Current user

/currentUserId

application/json

Get the current authenticated user name

Access scope : Public

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

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

POST

/login

application/json

Authenticate and create an API session allowing access to the other operations.
Caller must provide one of [userId+userPassword, userId+ssoToken, accessToken, jwt]

Access scope : Public

> Test operation

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)	{ "success" : false, "roles" : [ { "name" : "a security role name" } ], "extraAttributes" : { "some extra attributes" : "some extra attributes" } }	Returns { success: true } on successful login

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

POST

Logout

/logout

application/json

Invalidate the current user session

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "logout" : false }	Returns { "logout": true } on successful logout

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

GET

Other

/accountManagement/resetPasswordFailure

application/json

No available description

Access scope : Public

Parameters
Type	Name	Value	Description
Request Parameter	errorMessage	"string value"	(Optional)

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

GET

Other

/accountManagement/resetPasswordSuccess

application/json

No available description

Access scope : Public

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

Reference Data

Private tags : [ reference ]

Expand commands

GET

Controllable

/reference/controllable/{controllableName}

application/json

Get a controllable definition

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	controllableName	"string value"	Target controllable qualified name

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "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"
}

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

GET

Controllable Types

/reference/controllableTypes

application/json

Get details about all supported controllable types

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "id" : 1, "name" : "a controllable type details name", "label" : "a controllable type details label" } ]

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

POST

Devices Model

/reference/devices/search

application/json

Search devices references definitions

Access scope : Public

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"
      } ]
    } ],
    "uiClassifiers" : [ "some ui classifiers" ],
    "uiProfiles" : [ "some ui profiles" ],
    "uiClass" : "a ui class",
    "uiWidget" : "a widget name",
    "controllableType" : "ACTUATOR",
    "protocolType" : "IO"
  } ]
}

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

GET

Protocol Types

/reference/protocolTypes

application/json

Get details about supported protocol types on that server instance

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "id" : 1, "prefix" : "a prefix", "name" : "a protocol type details name", "label" : "a protocol type details label" } ]

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

GET

Timezones

/reference/timezones

application/json

Get timezones list

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "name" : "a timezone wrapper name", "dst" : false, "offset" : 1 } ]

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

GET

UI Classes

/reference/ui/classes

application/json

Get a list of all defined UI classes

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ "string value" ]

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

GET

UI Classifiers

/reference/ui/classifiers

application/json

Get a list of all defined UI classifiers

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ "string value" ]

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

GET

UI Profiles

/reference/ui/profile/{profileName}

application/json

Get a description of a given UI profile (or form-factor variant)

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	profileName	"string value"	Target UI profile name

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "name" : "a UIProfile descriptor name",
  "commands" : [ {
    "name" : "a UIProfile command name",
    "prototype" : {
      "parameters" : [ {
        "optional" : true,
        "sensitive" : false,
        "valuePrototypes" : [ {
          "type" : "STRING",
          "description" : "string value"
        } ]
      } ]
    },
    "description" : "a description"
  } ],
  "states" : [ {
    "name" : "a UIProfile state name",
    "prototype" : {
      "valuePrototypes" : [ {
        "type" : "STRING",
        "description" : "string value"
      } ]
    },
    "description" : "a description"
  } ],
  "formFactor" : false
}

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

GET

UI Profiles

/reference/ui/profileNames

application/json

Get a list of all defined UI profiles (and form-factor variants)

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ "string value" ]

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

GET

UI Widgets

/reference/ui/widgets

application/json

Get a list of all defined UI widgets

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ "string value" ]

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

Setup

Expand commands

POST

Bulk automation configuration

/setup/automation

application/json

Execute a group of operations (on ActionGroup, CalendarDay, CalendarRule or SetupTrigger) in provided order.
Execution is transactional : either all operations will succeed or fail.

Available operations : actionGroupOperation, calendarDayOperation, calendarRuleOperation, setupTriggerOperation
Available operation types : READ, CREATE, UPDATE, PATCH, DELETE

For READ, PATCH and DELETE : referenceOID must be provided. For a setup trigger operation, setupTriggerType must also be provided.
For CREATE and UPDATE : the full object definition must be provided
For PATCH : a partial object definition is expected.
            Patch compatible fields :
             - Calendar Rule : enabled
             - Setup Trigger : mode

Access scope : Public

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" : 1774370307213,
        "lastUpdateTime" : 1774370307213,
        "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

Get the current setup OID

Access scope : Public

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

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

POST

Current setup

/setup/current/{setupOID}

application/json

Change the current setup for that session. Any existing event registration is automatically closed.

Per-session rate-limit : 1 calls per 1h period for this particular operation (switch)

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	setupOID	"string value"	Target setup OID

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

GET

Dawn time

/setup/dawnTime

application/json

Return dawn time of the current day based on the setup location

Response is composed of a dawnTime nodes; it has a utc time (in milliseconds) and hours and minutes calculated by taking the setup timezone into account.
If dawnTime cannot be defined, utc, hours and minutes are not set.

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "hours" : 0, "minutes" : 0, "utc" : 0 }

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

GET

Dawn time by date

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

application/json

Return dawn time of the chosen day on the setup location

Response is composed of a dawnTime nodes; it has a utc time (in milliseconds) and hours and minutes calculated by taking the setup timezone into account.
If dawnTime cannot be defined, utc, hours and minutes are not set.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	year	1	The year to search
Path Variable	month	1	The month to search
Path Variable	day	1	The day to search

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "hours" : 0, "minutes" : 0, "utc" : 0 }

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

GET

Disconnection configuration

/setup/disconnectionAlert/configuration

application/json

Private tags : [ disconnectionAlert ]

Get configuration for notification sent on gateway disconnect

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "notificationTitle" : "a notification title", "notificationText" : "a notification text", "targetPushSubscriptions" : [ "some target push subscriptions" ], "notificationType" : "PUSH" }

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

PUT

Disconnection configuration

/setup/disconnectionAlert/configuration

application/json

Private tags : [ disconnectionAlert ]

Update configuration for notification sent on gateway disconnect

Access scope : Public

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "notificationTitle" : "a notification title",
  "notificationText" : "a notification text",
  "targetPushSubscriptions" : [ "some target push subscriptions" ],
  "notificationType" : "PUSH"
}

Configuration

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

GET

Dusk time

/setup/duskTime

application/json

Return dusk time of the current day based on the setup location

Response is composed of a duskTime nodes; it has a utc time (in milliseconds) and hours and minutes calculated by taking the setup timezone into account.
If duskTime cannot be defined, utc, hours and minutes are not set.

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "hours" : 0, "minutes" : 0, "utc" : 0 }

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

GET

Dusk time by date

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

application/json

Return dusk time of the chosen day based on the setup location

Response is composed of a duskTime nodes; it has a utc time (in milliseconds) and hours and minutes calculated by taking the setup timezone into account.
If duskTime cannot be defined, utc, hours and minutes are not set.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	year	1	The year to search
Path Variable	month	1	The month to search
Path Variable	day	1	The day to search

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "hours" : 0, "minutes" : 0, "utc" : 0 }

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

POST

Enduser

/setup/enduser

application/json

Add an existing enduser to setup

Access scope : Public

Parameters

Type

Name

Value

Description

Request Body

(JSON)

{
  "userId" : "a user id",
  "label" : "a setup end user wrapper label",
  "templateName" : "a template name",
  "activationDate" : 1774370307240,
  "expirationDate" : 1774370307240,
  "defaultSetup" : false
}

Enduser

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

DELETE

Enduser

/setup/enduser/{userId}

application/json

Remove an existing enduser from setup

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	userId	"string value"	Enduser 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

GET

Location

/setup/location

application/json

Get setup location

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1774337683104,
  "lastUpdateTime" : 1774337683105,
  "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"
    } ]
  }
}

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

PUT Location /setup/location application/json

Update setup location of user

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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", "name" : "LocationUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Setup

/setup

application/json

Get all data about the connected user setup

	-> gateways data (serial number, activation state, ...): <gateways/gateway>
	-> setup location: <location>
	-> house places (rooms and floors): <place>
	-> setup devices: <devices>

A gateway may be in different modes (mode) regarding to the activated functions (functions).

A house may be composed of several floors and rooms. The house, floors and rooms are viewed as a place.

Devices in the house are grouped by type called uiClass. Each device has an associated widget. The widget is used to control or to know the device state, whatever the device protocol (controllable): IO, RTS, X10, ... . A device can be either an actuator (type=1) or a sensor (type=2).

Data of one or several devices can be also get by setting the device(s) url as request parameter.

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

Access scope : Public

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" : 1774337683092,
  "lastUpdateTime" : 1774337683096,
  "id" : "an id",
  "location" : {
    "creationTime" : 1774337683095,
    "lastUpdateTime" : 1774337683096,
    "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"
      } ]
    }
  },
  "gateways" : [ {
    "gatewayId" : "a gateway id",
    "type" : 1,
    "subType" : 1,
    "placeOID" : "a place OID",
    "autoUpdateEnabled" : true,
    "alive" : false,
    "timeReliable" : true,
    "connectivity" : {
      "status" : "PARTIAL",
      "problems" : [ "NO_NTP" ],
      "protocolVersion" : "a protocol version"
    },
    "upToDate" : true,
    "updateStatus" : "UPDATING",
    "syncInProgress" : false,
    "updateCriticityLevel" : "BLOCKING",
    "automaticUpdate" : false,
    "mode" : "ACTIVE",
    "functions" : "some function names"
  } ],
  "devices" : [ {
    "creationTime" : 1774337683092,
    "lastUpdateTime" : 1774337683093,
    "label" : "a device label",
    "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
    "shortcut" : true,
    "controllableName" : "core:StatefulClosableActuator",
    "metadata" : "some metadata",
    "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" : 120123456804
    } ],
    "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"
    } ],
    "available" : true,
    "enabled" : false,
    "placeOID" : "a place OID",
    "widget" : "a widget name",
    "type" : 1,
    "oid" : "the device UUID",
    "uiClass" : "a ui class"
  } ],
  "zones" : [ {
    "creationTime" : 1774337683093,
    "lastUpdateTime" : 1774337683093,
    "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" : "ALWAYS",
  "resellerDelegationEndDate" : 1774337683095,
  "metadata" : "some metadata",
  "disconnectionConfiguration" : {
    "notificationTitle" : "a notification title",
    "notificationText" : "a notification text",
    "targetPushSubscriptions" : [ "some target push subscriptions" ],
    "notificationType" : "PUSH"
  },
  "oid" : "the setup UUID",
  "rootPlace" : {
    "creationTime" : 1774337683096,
    "lastUpdateTime" : 1774337683096,
    "label" : "a place label",
    "type" : 1,
    "metadata" : "some metadata",
    "oid" : "the place UUID",
    "subPlaces" : [ {
      "creationTime" : 1774337683096,
      "lastUpdateTime" : 1774337683096,
      "label" : "a place label",
      "type" : 1,
      "metadata" : "some metadata",
      "oid" : "the place UUID",
      "subPlaces" : [ {
        "creationTime" : 1774337683096,
        "lastUpdateTime" : 1774337683096,
        "label" : "a place label",
        "type" : 1,
        "metadata" : "some metadata",
        "oid" : "the place UUID",
        "subPlaces" : [ ]
      } ]
    } ]
  },
  "features" : [ {
    "name" : "a setup feature name",
    "source" : "a source"
  } ]
}

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

GET

Setup

/setup/files

application/json

Get the list of uploaded files on the setup

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "filename" : "a filename", "size" : 2, "uploadTime" : 1774337683070, "metadata" : "some metadata", "comments" : "some comments", "oid" : "the setup file UUID" } ]

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

GET

Setup

/setup/files/uploadURL

application/json

Get upload url for setup file

Access scope : Public

Parameters
Type	Name	Value	Description
Request Parameter	fileType	"string value"	File type
Request Parameter	fileName	"string value"	(Optional) File name

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

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

GET

Setup

/setup/files/{fileOID}/downloadURL

application/json

Get download url for setup file

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	fileOID	"string value"	OID of the file

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

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

GET

Setup additional information

/setup/additionalInformation

application/json

Get additional information

This operation returns setup additional information.

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

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "templateId" : "a template id", "type" : "SERIAL_NUMBER", "label" : "a setup additional info label", "value" : "a setup additional info value", "rank" : 1, "unsafe" : true } ]

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

GET

Setup additional information

/setup/additionalInformation/{templateId}

application/json

Get additional information

This operation returns setup additional information.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	templateId	"string value"	Additional information template id

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "templateId" : "a template id", "type" : "SERIAL_NUMBER", "label" : "a setup additional info label", "value" : "a setup additional info value", "rank" : 1, "unsafe" : true }

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

DELETE

Setup additional information

/setup/additionalInformation/{templateId}

application/json

Delete setup additional information

This operation deletes setup additional information.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	templateId	"string value"	Additional information template 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

POST

Setup additional information

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

application/json

Add setup additional information

This operation adds setup additional information.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	templateId	"string value"	Additional information template id
Path Variable	value	"string value"	Additional information value

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

GET

Setup features

/setup/features

application/json

Get setup features

Retrieve all setup features of a setup

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

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "name" : "a setup feature name", "source" : "a source" } ]

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

PUT

Setup metadata

/setup/metadata

application/json

Update setup metadata

Access scope : Public

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "metadata" : "some metadata" }	New metadata

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

GET

Setup options

/setup/options

application/json

This operation returns all subscribed options of a given setup.

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "creationTime" : 1774337683099,
  "lastUpdateTime" : 1774337683099,
  "optionId" : "an option id",
  "startDate" : 1774337683099,
  "endDate" : 1774337683099,
  "parameters" : [ {
    "name" : "a setup option parameter name",
    "value" : "a setup option parameter value"
  } ]
} ]

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

GET

Setup options

/setup/options/{optionId}

application/json

This operation returns the selected subscribed option of a given setup.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	optionId	"string value"	The id of the option to retrieve

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1774337683100,
  "lastUpdateTime" : 1774337683100,
  "optionId" : "an option id",
  "startDate" : 1774337683100,
  "endDate" : 1774337683100,
  "parameters" : [ {
    "name" : "a setup option parameter name",
    "value" : "a setup option parameter value"
  } ]
}

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

GET

Setup options

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

application/json

This operation returns all subscribed options of a given setup.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	optionId	"string value"	The id of the option to retrieve
Path Variable	parameterName	"string value"	The name of the option parameter to retrieve

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "name" : "a setup option parameter name", "value" : "a setup option parameter value" }

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

GET

Setup quotas

/setup/quotas

application/json

This operation returns remaining quotas value.

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "setupOID" : "a setup OID", "descriptorId" : "a descriptor id", "currentValue" : 1, "oid" : "the setup quota UUID" } ]

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

GET

Setup quotas

/setup/quotas/{quotaId}

application/json

This operation returns a quota.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	quotaId	"string value"	Quota id

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "setupOID" : "a setup OID", "descriptorId" : "a descriptor id", "currentValue" : 1, "oid" : "the setup quota UUID" }

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

Calendar

Private tags : [ calendar ]

Expand commands

GET

Calendar day

/setup/calendar/days

application/json

Get all calendar days for setup.

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "creationTime" : 1774337682982,
  "lastUpdateTime" : 1774337683040,
  "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" : 1774337683008,
        "lastUpdateTime" : 1774337683040,
        "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

Create a calendar day.

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

CalendarDayCreatedEvent
Field name	Field description
Description	A calendar day has been created
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "calendarDayOID" : "a calendar day OID", "label" : "a calendar day created event label", "metadata" : "some metadata", "type" : "a calendar day created event 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" : 1774370307180, "lastUpdateTime" : 1774370307181, "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" } } } ], "name" : "CalendarDayCreatedEvent" }
calendarDayOID	Calendar day OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

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

Update a calendar day.

Access scope : Public

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

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

CalendarDayUpdatedEvent
Field name	Field description
Description	A calendar day has been updated
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "calendarDayOID" : "a calendar day OID", "label" : "a calendar day updated event label", "metadata" : "some metadata", "type" : "a calendar day updated event 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" : 1774370307187, "lastUpdateTime" : 1774370307187, "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" } } } ], "name" : "CalendarDayUpdatedEvent" }
calendarDayOID	Calendar day OID
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

GET

Calendar day

/setup/calendar/days/{oid}

application/json

Get a calendar day.

Access scope : Public

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" : 1774337683057,
  "lastUpdateTime" : 1774337683058,
  "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" : 1774337683058,
        "lastUpdateTime" : 1774337683058,
        "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 : Public

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

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

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

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

GET

Calendar objects

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

application/json

Get all calendar objects applicable for the given startDate and endDate. All the

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

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	startDate	2	The start date of the period of search. TimeStamp (EPOCH in days)
Path Variable	endDate	2	The end date of the period of search. TimeStamp (EPOCH in days)

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "120123456790" : { "calendarDays" : [ "some calendar days" ], "calendarRules" : [ "some calendar rules" ] } }

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

GET

Calendar objects

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

application/json

Get all calendar objects applicable for the given

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

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	year	1	The year to search
Path Variable	month	1	The month to search
Path Variable	day	1	The day to search

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "calendarDays" : [ "some calendar days" ], "calendarRules" : [ "some calendar rules" ] }

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

POST

Calendar objects

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

application/json

Create a calendar day according to calendar days/rules to be removed

Access scope : Public

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" : 1774337683057,
  "lastUpdateTime" : 1774337683058,
  "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" : 1774337683058,
        "lastUpdateTime" : 1774337683058,
        "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

Get all calendar rules for setup.

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "weeklyCalendarRule" : {
    "creationTime" : 1774337683051,
    "lastUpdateTime" : 1774337683052,
    "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" : 1774337683051,
      "lastUpdateTime" : 1774337683052,
      "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" : 1774337683052,
            "lastUpdateTime" : 1774337683052,
            "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

Create a calendar rule.

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "GatewaySynchronizationEndedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

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

CalendarRuleCreatedEvent
Field name	Field description
Description	A calendar rule has been created
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "calendarRuleOID" : "a calendar rule OID", "calendarRuleId" : "a calendar rule id", "type" : "a calendar rule created event type", "priority" : 1, "calendarDayOID" : "a calendar day OID", "dayType" : "a day type", "metadata" : "some metadata", "finalRule" : false, "randomTimeRange" : 1, "startDay" : 4, "startMonth" : 3, "startYear" : 5, "startTimeHours" : 6, "startTimeMinutes" : 10, "endDay" : 9, "endMonth" : 11, "endYear" : 7, "endTimeHours" : 2, "endTimeMinutes" : 8, "name" : "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

PUT

Calendar rule

/setup/calendar/rules

application/json

Update a calendar rule.

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "calendarRuleOID" : "a calendar rule OID", "calendarRuleId" : "a calendar rule id", "type" : "a calendar rule updated event type", "priority" : 1, "calendarDayOID" : "a calendar day OID", "dayType" : "a day type", "metadata" : "some metadata", "finalRule" : false, "randomTimeRange" : 1, "startDay" : 4, "startMonth" : 3, "startYear" : 5, "startTimeHours" : 6, "startTimeMinutes" : 10, "endDay" : 9, "endMonth" : 11, "endYear" : 7, "endTimeHours" : 2, "endTimeMinutes" : 8, "name" : "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

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

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

GET

Calendar rule

/setup/calendar/rules/{oid}

application/json

Get a calendar rule.

Access scope : Public

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

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "weeklyCalendarRule" : {
    "creationTime" : 1774337683060,
    "lastUpdateTime" : 1774337683061,
    "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" : 1774337683060,
      "lastUpdateTime" : 1774337683061,
      "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" : 1774337683061,
            "lastUpdateTime" : 1774337683061,
            "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 : Public

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

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

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

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

POST

Calendar rules

/setup/calendar/ruleSet

application/json

Create a set of calendar rules.

Access scope : Public

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

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

CalendarRuleCreatedEvent
Field name	Field description
Description	A calendar rule has been created
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "calendarRuleOID" : "a calendar rule OID", "calendarRuleId" : "a calendar rule id", "type" : "a calendar rule created event type", "priority" : 1, "calendarDayOID" : "a calendar day OID", "dayType" : "a day type", "metadata" : "some metadata", "finalRule" : false, "randomTimeRange" : 1, "startDay" : 4, "startMonth" : 3, "startYear" : 5, "startTimeHours" : 6, "startTimeMinutes" : 10, "endDay" : 9, "endMonth" : 11, "endYear" : 7, "endTimeHours" : 2, "endTimeMinutes" : 8, "name" : "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

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

PUT

Calendar rules

/setup/calendar/ruleSet

application/json

Update a set of calendar rules.

Access scope : Public

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

CalendarRuleUpdatedEvent
Field name	Field description
Description	A calendar rule has been updated
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "calendarRuleOID" : "a calendar rule OID", "calendarRuleId" : "a calendar rule id", "type" : "a calendar rule updated event type", "priority" : 1, "calendarDayOID" : "a calendar day OID", "dayType" : "a day type", "metadata" : "some metadata", "finalRule" : false, "randomTimeRange" : 1, "startDay" : 4, "startMonth" : 3, "startYear" : 5, "startTimeHours" : 6, "startTimeMinutes" : 10, "endDay" : 9, "endMonth" : 11, "endYear" : 7, "endTimeHours" : 2, "endTimeMinutes" : 8, "name" : "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

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

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

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

Delete a set of calendar rules.

Access scope : Public

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

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

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

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

GET

Setup calendar status

/setup/calendar/status

application/json

Get calendar status.

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "enabled" : false }

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

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

Update calendar status.

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "functionType" : 1, "enabled" : false, "name" : "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

Camera Operations

Private tags : [ camera ]

Expand commands

POST

Picture

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

application/json

Delete a list of pictures.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Camera device URL
Request Body	(JSON)	[ 2 ]	Pictures ids to delete

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

GET

Picture

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

application/json

Get reference data for a given picture, allowing the later retrieval of the picture image through a storage server.

Response contains a picture reference and two picture url templates:
	-> a url template for the picture thumbnail
	-> a url template for the picture

Both url templates will look like to:
https://somewhere.com/getPicture?cameraid=@CAMERA_ID@&protocolType=@PROTOCOL_TYPE@&gatewayId=@GATEWAY_ID@&photoID=@PHOTO_ID@&sessionId=@SESSION_ID@

To use these templates, @CAMERA_ID@, @PROTOCOL_TYPE@, @GATEWAY_ID@, @PHOTO_ID@ and @SESSION_ID@ will have to be replaced by a correct values.

Note that the sessionId timeout is 30 seconds.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Camera device URL
Path Variable	pictureId	120123456790	Picture id

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "cameraId" : "a camera id",
  "gatewayId" : "a gateway id",
  "thumbnailUrlTemplate" : "a thumbnail url template",
  "pictureUrlTemplate" : "a picture url template",
  "sessionId" : "a session id",
  "protocolType" : 1,
  "timestamp" : 2,
  "pictureId" : 2
}

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

DELETE

Picture

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

application/json

Delete a picture

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Camera device URL
Path Variable	pictureId	120123456790	Picture id to delete

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

GET

Picture

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

application/json

Get url of a picture of a camera

Url contains a session id available for 30 seconds.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Camera device URL
Path Variable	pictureId	120123456790	Picture id

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

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

DELETE

Pictures

/setup/devices/{deviceURL}/pictures

application/json

Delete every picture

Access scope : Public

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

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

GET

Pictures

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

application/json

Get a url where pictures can be exported within a zip file. Url contains a session id available for 30 seconds

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "cameraId" : "a camera id", "protocolType" : 1, "gatewayId" : "a gateway id", "urlTemplate" : "a url template", "sessionId" : "a session id" }

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

GET

Pictures

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

application/json

Get pictures references for a given camera in a time range, allowing the later retrieval of the images through a storage server.

Response contains a list of picture references and two picture url templates:
	-> a url template for the picture thumbnail
	-> a url template for the picture

Both url templates will look like to:
https://somewhere.com/getPicture?cameraid=@CAMERA_ID@&protocolType=@PROTOCOL_TYPE@&gatewayId=@GATEWAY_ID@&photoID=@PHOTO_ID@&sessionId=@SESSION_ID@

To use these templates, @CAMERA_ID@, @PROTOCOL_TYPE@, @GATEWAY_ID@, @PHOTO_ID@ and @SESSION_ID@ will have to be replaced by a correct values.

Note that the sessionId timeout is 30 seconds.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Camera device URL
Path Variable	from	120123456790	Start date (in ms)
Path Variable	to	120123456790	End date (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "sessionId" : "a session id",
  "gatewayId" : "a gateway id",
  "cameraId" : "a camera id",
  "pictureUrlTemplate" : "a picture url template",
  "thumbnailUrlTemplate" : "a thumbnail url template",
  "pictures" : [ {
    "pictureId" : 2,
    "timestamp" : 2
  } ]
}

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

GET

Pictures

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

application/json

Get pictures of a camera in a time range and pictures range

Same as getPictures operation but within a range of pictures.
This operation is useful to render a paginated pictures library.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Camera device URL
Path Variable	from	120123456790	Start date (in ms)
Path Variable	to	120123456790	End date (in ms)
Path Variable	offset	1	Pictures list offset
Path Variable	size	1	Number of pictures to retrieve

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "sessionId" : "a session id",
  "gatewayId" : "a gateway id",
  "cameraId" : "a camera id",
  "pictureUrlTemplate" : "a picture url template",
  "thumbnailUrlTemplate" : "a thumbnail url template",
  "pictures" : [ {
    "pictureId" : 2,
    "timestamp" : 2
  } ]
}

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

Device

Expand commands

GET

Device

/setup/devices/{deviceURL}

application/json

Get a particular setup device definition

Access scope : Public

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)

{
  "creationTime" : 1774337682887,
  "lastUpdateTime" : 1774337682909,
  "label" : "a device label",
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
  "shortcut" : false,
  "controllableName" : "core:StatefulClosableActuator",
  "metadata" : "some metadata",
  "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" : 120123456793
  } ],
  "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"
  } ],
  "available" : false,
  "enabled" : true,
  "placeOID" : "a place OID",
  "widget" : "a widget name",
  "type" : 1,
  "oid" : "the device UUID",
  "uiClass" : "a ui class"
}

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

This operation allows to delete a device

This operation is useful to delete IO actuators, RTS devices, RTD alarm system and sensors, EnOcean actuators and Ramses devices.

Access scope : Public

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

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

DeviceDeletionFailedEvent
Field name	Field description
Description	Device deletion from the gateway has failed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "name" : "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

POST

Device [DEPRECATED] since version 2020.3.4

/setup/devices/{deviceURL}/_delete

application/json

This operation allows to delete a device

This operation is useful to delete IO actuators, RTS devices, RTD alarm system and sensors, EnOcean actuators and Ramses devices.

Access scope : Public

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

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

DeviceDeletionFailedEvent
Field name	Field description
Description	Device deletion from the gateway has failed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "name" : "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

POST

Device

/setup/devices/{deviceURL}/_deleteCascade

application/json

This operation allows to delete a device

This operation starts an asynchronous workflow to delete a device, updating action groups, triggers and calendar days if necessary. If device protocol allows it, the device is also unpaired from the gateway. Only one device deletion workflow may be run at a time. Use the returned jobId and events to determine when the workflow is complete.

Access scope : Public

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

DeviceDeletionFailedEvent
Field name	Field description
Description	Device deletion from the gateway has failed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "name" : "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

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

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

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

GET

Device

/setup/devices/{deviceURL}/controllable

application/json

Get a particular setup device controllable definition

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	The url of the device

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "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"
}

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

PUT

Device

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

application/json

Relocate a device in an existing place

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL to relocate
Path Variable	placeOID	"string value"	Existing place OID where device is relocated

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "name" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

PUT

Device

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

application/json

Update the name of a device

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "name" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

PUT

Device

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

application/json

Update the name of a device

Rename all subsystems at once like newLabel-1, newLabel-2, ... Set to true by default.

Access scope : Public

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

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "name" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

PUT

Device

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

application/json

Update the name of a device and its measurement category

This will set the device attribute core:MeasurementCategory to the set newCategory parameter (See Appendix for details about supported measurement category values).

This operation is only supported by sensor device that has measurement behavior.

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "name" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

PUT

Device Type

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

application/json

Update device type with new device type

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	newDeviceType	2	New device type

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "name" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Device additional information

/setup/devices/additionalInformation

application/json

Get additional information

This operation returns  additional information.

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "templateId" : "a template id",
  "type" : "SERIAL_NUMBER",
  "label" : "a device additional info label",
  "value" : "a device additional info value",
  "rank" : 1,
  "unsafe" : true,
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
} ]

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

GET

Device additional information

/setup/devices/{deviceURL}/additionalInformation

application/json

Get additional information

This operation returns device additional information.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	The url of the device

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "templateId" : "a template id",
  "type" : "SERIAL_NUMBER",
  "label" : "a device additional info label",
  "value" : "a device additional info value",
  "rank" : 1,
  "unsafe" : true,
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
} ]

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

GET

Device additional information

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

application/json

Get additional information

This operation returns device additional information.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	The url of the device
Path Variable	templateId	"string value"	Additional information template id

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "templateId" : "a template id",
  "type" : "SERIAL_NUMBER",
  "label" : "a device additional info label",
  "value" : "a device additional info value",
  "rank" : 1,
  "unsafe" : true,
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
}

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

GET

Device attribute

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

application/json

Get a particular attribute of a requested product

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	The url of the device
Path Variable	name	"string value"	The name of the attribute

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "name" : "a device attribute name", "type" : 1, "value" : "a device attribute value" }

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

GET

Device attributes

/setup/devices/{deviceURL}/attributes

application/json

Retrieve attributes of requested products

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	The url of the device

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "name" : "a device attribute name", "type" : 1, "value" : "a device attribute value" } ]

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

PUT

Device controllable

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

application/json

Update device controllable with equivalent controllable

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	newControllableName	"string value"	New controllable name

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "name" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

PUT

Device controllable [DEPRECATED] since version 2018.3.3

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

application/json

Update device controllable with equivalent controllable

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	newControllableName	"string value"	New controllable name

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "name" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Device controllables

/setup/devices/{deviceURL}/alternativeControllables

application/json

Get all equivalent controllables to another one

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	[ "string value" ]

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

GET

Device firmware

/setup/devices/{deviceURL}/firmwareUpToDate

application/json

Check if device firmware is up-to-date

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "upToDate" : false, "notes" : [ { "some notes" : "some notes" } ] }

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

GET

Device firmware

/setup/devices/{deviceURL}/firmwareUpdateCapability

application/json

Check if device supports firmware update feature

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "supportsFirmwareUpdate" : false }

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

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

Update The device firmware to the next available version

Access scope : Public

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

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

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

DeviceFirmwareUpdateStartedEvent
Field name	Field description
Description	A firmware update started on the given device
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "gatewayId" : "a gateway id", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "name" : "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

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

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

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

GET

Device manufacturer references

/setup/devices/{deviceURL}/manufacturerReferences

application/json

Get all manufacturer references for the device

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "protocolType" : 1, "provider" : "a provider", "tag" : "a tag", "type" : "SPEC" } ]

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

PUT

Device metadata

/setup/devices/{deviceURL}/metadata

application/json

Update device metadata

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL to update
Request Body	(JSON)	{ "metadata" : "some metadata" }	Device metadata

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "name" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Device state

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

application/json

Get a particular state of a requested device

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	The url of the device
Path Variable	name	"string value"	The name of the state

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "name" : "a device state name", "type" : 1, "value" : "a device state value", "lastUpdateTime" : 120123456791 }

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

PUT

Device state

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

application/json

Update a device persistent state

Update the value of a given device state.
This operation is only supported on some specific device states (called 'persistent' device states') that may be modified directly from the API.

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "name" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Device states

/setup/devices/{deviceURL}/states

application/json

Retrieve states of requested device

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	The url of the device

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "name" : "a device state name", "type" : 1, "value" : "a device state value", "lastUpdateTime" : 120123456791 } ]

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

GET

Devices

/setup/devices

application/json

Get setup  definition

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

Access scope : Public

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" : 1774337682910,
  "lastUpdateTime" : 1774337682911,
  "label" : "a device label",
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
  "shortcut" : false,
  "controllableName" : "core:StatefulClosableActuator",
  "metadata" : "some metadata",
  "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" : 120123456793
  } ],
  "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"
  } ],
  "available" : false,
  "enabled" : true,
  "placeOID" : "a place OID",
  "widget" : "a widget name",
  "type" : 1,
  "oid" : "the device UUID",
  "uiClass" : "a ui class"
} ]

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

PUT

Devices

/setup/devices/link

application/json

Link devices by adding a groupId

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "name" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

Unlink devices by removing groupId

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "name" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

Unlink devices by removing groupId

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "controllableName" : "a controllable name", "label" : "a device updated event label", "placeOID" : "a place OID", "metadata" : "some metadata", "name" : "DeviceUpdatedEvent" }
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup 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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "name" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Devices controllable

/setup/devices/controllables/{controllableName}

application/json

Get all devices urls which have that controllable name

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	controllableName	"string value"	A controllable name

Response
Type	Name	Value	Description
Response Body	(JSON)	[ "string value" ]

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

GET

Devices controllables

/setup/devices/controllables

application/json

Get all device urls and sort them by their controllables names

Access scope : Public

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

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

GET

Devices firmware

/setup/devices/notUpToDate

application/json

Retrieve devices URLs which are not up-to-date

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ "string value" ]

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

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

Update the given devices firmwares to the next available version

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "gatewayId" : "a gateway id", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "name" : "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

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

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

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

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

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

POST

Devices growing index variations

/setup/devices/states/growingIndexes

application/json

Get growing indexes values variations on a given time slot

Access scope : Public

Parameters
Type	Name	Value	Description
Request Body	(JSON)	[ { "deviceUrl" : "a device url", "stateName" : "a state name", "from" : 1774370307089, "to" : 1774370307089 } ]	Device growing index variation requests

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "deviceUrl" : "a device url", "stateName" : "a state name", "delta" : 2 } ]

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

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 : Public

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

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

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

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

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "name" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

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

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 : Public

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

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

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

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

GET

hidden [DEPRECATED] since version 2018.3.3

/setup/devices/hidden

application/json

Get hidden devices

Hidden devices are devices that cannot be unpaired because of technical limitations but have been removed from the user interface

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "creationTime" : 1774337682910,
  "lastUpdateTime" : 1774337682911,
  "label" : "a device label",
  "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
  "shortcut" : false,
  "controllableName" : "core:StatefulClosableActuator",
  "metadata" : "some metadata",
  "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" : 120123456793
  } ],
  "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"
  } ],
  "available" : false,
  "enabled" : true,
  "placeOID" : "a place OID",
  "widget" : "a widget name",
  "type" : 1,
  "oid" : "the device UUID",
  "uiClass" : "a ui class"
} ]

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

Retrieve annual state history of a device within a time range

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "historyValues" : [ {
    "value" : "a device state history value value",
    "min" : 3,
    "max" : 4,
    "samples" : 2,
    "when" : 1774337682929
  } ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:LinearSpeedInMeterPerSecond"
}

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

GET

Annual stacked history values

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

application/json

Retrieve annual state history of a device within a time range with stacked values of other devices of the same type

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "stackedHistoryValues" : [ {
    "values" : [ 5 ],
    "minValues" : [ 4 ],
    "maxValues" : [ 6 ],
    "samples" : [ 2 ],
    "when" : 1774337682934
  } ],
  "stackLevels" : [ "some stack levels" ],
  "deviceCounts" : [ 1 ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:AngleInDegrees"
}

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

GET

Annual stacked states history values

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

application/json

Retrieve annual states history of a device within a time range with stacked values of other devices of the same type

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "stackedHistoryValues" : [ {
    "values" : [ 5 ],
    "minValues" : [ 4 ],
    "maxValues" : [ 6 ],
    "samples" : [ 2 ],
    "when" : 1774337682935
  } ],
  "stackLevels" : [ "some stack levels" ],
  "deviceCounts" : [ 1 ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:AngleInDegrees"
} ]

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

GET

Annual states history values

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

application/json

Retrieve annual state history of a device within a time range

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "historyValues" : [ {
    "value" : "a device state history value value",
    "min" : 3,
    "max" : 4,
    "samples" : 2,
    "when" : 1774337682930
  } ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:LinearSpeedInMeterPerSecond"
} ]

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

GET

Daily history values

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

application/json

Retrieve daily state history of a device within a time range

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "historyValues" : [ {
    "value" : "a device state history value value",
    "min" : 3,
    "max" : 4,
    "samples" : 2,
    "when" : 1774337682929
  } ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:LinearSpeedInMeterPerSecond"
}

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

GET

Daily stacked history values

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

application/json

Retrieve daily state history of a device within a time range with stacked values of other devices of the same type

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "stackedHistoryValues" : [ {
    "values" : [ 5 ],
    "minValues" : [ 4 ],
    "maxValues" : [ 6 ],
    "samples" : [ 2 ],
    "when" : 1774337682934
  } ],
  "stackLevels" : [ "some stack levels" ],
  "deviceCounts" : [ 1 ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:AngleInDegrees"
}

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

GET

Daily stacked history values

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

text/csv

Export daily stacked history values in CSV format

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

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

GET

Daily stacked states history values

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

application/json

Retrieve daily states history of a device within a time range with stacked values of other devices of the same type

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "stackedHistoryValues" : [ {
    "values" : [ 5 ],
    "minValues" : [ 4 ],
    "maxValues" : [ 6 ],
    "samples" : [ 2 ],
    "when" : 1774337682935
  } ],
  "stackLevels" : [ "some stack levels" ],
  "deviceCounts" : [ 1 ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:AngleInDegrees"
} ]

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

GET

Daily states history values

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

application/json

Retrieve daily states history of a device within a time range

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "historyValues" : [ {
    "value" : "a device state history value value",
    "min" : 3,
    "max" : 4,
    "samples" : 2,
    "when" : 1774337682930
  } ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:LinearSpeedInMeterPerSecond"
} ]

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

GET

Export history values

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

text/csv

Export all state values in CSV format - limited in time and in number of values - Contact support to know these limits

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved

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

GET

History values

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

application/json

Retrieve overall state history of a device within a time range

Max history query span is limited to 3 days if limit parameter is not set.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)
Request Parameter	limit	2	(Optional) Maximum number of values to retrieve

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "historyValues" : [ {
    "value" : "a device state history value value",
    "min" : 3,
    "max" : 4,
    "samples" : 2,
    "when" : 1774337682929
  } ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:LinearSpeedInMeterPerSecond"
}

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

GET

History values

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

text/csv

Export state values in history CSV format

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

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

GET

Monthly history values

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

application/json

Retrieve monthly state history of a device within a time range

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "historyValues" : [ {
    "value" : "a device state history value value",
    "min" : 3,
    "max" : 4,
    "samples" : 2,
    "when" : 1774337682929
  } ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:LinearSpeedInMeterPerSecond"
}

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

GET

Monthly history values [DEPRECATED] since version 2018.3.3

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

application/json

Retrieve monthly state history of a device within a time range

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "historyValues" : [ {
    "value" : "a device state history value value",
    "min" : 3,
    "max" : 4,
    "samples" : 2,
    "when" : 1774337682929
  } ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:LinearSpeedInMeterPerSecond"
}

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

GET

Monthly stacked history values

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

application/json

Retrieve monthly state history of a device in a time range with stacked values of other devices of the same type

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "stackedHistoryValues" : [ {
    "values" : [ 5 ],
    "minValues" : [ 4 ],
    "maxValues" : [ 6 ],
    "samples" : [ 2 ],
    "when" : 1774337682934
  } ],
  "stackLevels" : [ "some stack levels" ],
  "deviceCounts" : [ 1 ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:AngleInDegrees"
}

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

GET

Monthly stacked states history values

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

application/json

Retrieve monthly states history of a device in a time range with stacked values of other devices of the same type

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "stackedHistoryValues" : [ {
    "values" : [ 5 ],
    "minValues" : [ 4 ],
    "maxValues" : [ 6 ],
    "samples" : [ 2 ],
    "when" : 1774337682935
  } ],
  "stackLevels" : [ "some stack levels" ],
  "deviceCounts" : [ 1 ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:AngleInDegrees"
} ]

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

GET

Monthly states history values

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

application/json

Retrieve monthly states history of a device within a time range

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "historyValues" : [ {
    "value" : "a device state history value value",
    "min" : 3,
    "max" : 4,
    "samples" : 2,
    "when" : 1774337682930
  } ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:LinearSpeedInMeterPerSecond"
} ]

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

GET

Stacked history values

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

application/json

Retrieve overall state history of a device within a time range with stacked values of other devices of the same type

Max history query span is limited to 3 days.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	name	"string value"	State name for which history has to be retrieved
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "stackedHistoryValues" : [ {
    "values" : [ 5 ],
    "minValues" : [ 4 ],
    "maxValues" : [ 6 ],
    "samples" : [ 2 ],
    "when" : 1774337682934
  } ],
  "stackLevels" : [ "some stack levels" ],
  "deviceCounts" : [ 1 ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:AngleInDegrees"
}

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

GET

Stacked states history values

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

application/json

Retrieve overall states history of a device within a time range with stacked values of other devices of the same type

Max history query span is limited to 3 days.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "stackedHistoryValues" : [ {
    "values" : [ 5 ],
    "minValues" : [ 4 ],
    "maxValues" : [ 6 ],
    "samples" : [ 2 ],
    "when" : 1774337682935
  } ],
  "stackLevels" : [ "some stack levels" ],
  "deviceCounts" : [ 1 ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:AngleInDegrees"
} ]

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

GET

States History values

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

application/json

Retrieve overall states history of a device within a time range

Max history query span is limited to 3 days if limit parameter is not set.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	deviceURL	"string value"	Device URL
Path Variable	from	2	Start date: period lower bound (in ms)
Path Variable	to	2	End date: period higher bound (in ms)
Request Parameter	limit	2	(Optional) Maximum number of values to retrieve

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "historyValues" : [ {
    "value" : "a device state history value value",
    "min" : 3,
    "max" : 4,
    "samples" : 2,
    "when" : 1774337682930
  } ],
  "historizationMethod" : 1,
  "deviceUnit" : "core:LinearSpeedInMeterPerSecond"
} ]

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

Gateway

Expand commands

POST

Activate developer mode

/setup/gateways/{gatewayId}/developerMode

application/json

Activate developer mode for a gateway

Access scope : Public

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

POST

Activate module

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

application/json

activate a module for a gateway

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway
Path Variable	moduleId	"string value"	The id of the module

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

GET

Disconnection configuration

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

application/json

Private tags : [ disconnectionAlert ]

Get configuration for notification sent after gateway disconnection

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "timeout" : 1 }

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

PUT

Disconnection configuration

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

application/json

Private tags : [ disconnectionAlert ]

Update configuration for notification sent after gateway disconnection

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway
Request Body	(JSON)	{ "timeout" : 1 }

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

Generated events on method call

GatewayDownOptionsChangedEvent
Field name	Field description
Description	Gateway disconnection alert configuration has changed
JSON	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "timeout" : 1, "name" : "GatewayDownOptionsChangedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams
timeout	New timer between disconnection and notification (in seconds)

POST

Enable Auto Update

/setup/gateways/{gatewayId}/enableAutoUpdate

application/json

Enabled or disabled gateway's auto update

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Request Parameter	enable	false	(Optional) boolean

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

GET

Gateway

/setup/gateways/{gatewayId}

application/json

Get a particular gateway of a connected user setup

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "partners" : [ {
    "status" : "OWNER",
    "activated" : true,
    "name" : "a business partner name",
    "id" : "a partner id"
  } ],
  "placeOID" : "a place OID",
  "functions" : "some function names",
  "subType" : 1,
  "gatewayId" : "a gateway id",
  "mode" : "ACTIVE",
  "alive" : false,
  "autoUpdateEnabled" : true,
  "firmwareVersion" : "2023.1.4-1:30ccca5e458c342a95d28cd2667f431e:07029280615154e81c8205c83c8324e7",
  "timeReliable" : true,
  "updateStatus" : "UPDATING",
  "connectivity" : {
    "status" : "PARTIAL",
    "problems" : [ "NO_NTP" ],
    "protocolVersion" : "a protocol version"
  },
  "syncInProgress" : false,
  "upToDate" : true,
  "updateCriticityLevel" : "BLOCKING",
  "automaticUpdate" : false,
  "type" : 1
}

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

GET

Gateway

/setup/gateways/{gatewayId}/activeProtocols

application/json

Return the protocols activated on the gateway

Active protocol means that protocol can be used by the gateway.

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	[ 1 ]

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

PUT

Gateway

/setup/gateways/{gatewayId}/attach

application/json

Attaches a new gateway to the user's setup

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Request Body	(JSON)	{ "applicationId" : "an application id" }	(Optional)

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

GET

Gateway

/setup/gateways/{gatewayId}/availableProtocols

application/json

Return the protocols available on the gateway

Available protocol means that protocol is fully functional. Native protocol is available as soon as it is activated.
A protocol that needs a USB key plugged to the gateway is available only when USB key is plugged.

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	[ 1 ]

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

GET

Gateway

/setup/gateways/{gatewayId}/supportedProtocols

application/json

Return the protocols supported by the gateway

Supported protocol means protocol does not work currently but could work as soon protocol becomes active.

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	[ 1 ]

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

PUT

Gateway

/setup/gateways/{gatewayId}/update

application/json

Update gateway if necessary

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "details" : { "type" : "EXECUTION", "ownerKey" : "an owner key", "execId" : "an exec id" }, "updateStarted" : true }

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

GET

Gateway

/setup/gateways/{gatewayId}/usedActiveProtocols

application/json

Return the protocols activated on the gateway that were available at least once

Active protocol means that protocol can be used by the gateway. A protocol is considered as being used if it was available at least once in the past.

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	[ 1 ]

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

PUT

Gateway

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

application/json

Migrates the complete configuration of a gateway to another gateway. Server-side only : the target gateway is not updated yet.

This is usually useful when replacing a defective hardware

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	sourceGatewayId	"string value"	The gateway ID source
Path Variable	targetGatewayId	"string value"	The gateway ID destination
Request Parameter	allowIncompatibleProtocols	false	(Optional) allow incompatible protocols

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

PUT

Gateway

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

application/json

Migrates the complete configuration of a gateway to another gateway and start updating the target gateway.

This is usually useful when replacing a defective hardware

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	sourceGatewayId	"string value"	The gateway ID source
Path Variable	targetGatewayId	"string value"	The gateway ID destination
Request Parameter	allowIncompatibleProtocols	false	(Optional) allow incompatible protocols

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

GET

Gateway Synchronization

/setup/gateways/{gatewayId}/aliveAndReady

application/json

Return the gateway status

This operation allows testing and validating connectivity between a gateway and backend servers.
It returns true if the gateway is ready and alive.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway serial number to test

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "result" : false }

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

GET

Gateway Synchronization

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

application/json

Test if failed synchronization tasks exist for a given gateway

This operation tests if failed synchronization tasks still exist for the target gateway. (This test is independent from the gateway connectivity)
Note that this operation may return true even though a call to /setup/gateways/{gatewayId}/synchronization/inProgress returned false
because failed synchronization tasks may still exist.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway serial number to test

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "result" : false }

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

GET

Gateway Synchronization

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

application/json

Get a list of object categories containing failed synchronization tasks exist for a given gateway

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

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway serial number to test

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "result" : [ "CALENDAR_RULE" ] }

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

GET

Gateway Synchronization

/setup/gateways/{gatewayId}/synchronization/inProgress

application/json

Return the gateways synchronization status

This operation returns true if synchronization tasks are still in progress.
Note that even if this operation returns false, failed synchronization tasks may still exist if a connectivity loss or gateway crash occured.
To make sure the gateway is fully in sync with the server, see the /setup/gateways/{gatewayId}/synchronization/failedTasks operation

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway serial number to test

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "result" : false }

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

GET

Gateway Synchronization

/setup/gateways/{gatewayId}/synchronization/pendingTasks

application/json

Test if pending synchronization tasks exist for a given gateway

This operation tests if synchronization tasks still exist for the target gateway. (This test is independent from the gateway connectivity)
Note that this operation may return true even though a call to /setup/gateways/{gatewayId}/synchronized returned true
because failed synchronization tasks may still exist.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway serial number to test

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "result" : false }

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

POST

Gateway activate partner offer

/setup/gateways/{gatewayId}/partnerOffers/{partnerOfferId}/activate

application/json

Activate a partner offer by partner offer Id

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway
Path Variable	partnerOfferId	"string value"	The partner offer Id

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

GET

Gateway additional informations

/setup/gateways/{gatewayId}/additionalInformation

application/json

Get additional informations

This operation returns gateway additional informations.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "templateId" : "a template id",
  "type" : "SERIAL_NUMBER",
  "label" : "a gateway additional info label",
  "value" : "a gateway additional info value",
  "rank" : 1,
  "unsafe" : true,
  "gatewayId" : "a gateway id"
} ]

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

GET

Gateway additional informations

/setup/gateways/{gatewayId}/additionalInformation/{templateId}

application/json

Get additional information

This operation returns gateway additional information.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway
Path Variable	templateId	"string value"	Additional information template id

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "templateId" : "a template id",
  "type" : "SERIAL_NUMBER",
  "label" : "a gateway additional info label",
  "value" : "a gateway additional info value",
  "rank" : 1,
  "unsafe" : true,
  "gatewayId" : "a gateway id"
}

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

POST

Gateway deactivate partner offer

/setup/gateways/{gatewayId}/partnerOffers/{partnerOfferId}/deactivate

application/json

Deactivate a partner offer by partner offer Id

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway
Path Variable	partnerOfferId	"string value"	The partner offer Id

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

PUT

Gateway management

/setup/gateways/{gatewayId}/detach

application/json

Detach gateway from setup

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway
Request Body	(JSON)	{ "purgeDependencies" : false }	(Optional)

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

GET

Gateway management

/setup/gateways/{gatewayId}/functions

application/json

Get gateway functionalities

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway

Response
Type	Name	Value	Description
Response Body	(JSON)	[ "string value" ]

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

PUT

Gateway management

/setup/gateways/{gatewayId}/functions/{functionType}

application/json

Update gateway functionality

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway
Path Variable	functionType	"string value"	The name of the function
Request Body	(JSON)	{ "enabled" : false }

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

GET

Gateway version

/setup/gateways/{gatewayId}/version

application/json

Get gateway version

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway

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

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

GET

Gateways

/setup/gateways

application/json

Get every gateways of a connected user setup

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "partners" : [ {
    "status" : "OWNER",
    "activated" : true,
    "name" : "a business partner name",
    "id" : "a partner id"
  } ],
  "placeOID" : "a place OID",
  "functions" : "some function names",
  "subType" : 1,
  "gatewayId" : "a gateway id",
  "mode" : "ACTIVE",
  "alive" : false,
  "autoUpdateEnabled" : true,
  "firmwareVersion" : "2023.1.4-1:30ccca5e458c342a95d28cd2667f431e:07029280615154e81c8205c83c8324e7",
  "timeReliable" : true,
  "updateStatus" : "UPDATING",
  "connectivity" : {
    "status" : "PARTIAL",
    "problems" : [ "NO_NTP" ],
    "protocolVersion" : "a protocol version"
  },
  "syncInProgress" : false,
  "upToDate" : true,
  "updateCriticityLevel" : "BLOCKING",
  "automaticUpdate" : false,
  "type" : 1
} ]

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

GET

Get all partner offers ids

/setup/gateways/{gatewayId}/partnerOffers

application/json

Get all partner offers ids

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway

Response
Type	Name	Value	Description
Response Body	(JSON)	[ "string value" ]

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

GET

Get developer mode status

/setup/gateways/{gatewayId}/developerMode

application/json

Get the status of developer mode for a gateway

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "active" : false }

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

POST

KeepAlive

/setup/gateways/{gatewayId}/protocols/{protocolType}/keepAlive

application/json

This sends a keepAlive message to the given protocol

Per-session rate-limit : 1 calls per 1s period for this particular operation (keep-alive)

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The gateway ID
Path Variable	protocolType	1	The protocol type

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

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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])", "deviceStates" : [ { "name" : "a device state change item name", "type" : 1, "value" : "a device state change item value" } ], "name" : "DeviceStateChangedEvent" }
deviceStates	Updated device states
deviceURL	Device URL
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

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

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

POST

Refresh states

/setup/gateways/{gatewayId}/protocols/{protocolType}/devices/states/refresh

application/json

Refresh all devices states of given gateway and protocol

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

Access scope : Public

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

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

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

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

DELETE

deactivate module

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

application/json

deactivate a module for a gateway

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	gatewayId	"string value"	The id of the gateway
Path Variable	moduleId	"string value"	The id of the module

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

Interactive Notifications

Expand commands

GET

Setup interactive notification

/setup/interactiveNotifications/{interactiveNotificationOID}

application/json

Return an InteractiveNotification

This operation returns an InteractiveNotification object to be displayed.

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	interactiveNotificationOID	"string value"	Interactive notification id

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "actionMask" : 1, "text" : "a text", "subject" : "a subject", "oid" : "a notification OID", "date" : 1774337682847, "expirationDate" : 1774337682847 }

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

POST

Setup interactive notification

/setup/interactiveNotifications/{interactiveNotificationOID}/{actionType}

application/json

Complete an interactive notification

When the user clicks a button (except for cancel), this method should be called with the flag value of the clicked button.
The notification state is then changed on the server-side and the notification is moved to history

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	interactiveNotificationOID	"string value"	Interactive notification id
Path Variable	actionType	"string value"	Action type (OK,CANCEL,YES,NO)

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

GET

Setup interactive notifications

/setup/interactiveNotifications

application/json

Return a collection of interactive notification waiting for validation

This operation returns a collection of InteractiveNotification objects to be displayed one after the other.

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

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "actionMask" : 1, "text" : "a text", "subject" : "a subject", "oid" : "a notification OID", "date" : 1774337682847, "expirationDate" : 1774337682847 } ]

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

GET

Setup interactive notifications history

/setup/interactiveNotifications/history

application/json

Return a collection of interactive notification that were validated in the past

This operation returns a collection of InteractiveNotification objects to be displayed one after the other.

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

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "actionMask" : 1, "text" : "a text", "subject" : "a subject", "oid" : "a notification OID", "date" : 1774337682847, "expirationDate" : 1774337682847 } ]

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

Place

Expand commands

GET

Place

/setup/places

application/json

Get setup places starting from root

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1774337682959,
  "lastUpdateTime" : 1774337682959,
  "label" : "a place label",
  "type" : 1,
  "metadata" : "some metadata",
  "oid" : "the place UUID",
  "subPlaces" : [ {
    "creationTime" : 1774337682959,
    "lastUpdateTime" : 1774337682959,
    "label" : "a place label",
    "type" : 1,
    "metadata" : "some metadata",
    "oid" : "the place UUID",
    "subPlaces" : [ {
      "creationTime" : 1774337682959,
      "lastUpdateTime" : 1774337682959,
      "label" : "a place label",
      "type" : 1,
      "metadata" : "some metadata",
      "oid" : "the place UUID",
      "subPlaces" : [ ]
    } ]
  } ]
}

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

POST

Place

/setup/places/{parentPlaceOID}/subPlaces

application/json

Create place in user setup

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	parentPlaceOID	"string value"	The parent place of the new place
Request Body	(JSON)	{ "type" : "a place settings type", "label" : "a place settings 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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "placeOID" : "a place OID", "parentPlaceOID" : "a parent place OID", "type" : 1, "label" : "a place created event label", "metadata" : "some metadata", "name" : "PlaceCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
placeOID	Place OID
setupOID	Setup OID

POST

Place [DEPRECATED] since version 2018.3.3

/setup/places/{parentPlaceOID}/{label}/{type}

application/json

Create place in user setup

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "placeOID" : "a place OID", "parentPlaceOID" : "a parent place OID", "type" : 1, "label" : "a place created event label", "metadata" : "some metadata", "name" : "PlaceCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
placeOID	Place OID
setupOID	Setup OID

GET

Place

/setup/places/{placeOID}

application/json

Get places starting from a given place OID

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	placeOID	"string value"	The place OID

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1774337682959,
  "lastUpdateTime" : 1774337682959,
  "label" : "a place label",
  "type" : 1,
  "metadata" : "some metadata",
  "oid" : "the place UUID",
  "subPlaces" : [ {
    "creationTime" : 1774337682959,
    "lastUpdateTime" : 1774337682959,
    "label" : "a place label",
    "type" : 1,
    "metadata" : "some metadata",
    "oid" : "the place UUID",
    "subPlaces" : [ {
      "creationTime" : 1774337682959,
      "lastUpdateTime" : 1774337682959,
      "label" : "a place label",
      "type" : 1,
      "metadata" : "some metadata",
      "oid" : "the place UUID",
      "subPlaces" : [ ]
    } ]
  } ]
}

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

PUT

Place

/setup/places/{placeOID}

application/json

Update place settings : type, label and metadata

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	placeOID	"string value"	The place OID
Request Body	(JSON)	{ "type" : "a place settings type", "label" : "a place settings label", "metadata" : "some metadata" }	Place settings : type, label and metadata

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

Generated events on method call

PlaceUpdatedEvent
Field name	Field description
Description	An existing place has been updated
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "placeOID" : "a place OID", "parentPlaceOID" : "a parent place OID", "type" : 1, "label" : "a place updated event label", "metadata" : "some metadata", "name" : "PlaceUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
placeOID	Place OID
setupOID	Setup OID

DELETE Place /setup/places/{placeOID} application/json

Delete a place from user setup

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "placeOID" : "a place OID", "name" : "PlaceDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
placeOID	Place OID
setupOID	Setup OID

PUT

Place

/setup/places/{placeOID}/parent/{newParentPlaceOID}

application/json

Relocate an existing place in another parent place

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	placeOID	"string value"	The id of the place to update
Path Variable	newParentPlaceOID	"string value"	The new parent place

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

Generated events on method call

PlaceUpdatedEvent
Field name	Field description
Description	An existing place has been updated
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "placeOID" : "a place OID", "parentPlaceOID" : "a parent place OID", "type" : 1, "label" : "a place updated event label", "metadata" : "some metadata", "name" : "PlaceUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
placeOID	Place OID
setupOID	Setup OID

PUT

Place [DEPRECATED] since version 2018.3.3

/setup/places/{placeOID}/{newParentPlaceOID}

application/json

Relocate an existing place in another floor

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	placeOID	"string value"	The id of the place to update
Path Variable	newParentPlaceOID	"string value"	The new parrent place

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

Generated events on method call

PlaceUpdatedEvent
Field name	Field description
Description	An existing place has been updated
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "placeOID" : "a place OID", "parentPlaceOID" : "a parent place OID", "type" : 1, "label" : "a place updated event label", "metadata" : "some metadata", "name" : "PlaceUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
placeOID	Place OID
setupOID	Setup OID

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 : Public

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

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

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

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

Push

Private tags : [ push ]

Expand commands

POST

Android [DEPRECATED] since version 2018.3.3

/setup/subscribe/notification/android/{providerApplicationId}

application/json

Deprecated, use the new android firebase infrastructure. Subscribe an Android device to the notification service

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "pushSubscriptionOID" : "a push subscription OID", "name" : "PushSubscriptionCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Android [DEPRECATED] since version 2018.3.3

/setup/subscribe/notification/android/{providerApplicationId}/{deviceUdid}

application/json

Deprecated, use the new android firebase infrastructure. Get the current subscription configuration for a device (Android)

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	providerApplicationId	"string value"	The provider application Id
Path Variable	deviceUdid	"string value"	The device UDID

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "device" : {
    "creationTime" : 1774337682856,
    "lastUpdateTime" : 1774337682856,
    "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",
  "oid" : "the gcm subscriber json wrapper UUID",
  "jsonPayload" : false
}

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

DELETE

Android [DEPRECATED] since version 2018.3.3

/setup/subscribe/notification/android/{providerApplicationId}/{deviceUdid}

application/json

Deprecated, use DELETE on {subscriberOID} instead. Unsubscribe an Android device

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	providerApplicationId	"string value"	The provider application Id
Path Variable	deviceUdid	"string value"	The device UDID

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "pushSubscriptionOID" : "a push subscription OID", "name" : "PushSubscriptionDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

POST

AndroidFcm

/setup/subscribe/notification/android/fcm/{providerApplicationId}

application/json

Subscribe an Android device to the firebase notification service

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "pushSubscriptionOID" : "a push subscription OID", "name" : "PushSubscriptionCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

PUT

AndroidFcm

/setup/subscribe/notification/android/fcm/{providerApplicationId}

application/json

Update an Android firebase device subscription

Access scope : Public

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",
  "oid" : "the fcm subscriber json wrapper UUID"
}

Json description of the device to update and the configuration wanted

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

GET

AndroidFcm

/setup/subscribe/notification/android/fcm/{providerApplicationId}/{deviceUdid}

application/json

Get the current subscription configuration for a device (Android firebase)

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	providerApplicationId	"string value"	The provider application Id
Path Variable	deviceUdid	"string value"	The device UDID

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "device" : {
    "creationTime" : 1774337682858,
    "lastUpdateTime" : 1774337682858,
    "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",
  "oid" : "the fcm subscriber json wrapper UUID"
}

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

POST

Apple

/setup/subscribe/notification/apple/{providerApplicationId}

application/json

Subscribe an Apple device to the notification service

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "pushSubscriptionOID" : "a push subscription OID", "name" : "PushSubscriptionCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

PUT

Apple

/setup/subscribe/notification/apple/{providerApplicationId}

application/json

Update an Apple device subscription

Access scope : Public

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",
  "oid" : "the apns subscriber json wrapper UUID",
  "badge" : false,
  "alert" : true,
  "sound" : false
}

Json description of the device to update and the configuration wanted

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

GET

Apple

/setup/subscribe/notification/apple/{providerApplicationId}/{deviceUdid}

application/json

Get the current subscription configuration for a device (Apple)

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	providerApplicationId	"string value"	The provider application Id
Path Variable	deviceUdid	"string value"	The device UDID

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "device" : {
    "creationTime" : 1774337682853,
    "lastUpdateTime" : 1774337682853,
    "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",
  "oid" : "the apns subscriber json wrapper UUID",
  "badge" : false,
  "alert" : true,
  "sound" : false
}

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

DELETE

Apple [DEPRECATED] since version 2018.3.3

/setup/subscribe/notification/apple/{providerApplicationId}/{deviceUdid}

application/json

Deprecated, use DELETE on {subscriberOID} instead. Unsubscribe an Apple device

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	providerApplicationId	"string value"	The provider application Id
Path Variable	deviceUdid	"string value"	The device UDID

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "pushSubscriptionOID" : "a push subscription OID", "name" : "PushSubscriptionDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

GET

Devices

/setup/subscribe/notification/devices/{applicationId}

application/json

Get all push devices for connected endUser from functional application id

Access scope : Public

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" : 1774337682868,
        "lastUpdateTime" : 1774337682868,
        "udid" : "a udid",
        "model" : "a model",
        "version" : "a version",
        "name" : "a push device name",
        "metadata" : "some metadata"
      }
    } ],
    "androidDevices" : [ {
      "subscriberOID" : "a subscriber OID",
      "device" : {
        "creationTime" : 1774337682868,
        "lastUpdateTime" : 1774337682868,
        "udid" : "a udid",
        "model" : "a model",
        "version" : "a version",
        "name" : "a push device name",
        "metadata" : "some metadata"
      }
    } ],
    "androidFcmDevices" : [ {
      "subscriberOID" : "a subscriber OID",
      "device" : {
        "creationTime" : 1774337682868,
        "lastUpdateTime" : 1774337682869,
        "udid" : "a udid",
        "model" : "a model",
        "version" : "a version",
        "name" : "a push device name",
        "metadata" : "some metadata"
      }
    } ],
    "windowsDevices" : [ {
      "subscriberOID" : "a subscriber OID",
      "device" : {
        "creationTime" : 1774337682868,
        "lastUpdateTime" : 1774337682868,
        "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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "pushSubscriptionOID" : "a push subscription OID", "name" : "PushSubscriptionDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

DELETE Notification /setup/subscribe/notification/{subscriberOID} application/json

Unsubscribe a device from the notification service

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "pushSubscriptionOID" : "a push subscription OID", "name" : "PushSubscriptionDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

DELETE

Notifications

/setup/subscribe/notification/all

application/json

Unsubscribe a user from notification service for all the setups on his device

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "pushSubscriptionOID" : "a push subscription OID", "name" : "PushSubscriptionDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

POST

Windows

/setup/subscribe/notification/windows/{providerApplicationId}

application/json

Subscribe a Windows device to the notification service

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "pushSubscriptionOID" : "a push subscription OID", "name" : "PushSubscriptionCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup 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

Update a Windows device subscription

Access scope : Public

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

Get the current subscription configuration for a device (Windows)

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	providerApplicationId	"string value"	The provider application Id
Path Variable	deviceUdid	"string value"	The device UDID

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "device" : {
    "creationTime" : 1774337682861,
    "lastUpdateTime" : 1774337682861,
    "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"
}

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

DELETE

Windows [DEPRECATED] since version 2018.3.3

/setup/subscribe/notification/windows/{providerApplicationId}/{deviceUdid}

application/json

Deprecated, use DELETE on {subscriberOID} instead. Unsubscribe a Windows device

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	providerApplicationId	"string value"	The provider application Id
Path Variable	deviceUdid	"string value"	The device UDID

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "pushSubscriptionOID" : "a push subscription OID", "name" : "PushSubscriptionDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID

Secrets

Expand commands

POST

Secret

/setup/secrets

application/json

Create a secret

Access scope : Public

Parameters
Type	Name	Value	Description
Request Body	(JSON)	{ "userId" : "a user id", "label" : "a setup secret label", "targetType" : "ACTION_GROUP", "targetId" : "a target id", "exclusive" : false, "scopeName" : "Google.smarthome" }

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

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

PUT

Secret

/setup/secrets/{OID}

application/json

Update a secret

Access scope : Public

Parameters

Type

Name

Value

Description

Path Variable

OID

"string value"

Request Body

(JSON)

{
  "userId" : "a user id",
  "label" : "a setup secret label",
  "targetType" : "ACTION_GROUP",
  "targetId" : "a target id",
  "exclusive" : false,
  "scopeName" : "Google.smarthome",
  "oid" : "the setup secret UUID"
}

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

DELETE

Secret

/setup/secrets/{OID}

application/json

Delete a secret

Access scope : Public

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

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

PUT

Secret

/setup/secrets/{OID}/value

application/json

Update a secret value

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	OID	"string value"
Request Body	(JSON)	{ }

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

GET

Secrets

/setup/secrets/scope/{scopeName}

application/json

List secrets

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	scopeName	"string value"

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "setupOID" : "a setup OID",
  "userId" : "a user id",
  "label" : "a setup secret label",
  "targetType" : "ACTION_GROUP",
  "targetId" : "a target id",
  "exclusive" : false,
  "scopeName" : "Google.smarthome",
  "oid" : "the setup secret UUID"
} ]

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

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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "serviceId" : "a service id", "url" : "a url", "name" : "ExternalServiceURLEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
serviceId	The service ID
setupOID	Setup OID
url	The requested URL

Third-Party

Expand commands

GET

Activated Models

/setup/thirdparty/activated

application/json

Get the activated third party model for current setup

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "thirdPartyModelSetupUsers" : [ {
    "creationTime" : 1774337683226,
    "lastUpdateTime" : 1774337683226,
    "userId" : "a user id",
    "setupOID" : "a setup OID",
    "modelType" : 1,
    "thirdPartyUserId" : "a third party user id",
    "serviceReference" : "a service reference",
    "sync" : false,
    "oid" : "the third party model setup user UUID"
  } ],
  "activatedModels" : [ {
    "modelId" : 1,
    "modelLabel" : "a model label"
  } ]
}

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

GET

Security status

/setup/thirdparty/model/{modelName}/security/status

application/json

Get the security status of a third party model

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	modelName	"string value"

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "status" : "some status", "remaining" : 120123456790 }

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

POST

Security unlock

/setup/thirdparty/model/{modelName}/security/unlock

application/json

Unlock security actions of a third party model

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	modelName	"string value"

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

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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "zoneOID" : "a zone OID", "type" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "name" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup 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 : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "zoneOID" : "a zone OID", "type" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "name" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
zoneOID	Zone OID

POST

Items

/setup/zones/{sourceZoneOID}/items/relocate/{targetZoneOID}

application/json

Relocate items to another zone in user setup

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "zoneOID" : "a zone OID", "type" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "name" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
zoneOID	Zone OID

GET

Items

/setup/zones/{zoneOID}/items

application/json

Get the items of a zone

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	zoneOID	"string value"	The id of the zone

Response
Type	Name	Value	Description
Response Body	(JSON)	[ { "itemType" : "device", "deviceOID" : "a device OID", "deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])" } ]

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

POST

Items

/setup/zones/{zoneOID}/items

application/json

Add items to a zone in user setup

Access scope : Public

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

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "zoneOID" : "a zone OID", "type" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "name" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
zoneOID	Zone OID

PUT

Items [DEPRECATED] since version 2018.3.3

/setup/zones/{zoneOID}/items

application/json

Relocate items to a zone in user setup

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "zoneOID" : "a zone OID", "type" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "name" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
zoneOID	Zone OID

DELETE

Items [DEPRECATED] since version 2018.3.3

/setup/zones/{zoneOID}/items

application/json

Remove items from a zone in user setup

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "zoneOID" : "a zone OID", "type" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "name" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
zoneOID	Zone OID

POST

Items

/setup/zones/{zoneOID}/items/_delete

application/json

Remove items from a zone in user setup

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "zoneOID" : "a zone OID", "type" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "name" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
zoneOID	Zone OID

POST Zone /setup/zones application/json

Create zone in user setup

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "zoneOID" : "a zone OID", "type" : 1, "label" : "a zone created event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "name" : "ZoneCreatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
zoneOID	Zone OID

GET

Zone

/setup/zones/{zoneOID}

application/json

Get a zone of a user setup

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	zoneOID	"string value"	The id of zone to retrieve

Response

Type

Name

Value

Description

Response Body

(JSON)

{
  "creationTime" : 1774337682970,
  "lastUpdateTime" : 1774337682976,
  "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"
}

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

PUT

Zone

/setup/zones/{zoneOID}

application/json

Update zone

Access scope : Public

Parameters

Type

Name

Value

Description

Path Variable

zoneOID

"string value"

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 desired zone to update

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

DELETE Zone /setup/zones/{zoneOID} application/json

Delete a zone from user setup.

Access scope : Public

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "zoneOID" : "a zone OID", "name" : "ZoneDeletedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
zoneOID	Zone OID

PUT

Zone

/setup/zones/{zoneOID}/{type}/{label}

application/json

Update zone type and label

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	zoneOID	"string value"	Zone OID to update
Path Variable	type	1	New zone type
Path Variable	label	"string value"	New zone label

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	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "zoneOID" : "a zone OID", "type" : 1, "label" : "a zone updated event label", "deviceURLs" : [ "some device URLs" ], "placeOIDs" : [ "some place OIDs" ], "name" : "ZoneUpdatedEvent" }
owningPartners	Owning partners of the parent entity (setup, ...)) . only available in event streams
setupOID	Setup OID
zoneOID	Zone OID

GET

Zones

/setup/zones

application/json

Get all zones of a user setup

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "creationTime" : 1774337682978,
  "lastUpdateTime" : 1774337682978,
  "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"
} ]

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

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

Create a new setup trigger : see asset-specs for scheduling Intervals composition (exhaustive but non-functional example)

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "name" : "GatewaySynchronizationStartedEvent" }
gatewayId	Gateway id
owningPartner	Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams

SetupTriggerCreatedEvent
Field name	Field description
Description	A setup trigger has been created
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" : 1774370307418, "lastUpdateTime" : 1774370307419, "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 } } ], "name" : "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

SetupTriggerCreationFailedEvent
Field name	Field description
Description	A setup trigger could not be created
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "setupTriggerType" : 1, "setupTriggerOID" : "a setup trigger OID", "setupTriggerId" : "a setup trigger id", "name" : "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

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

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

Update an existing setup trigger : see asset-specs for scheduling Intervals composition (exhaustive but non-functional example)

Access scope : Public

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

SetupTriggerUpdatedEvent
Field name	Field description
Description	A setup trigger has been updated
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "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" : 1774370307427, "lastUpdateTime" : 1774370307428, "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 } } ], "name" : "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

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

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

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

Test a setup trigger definition, executing its effects : see asset-specs for scheduling Intervals composition (exhaustive but non-functional example)

Access scope : Public

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

test a single discrete trigger effect

Access scope : Public

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

Get a setup trigger by type and OID

Access scope : Public

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" : 1774337683158,
    "lastUpdateTime" : 1774337683177,
    "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" : 1774337683176,
          "lastUpdateTime" : 1774337683177,
          "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

Delete a setup trigger

Access scope : Public

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

SetupTriggerDeletedEvent
Field name	Field description
Description	A setup trigger has been deleted
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "setupTriggerType" : 1, "setupTriggerOID" : "a setup trigger OID", "name" : "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

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

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

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

Update a setup trigger activation mode

Access scope : Public

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

SetupTriggerModeChangeFailedEvent
Field name	Field description
Description	The scheduling mode of a setup trigger could not be changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "setupTriggerType" : 1, "setupTriggerOID" : "a setup trigger OID", "name" : "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

SetupTriggerModeChangedEvent
Field name	Field description
Description	The scheduling mode of a setup trigger has changed
JSON	{ "timestamp" : 2, "owningPartners" : [ "some owning partners" ], "setupOID" : "a setup OID", "setupTriggerType" : 1, "setupTriggerOID" : "a setup trigger OID", "newMode" : 1, "name" : "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

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

Get a setup trigger status

Access scope : Public

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

Get all setup triggers

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

Access scope : Public

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "ifThenSetupTrigger" : {
    "creationTime" : 1774337683179,
    "lastUpdateTime" : 1774337683180,
    "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" : 1774337683179,
          "lastUpdateTime" : 1774337683179,
          "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

Get all setup triggers of a given type

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	type	"string value"	Setup trigger type

Response

Type

Name

Value

Description

Response Body

(JSON)

[ {
  "ifThenSetupTrigger" : {
    "creationTime" : 1774337683179,
    "lastUpdateTime" : 1774337683180,
    "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" : 1774337683179,
          "lastUpdateTime" : 1774337683179,
          "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

Get all setup triggers status

Access scope : Public

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

Get trigger status.

Access scope : Public

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "enabled" : false }

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

PUT Setup trigger status /triggers/status application/json

Update trigger status.

Access scope : Public

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	{ "timestamp" : 2, "owningPartner" : "an owning partner", "gatewayId" : "A gateway id (ex: 0101-1234-5678)", "functionType" : 1, "enabled" : false, "name" : "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

Terms of use

Expand commands

Accounts management

Expand commands

POST

TermsOfUse

/termsOfUse/{gatewayId}/accept/{token}

application/json

Accept Terms of Use given a token. A token can only be used once.

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "TermsOfUseValidated" : false }

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

POST

TermsOfUse

/termsOfUse/{gatewayId}/decline/{token}

application/json

Decline Terms of Use given a token. A token can only be used once.

Access scope : Public

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

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "TermsOfUseDeclined" : false }

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

Utils

Expand commands

Location utils

Expand commands

GET

Location Details by postcode

/utils/location/countries/{countryNameOrCode}/postcodes/{postcode}/cities

application/json

Get cities for given country code and postcode

Access scope : Public

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

Get country cities which names start by a given prefix without secondary zones

Access scope : Public

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

Get country cities which names start by a given prefix with options

Access scope : Public

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

Get postcode pattern for given country name or code

Access scope : Public

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

Get server time and details for a given timezone

Access scope : Public

Parameters
Type	Name	Value	Description
Path Variable	timeZoneName	"string value"	The timezone name

Response
Type	Name	Value	Description
Response Body	(JSON)	{ "serverTime" : 2, "rawTzOffset" : 2, "currentTzOffset" : 2, "dstSavings" : 1, "usingNorthernHemisphereDST" : false }

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

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