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 : Full enduser API access (enduser/*)
> Test operation
|
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
[ {
"creationTime" : 1769503155350,
"lastUpdateTime" : 1769503155350,
"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" : 1769503155350,
"lastUpdateTime" : 1769503155350,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
{
"label" : "a calendar day label",
"type" : "WORK_DAY",
"dayTimeTriggers" : [ {
"startActionGroupTimeTrigger" : {
"triggerType" : "DAWN",
"minutes" : 1,
"hours" : 1,
"metadata" : "some metadata",
"enabled" : false,
"duskOffset" : 1,
"dawnOffset" : 1,
"randomTimeOffset" : 8,
"alwaysBeforeHours" : 5,
"alwaysBeforeMinutes" : 7,
"alwaysAfterHours" : 4,
"alwaysAfterMinutes" : 9,
"actionGroupOID" : "an action group OID",
"localActionGroup" : {
"label" : "a managed action group label",
"metadata" : "some metadata",
"shortcut" : true,
"notificationTypeMask" : 1,
"notificationCondition" : "ALWAYS",
"notificationText" : "a notification text",
"notificationTitle" : "a notification title",
"targetEmailAddresses" : [ "some target email addresses" ],
"targetPhoneNumbers" : [ "some target phone numbers" ],
"targetPushSubscriptions" : [ "some target push subscriptions" ],
"actions" : [ {
"deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
"commands" : [ {
"type" : 1,
"name" : "a command name",
"parameters" : [ "some parameters" ],
"sensitiveParametersIndexes" : [ 1 ],
"authentication" : "an authentication",
"delay" : 1,
"lockLevel" : 13
} ]
} ]
}
}
} ],
"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
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
GatewaySynchronizationEndedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
CalendarDayCreatedEvent
| 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" : 1769533841240,
"lastUpdateTime" : 1769533841240,
"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"
} |
| Field name |
Field description |
| calendarDayOID |
Calendar day OID |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
|
|
| PUT |
Calendar day
|
/setup/calendar/days
|
application/json |
|
Update a calendar day.
Access scope : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
{
"label" : "a calendar day label",
"type" : "WORK_DAY",
"dayTimeTriggers" : [ {
"startActionGroupTimeTrigger" : {
"triggerType" : "DAWN",
"minutes" : 1,
"hours" : 1,
"metadata" : "some metadata",
"enabled" : false,
"duskOffset" : 1,
"dawnOffset" : 1,
"randomTimeOffset" : 8,
"alwaysBeforeHours" : 5,
"alwaysBeforeMinutes" : 7,
"alwaysAfterHours" : 4,
"alwaysAfterMinutes" : 9,
"actionGroupOID" : "an action group OID",
"localActionGroup" : {
"label" : "a managed action group label",
"metadata" : "some metadata",
"shortcut" : true,
"notificationTypeMask" : 1,
"notificationCondition" : "ALWAYS",
"notificationText" : "a notification text",
"notificationTitle" : "a notification title",
"targetEmailAddresses" : [ "some target email addresses" ],
"targetPhoneNumbers" : [ "some target phone numbers" ],
"targetPushSubscriptions" : [ "some target push subscriptions" ],
"actions" : [ {
"deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
"commands" : [ {
"type" : 1,
"name" : "a command name",
"parameters" : [ "some parameters" ],
"sensitiveParametersIndexes" : [ 1 ],
"authentication" : "an authentication",
"delay" : 1,
"lockLevel" : 13
} ]
} ],
"oid" : "the managed action group UUID"
}
}
} ],
"metadata" : "some metadata",
"oid" : "the calendar day UUID"
} |
Json description of the calendar day to update
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
GatewaySynchronizationStartedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
CalendarDayUpdatedEvent
| 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" : 1769533841246,
"lastUpdateTime" : 1769533841246,
"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"
} |
| Field name |
Field description |
| calendarDayOID |
Calendar day OID |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
GatewaySynchronizationEndedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155345,
"lastUpdateTime" : 1769503155346,
"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" : 1769503155345,
"lastUpdateTime" : 1769503155346,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
oid
|
"string value" |
Calendar day's oid to delete
|
HTTP Status Code
| Code |
Message |
Meaning |
|
204
|
NO_CONTENT |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
|
Generated events on method call
GatewaySynchronizationEndedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
CalendarDayDeletedEvent
| 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"
} |
| Field name |
Field description |
| calendarDayOID |
Calendar day OID |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
GatewaySynchronizationStartedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
|
|
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155345,
"lastUpdateTime" : 1769503155346,
"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" : 1769503155345,
"lastUpdateTime" : 1769503155346,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
[ {
"weeklyCalendarRule" : {
"creationTime" : 1769503155322,
"lastUpdateTime" : 1769503155341,
"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" : 1769503155324,
"lastUpdateTime" : 1769503155341,
"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" : 1769503155336,
"lastUpdateTime" : 1769503155341,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
CalendarRuleCreatedEvent
| 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"
} |
| Field name |
Field description |
| 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
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
GatewaySynchronizationEndedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
|
|
| PUT |
Calendar rule
|
/setup/calendar/rules
|
application/json |
|
Update a calendar rule.
Access scope : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
GatewaySynchronizationEndedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
oid
|
"string value" |
Calendar rule's oid
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
{
"weeklyCalendarRule" : {
"creationTime" : 1769503155347,
"lastUpdateTime" : 1769503155348,
"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" : 1769503155347,
"lastUpdateTime" : 1769503155348,
"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" : 1769503155347,
"lastUpdateTime" : 1769503155348,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
oid
|
"string value" |
Calendar rule's oid to delete
|
HTTP Status Code
| Code |
Message |
Meaning |
|
204
|
NO_CONTENT |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
|
Generated events on method call
GatewaySynchronizationStartedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
GatewaySynchronizationEndedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
CalendarRuleDeletedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
[ {
"weeklyCalendarRule" : {
"priority" : 1,
"calendarDayOID" : "a calendar day OID",
"finalRule" : true,
"randomTimeRange" : 1,
"dayType" : "HOLIDAY",
"enabled" : false,
"metadata" : "some metadata",
"startTimeHours" : 1,
"startTimeMinutes" : 1,
"endTimeHours" : 1,
"endTimeMinutes" : 1,
"localCalendarDay" : {
"label" : "a calendar day label",
"type" : "DAY_OFF_AT_HOME",
"dayTimeTriggers" : [ {
"startActionGroupTimeTrigger" : {
"triggerType" : "DUSK",
"minutes" : 1,
"hours" : 1,
"metadata" : "some metadata",
"enabled" : true,
"duskOffset" : 1,
"dawnOffset" : 1,
"randomTimeOffset" : 9,
"alwaysBeforeHours" : 6,
"alwaysBeforeMinutes" : 8,
"alwaysAfterHours" : 5,
"alwaysAfterMinutes" : 10,
"actionGroupOID" : "an action group OID",
"localActionGroup" : {
"label" : "a managed action group label",
"metadata" : "some metadata",
"shortcut" : false,
"notificationTypeMask" : 1,
"notificationCondition" : "ON_SUCCESS",
"notificationText" : "a notification text",
"notificationTitle" : "a notification title",
"targetEmailAddresses" : [ "some target email addresses" ],
"targetPhoneNumbers" : [ "some target phone numbers" ],
"targetPushSubscriptions" : [ "some target push subscriptions" ],
"actions" : [ {
"deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])",
"commands" : [ {
"type" : 1,
"name" : "a command name",
"parameters" : [ "some parameters" ],
"sensitiveParametersIndexes" : [ 1 ],
"authentication" : "an authentication",
"delay" : 1,
"lockLevel" : 14
} ]
} ]
}
}
} ],
"metadata" : "some metadata"
},
"startYear" : 1,
"startMonth" : 1,
"startDay" : 1,
"endYear" : 1,
"endMonth" : 1,
"endDay" : 1,
"period" : 1,
"presenceFilter" : "NO_FILTER",
"dayMask" : 1
}
} ] |
Json description of the set of calendar rules to create
|
|
Request Parameter
|
withTimeValidityChecks
|
false |
(Optional)
(Default: true)
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
{
"calendarRulesIds" : [ "some calendar rules ids" ],
"calendarRulesOIDs" : [ "some calendar rules OIDs" ]
} |
|
HTTP Status Code
| Code |
Message |
Meaning |
|
201
|
CREATED |
The request has been fulfilled and resulted in a new resource being created
|
Generated events on method call
GatewaySynchronizationStartedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
GatewaySynchronizationEndedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
CalendarRuleCreatedEvent
| 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"
} |
| Field name |
Field description |
| 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 rules
|
/setup/calendar/ruleSet
|
application/json |
|
Update a set of calendar rules.
Access scope : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
GatewaySynchronizationEndedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
[ "string value" ] |
Calendar rules oids to delete
|
HTTP Status Code
| Code |
Message |
Meaning |
|
204
|
NO_CONTENT |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
|
Generated events on method call
GatewaySynchronizationEndedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
CalendarRuleDeletedEvent
| 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"
} |
| Field name |
Field description |
| calendarRuleOID |
Calendar rule OID |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
GatewaySynchronizationStartedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
|
|
| GET |
Setup calendar status
|
/setup/calendar/status
|
application/json |
|
Get calendar status.
Access scope : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
{
"enabled" : false
} |
Calendar status
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
GatewayFunctionChangedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155248,
"lastUpdateTime" : 1769503155269,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
deviceURL
|
"string value" |
Device URL to update
|
|
Request Body
|
(JSON)
|
{
"purgeHistory" : true,
"deleteAllSubSystems" : true,
"deleteEmptyCalendarDays" : false,
"forced" : false
} |
(Optional)
Json description of the calendar day to create
|
HTTP Status Code
| Code |
Message |
Meaning |
|
204
|
NO_CONTENT |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
|
Generated events on method call
DeviceDeletionFailedEvent
| 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"
} |
| Field name |
Field description |
| deviceURL |
Device URL |
| failureType |
Failure type |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
DeviceRemovedEvent
| 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"
} |
| Field name |
Field description |
| deviceURL |
Device URL |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| deviceURL |
Device URL |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
DeviceDeletionFailedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
deviceURL
|
"string value" |
Device URL to delete
|
|
Request Body
|
(JSON)
|
{
"purgeHistory" : true,
"deleteAllSubSystems" : true,
"deleteEmptyCalendarDays" : false,
"forced" : false
} |
(Optional)
Delete options
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
{
"jobId" : "string value"
} |
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
DeviceRemovedEvent
| 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"
} |
| Field name |
Field description |
| deviceURL |
Device URL |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
SetupJobFailedEvent
| Description |
An asynchronous job has failed |
| JSON |
{
"timestamp" : 2,
"owningPartners" : [ "some owning partners" ],
"setupOID" : "a setup OID",
"jobId" : "a job id",
"name" : "SetupJobFailedEvent"
} |
| Field name |
Field description |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
DeviceDeletionFailedEvent
| 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"
} |
| Field name |
Field description |
| deviceURL |
Device URL |
| failureType |
Failure type |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
SetupJobCompletedEvent
| Description |
An asynchronous job has completed successfully |
| JSON |
{
"timestamp" : 2,
"owningPartners" : [ "some owning partners" ],
"setupOID" : "a setup OID",
"jobId" : "a job id",
"name" : "SetupJobCompletedEvent"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 controllables [DEPRECATED]
since version 2018.3.3
|
/setup/devices/{deviceURL}/equivalentControllables
|
application/json |
|
Get all equivalent controllables to another one
Access scope : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
deviceURL
|
"string value" |
Device URL to update
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
DeviceFirmwareUpdateCompletedEvent
| 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"
} |
| Field name |
Field description |
| deviceURL |
Device URL |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
DeviceFirmwareUpdateFailedEvent
| 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"
} |
| Field name |
Field description |
| deviceURL |
Device URL |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
GatewayFirmwareUpdateFailedEvent
| 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"
} |
| Field name |
Field description |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
GatewayFirmwareUpdateStartedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
The gateway id |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
DeviceFirmwareUpdateStartedEvent
| 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"
} |
| Field name |
Field description |
| 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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155271,
"lastUpdateTime" : 1769503155272,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
{
"devicesURL" : [ "a devices URL" ]
} |
|
HTTP Status Code
| Code |
Message |
Meaning |
|
204
|
NO_CONTENT |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
|
Generated events on method call
DeviceUpdatedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
{
"devicesURL" : [ "a devices URL" ]
} |
|
HTTP Status Code
| Code |
Message |
Meaning |
|
204
|
NO_CONTENT |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
|
Generated events on method call
DeviceUpdatedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
DeviceStateChangedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
[ "string value" ] |
List of devices URLs to update
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
GatewayFirmwareUpdateCompletedEvent
| 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"
} |
| Field name |
Field description |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
GatewayFirmwareUpdateStartedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
The gateway id |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
DeviceFirmwareUpdateStartedEvent
| 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"
} |
| Field name |
Field description |
| deviceURL |
The device address |
| gatewayId |
The gateway id |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
GatewayFirmwareUpdateFailedEvent
| 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"
} |
| Field name |
Field description |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
DeviceFirmwareUpdateFailedEvent
| 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"
} |
| Field name |
Field description |
| deviceURL |
Device URL |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
DeviceFirmwareUpdateCompletedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
[ {
"deviceUrl" : "a device url",
"stateName" : "a state name",
"from" : 1769533841155,
"to" : 1769533841155
} ] |
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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
[ "string value" ] |
(Optional)
URLs of the devices to refresh
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
DeviceStateChangedEvent
| 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"
} |
| Field name |
Field description |
| deviceStates |
Updated device states |
| deviceURL |
Device URL |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
RefreshAllDevicesStatesCompletedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
RefreshAllDevicesStatesFailedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
|
|
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
RefreshAllDevicesStatesFailedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
DeviceStateChangedEvent
| 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"
} |
| Field name |
Field description |
| deviceStates |
Updated device states |
| deviceURL |
Device URL |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
RefreshAllDevicesStatesCompletedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
deviceURL
|
"string value" |
Device URL
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
RefreshAllDevicesStatesFailedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
DeviceStateChangedEvent
| 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"
} |
| Field name |
Field description |
| deviceStates |
Updated device states |
| deviceURL |
Device URL |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
RefreshAllDevicesStatesCompletedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
[ {
"creationTime" : 1769503155271,
"lastUpdateTime" : 1769503155272,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155291
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155286
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155286
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155291
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155291
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155286
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155286
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155291
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
|
|
|
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155291
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155291
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155291
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155286
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155286
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155291
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155286
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155286
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155291
} ],
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
gatewayId
|
"string value" |
The id of the gateway
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
|
|
| POST |
Activate module
|
/setup/gateways/{gatewayId}/modules/{moduleId}
|
application/json |
|
activate a module for a gateway
Access scope : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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"
} ],
"functions" : "some function names",
"mode" : "ACTIVE",
"subType" : 1,
"gatewayId" : "a gateway id",
"placeOID" : "a place OID",
"alive" : false,
"autoUpdateEnabled" : true,
"firmwareVersion" : "2023.1.4-1:30ccca5e458c342a95d28cd2667f431e:07029280615154e81c8205c83c8324e7",
"timeReliable" : true,
"upToDate" : true,
"updateStatus" : "UPDATING",
"updateCriticityLevel" : "BLOCKING",
"automaticUpdate" : false,
"connectivity" : {
"status" : "PARTIAL",
"problems" : [ "NO_NTP" ],
"protocolVersion" : "a protocol version"
},
"syncInProgress" : 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 [DEPRECATED]
since version 2018.3.3
|
/setup/gateways/{gatewayId}/synchronized
|
application/json |
|
Return the gateways synchronization status
DEPRECATED : use /setup/gateways/{gatewayId}/aliveAndReady
Access scope : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
[ {
"partners" : [ {
"status" : "OWNER",
"activated" : true,
"name" : "a business partner name",
"id" : "a partner id"
} ],
"functions" : "some function names",
"mode" : "ACTIVE",
"subType" : 1,
"gatewayId" : "a gateway id",
"placeOID" : "a place OID",
"alive" : false,
"autoUpdateEnabled" : true,
"firmwareVersion" : "2023.1.4-1:30ccca5e458c342a95d28cd2667f431e:07029280615154e81c8205c83c8324e7",
"timeReliable" : true,
"upToDate" : true,
"updateStatus" : "UPDATING",
"updateCriticityLevel" : "BLOCKING",
"automaticUpdate" : false,
"connectivity" : {
"status" : "PARTIAL",
"problems" : [ "NO_NTP" ],
"protocolVersion" : "a protocol version"
},
"syncInProgress" : 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
gatewayId
|
"string value" |
The id of the gateway
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
DeviceStateChangedEvent
| 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"
} |
| Field name |
Field description |
| deviceStates |
Updated device states |
| deviceURL |
Device URL |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
RefreshAllDevicesStatesFailedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
RefreshAllDevicesStatesCompletedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
gatewayId
|
"string value" |
The id of the gateway
|
|
Path Variable
|
protocolType
|
1 |
The protocol type
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
RefreshAllDevicesStatesFailedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
DeviceStateChangedEvent
| 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"
} |
| Field name |
Field description |
| deviceStates |
Updated device states |
| deviceURL |
Device URL |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
RefreshAllDevicesStatesCompletedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155190,
"expirationDate" : 1769503155190
} |
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
[ {
"actionMask" : 1,
"text" : "a text",
"subject" : "a subject",
"oid" : "a notification OID",
"date" : 1769503155190,
"expirationDate" : 1769503155190
} ] |
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
[ {
"actionMask" : 1,
"text" : "a text",
"subject" : "a subject",
"oid" : "a notification OID",
"date" : 1769503155190,
"expirationDate" : 1769503155190
} ] |
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
{
"creationTime" : 1769503155309,
"lastUpdateTime" : 1769503155309,
"label" : "a place label",
"type" : 1,
"metadata" : "some metadata",
"oid" : "the place UUID",
"subPlaces" : [ {
"creationTime" : 1769503155309,
"lastUpdateTime" : 1769503155309,
"label" : "a place label",
"type" : 1,
"metadata" : "some metadata",
"oid" : "the place UUID",
"subPlaces" : [ {
"creationTime" : 1769503155309,
"lastUpdateTime" : 1769503155309,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
placeOID
|
"string value" |
The place OID
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
{
"creationTime" : 1769503155309,
"lastUpdateTime" : 1769503155309,
"label" : "a place label",
"type" : 1,
"metadata" : "some metadata",
"oid" : "the place UUID",
"subPlaces" : [ {
"creationTime" : 1769503155309,
"lastUpdateTime" : 1769503155309,
"label" : "a place label",
"type" : 1,
"metadata" : "some metadata",
"oid" : "the place UUID",
"subPlaces" : [ {
"creationTime" : 1769503155309,
"lastUpdateTime" : 1769503155309,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
placeOID
|
"string value" |
The id of the place to delete
|
HTTP Status Code
| Code |
Message |
Meaning |
|
204
|
NO_CONTENT |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
|
Generated events on method call
PlaceDeletedEvent
| Description |
An existing place has been deleted |
| JSON |
{
"timestamp" : 2,
"owningPartners" : [ "some owning partners" ],
"setupOID" : "a setup OID",
"placeOID" : "a place OID",
"name" : "PlaceDeletedEvent"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
protocolType
|
1 |
The protocol type of devices to refresh
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
RefreshAllDevicesStatesCompletedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
RefreshAllDevicesStatesFailedEvent
| 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"
} |
| Field name |
Field description |
| gatewayId |
Gateway id |
| owningPartner |
Owning partner of the parent entity (gateway, setup group, ...)) . only available in event streams |
DeviceStateChangedEvent
| 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"
} |
| Field name |
Field description |
| deviceStates |
Updated device states |
| deviceURL |
Device URL |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
|
|
| PUT |
Android [DEPRECATED]
since version 2018.3.3
|
/setup/subscribe/notification/android/{providerApplicationId}
|
application/json |
|
Deprecated, use the new android firebase infrastructure. Update an Android device subscription
Access scope : Full enduser API access (enduser/*)
> Test operation
|
|
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 gcm subscriber json wrapper UUID",
"jsonPayload" : 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 |
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155215,
"lastUpdateTime" : 1769503155215,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155198,
"lastUpdateTime" : 1769503155198,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155213,
"lastUpdateTime" : 1769503155213,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155209,
"lastUpdateTime" : 1769503155209,
"udid" : "a udid",
"model" : "a model",
"version" : "a version",
"name" : "a push device name",
"metadata" : "some metadata"
}
} ],
"androidDevices" : [ {
"subscriberOID" : "a subscriber OID",
"device" : {
"creationTime" : 1769503155209,
"lastUpdateTime" : 1769503155209,
"udid" : "a udid",
"model" : "a model",
"version" : "a version",
"name" : "a push device name",
"metadata" : "some metadata"
}
} ],
"androidFcmDevices" : [ {
"subscriberOID" : "a subscriber OID",
"device" : {
"creationTime" : 1769503155210,
"lastUpdateTime" : 1769503155210,
"udid" : "a udid",
"model" : "a model",
"version" : "a version",
"name" : "a push device name",
"metadata" : "some metadata"
}
} ],
"windowsDevices" : [ {
"subscriberOID" : "a subscriber OID",
"device" : {
"creationTime" : 1769503155209,
"lastUpdateTime" : 1769503155209,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
userIdToUnsubscribe
|
"string value" |
The user ID to unsubscribe
|
HTTP Status Code
| Code |
Message |
Meaning |
|
204
|
NO_CONTENT |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
|
Generated events on method call
PushSubscriptionDeletedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
subscriberOID
|
"string value" |
The subscriber OID
|
HTTP Status Code
| Code |
Message |
Meaning |
|
204
|
NO_CONTENT |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
|
Generated events on method call
PushSubscriptionDeletedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155201,
"lastUpdateTime" : 1769503155201,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
ExternalServiceURLEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
{
"thirdPartyModelSetupUsers" : [ {
"creationTime" : 1769503155472,
"lastUpdateTime" : 1769503155472,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
{
"label" : "a zone label",
"type" : 0,
"items" : [ {
"itemType" : "device",
"deviceOID" : "a device OID",
"deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
} ],
"externalOID" : "an external OID",
"metadata" : "some metadata"
} |
Json description of item list
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
Generated events on method call
ZoneUpdatedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
{
"label" : "a zone label",
"type" : 0,
"items" : [ {
"itemType" : "device",
"deviceOID" : "a device OID",
"deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
} ],
"externalOID" : "an external OID",
"metadata" : "some metadata",
"oid" : "the zone UUID"
} |
Json description of item list to remove
|
HTTP Status Code
| Code |
Message |
Meaning |
|
204
|
NO_CONTENT |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
|
Generated events on method call
ZoneUpdatedEvent
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
{
"label" : "a zone label",
"type" : 0,
"items" : [ {
"itemType" : "device",
"deviceOID" : "a device OID",
"deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
} ],
"externalOID" : "an external OID",
"metadata" : "some metadata",
"oid" : "the zone UUID"
} |
Json description of item list to 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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
{
"label" : "a zone label",
"type" : 0,
"items" : [ {
"itemType" : "device",
"deviceOID" : "a device OID",
"deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
} ],
"externalOID" : "an external OID",
"metadata" : "some metadata"
} |
Json description of desired zone
|
HTTP Status Code
| Code |
Message |
Meaning |
|
201
|
CREATED |
The request has been fulfilled and resulted in a new resource being created
|
Generated events on method call
ZoneCreatedEvent
| 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"
} |
| Field name |
Field description |
| owningPartners |
Owning partners of the parent entity (setup, ...)) . only available in event streams |
| setupOID |
Setup OID |
| zoneOID |
Zone OID |
|
|
| PUT |
Zone [DEPRECATED]
since version 2018.3.3
|
/setup/zones
|
application/json |
|
Update zone
Access scope : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Request Body
|
(JSON)
|
{
"label" : "a zone label",
"type" : 0,
"items" : [ {
"itemType" : "device",
"deviceOID" : "a device OID",
"deviceURL" : "device URL (<protocol>://<gatewayId>/<deviceAddress>[#<subsystemId>])"
} ],
"externalOID" : "an external OID",
"metadata" : "some metadata",
"oid" : "the zone UUID"
} |
Json description of desired zone to update
|
HTTP Status Code
| Code |
Message |
Meaning |
|
200
|
OK |
The request has succeeded
|
|
|
| GET |
Zone
|
/setup/zones/{zoneOID}
|
application/json |
|
Get a zone of a user setup
Access scope : Full enduser API access (enduser/*)
> Test operation
|
|
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" : 1769503155311,
"lastUpdateTime" : 1769503155314,
"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 : Full enduser API access (enduser/*)
> Test operation
|
|
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 : Full enduser API access (enduser/*)
> Test operation
|
|
Parameters
| Type |
Name |
Value |
Description |
|
Path Variable
|
zoneOID
|
"string value" |
Zone OID to delete
|
HTTP Status Code
| Code |
Message |
Meaning |
|
204
|
NO_CONTENT |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation
|
Generated events on method call
ZoneDeletedEvent
| Description |
An existing zone has been deleted |
| JSON |
{
"timestamp" : 2,
"owningPartners" : [ "some owning partners" ],
"setupOID" : "a setup OID",
"zoneOID" : "a zone OID",
"name" : "ZoneDeletedEvent"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
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
| 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"
} |
| Field name |
Field description |
| 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 : Full enduser API access (enduser/*)
> Test operation
|
|
Response
| Type |
Name |
Value |
Description |
|
Response Body
|
(JSON)
|
[ {
"creationTime" : 1769503155315,
"lastUpdateTime" : 1769503155315,
"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
|
|
|
|