Bond Local API http://docs-local.appbond.

com/#tag/Bridge/paths/~1v2~1bridge/get

Download OpenAPI speci�cation: Download

The Bond V2 API allows control of Ceiling Fans, Fireplaces, and other Bond devices. It is intended for integration with o�ine control systems,
for use by advanced users, hobbiests, integrators, and installers.

For the purposes of device control, it does not matter whether these devices are remote-controlled devices that Work with Bond (connected
via a Bond Bridge) or smart devices that are Smart by Bond.

This documentation describes the Local HTTP API for Bond products running v2 �rmware. This API does not require an internet connection,
but does require that the API client be able to directly communicate with the Bond over HTTP. Typically this means being on the same Wi-Fi
network. We are still working on a Cloud API, which will be very similar to the Local API.

1 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

We welcome your corrections and improvements to this documentation! You can �nd the source code for the documentation at the link below.
Feel free to open a PR.

https://github.com/bondhome/api-v2

The Bond Local API uses unencrypted HTTP using a simple token-based authentication mechanism.

Why HTTP and not HTTPS?

After speaking with many users interested in Local API, we discovered that users were satis�ed with the protection provided by their Wi-Fi
network's password, and that it is more important to provide easy and low-latency control of Bond devices than to provide security against
other devices and users on the Wi-Fi network.

Furthermore, it can be challenging for an API client to use HTTPS securely. In order to protect against malicious devices or users inside your
Wi-Fi network, it would be necessary for an HTTPS API client to check the validity of the Bond's HTTPS certi�cate against an Olibra Certi�cate
Authority. The web standard of using domain-based certi�cate chain-of-trust does not work when o�ine, because the Bond does not have a
domain name, being a device on your local network rather than on the public internet. As a consequence, an HTTPS API would not work from
many webbrowsers due to the certi�cate being untrusted.

That said, if you have untrusted users or devices on your Wi-Fi network, we recommend placing Bond on a seperate home automation network
to which the untrusted users do not have the password.

Security on the Internet

Rest assured that when Bond products communicate with Bond Cloud (which is needed for integration and voice control support), we use

2 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

industry-standard secure TLS connections, secured with per-unit public key cryptography. There is no unencrypted communication between
Bond hardware and Bond Cloud.

Please be sure to always use Bond behind a �rewall, and do not set up port-forwarding to the Bond Local API, to ensure that unsecured
communications do not take place over the public internet.

To get the optimal match between this documentation and your Bond's exposed API, we recommend you update your Bond to the most recent
�rmware available. In situations where part of this API is only available on Beta �rmware, we will try to make this clear. To use such a feature,
you'll need to upgrade your �rmware with a Beta app. You can sign up to receive Beta apps through one of the links in this post, and we will
typically post about Beta features in the Beta category of the forums

First, power on a Bond device and connect it to your Wi-Fi network. Use the Bond app to con�rm that the Bond's �rmware is at least version v2.

The newest versions of the Bond Home app (starting in v2.15) have the Bond's IP address in the Bond's "Network Info" screen. Tapping it will
copy it to your clipboard. If ping is more convenient for you, please refer to the instructions below.

3 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

From your PC connected to the same network, try pinging the Bond. For example, if your Bond ID is ZZBL12345, you can ping it by running the
following command in a terminal:

ping BB18038.local

You should see the IP address printed, along with reply messages. Press Ctrl-C to exit the ping program:

PING bb18038.local (192.100.0.61): 56 data bytes

64 bytes from 192.100.0.61: icmp_seq=0 ttl=64 time=96.800 ms
64 bytes from 192.100.0.61: icmp_seq=1 ttl=64 time=34.902 ms
64 bytes from 192.100.0.61: icmp_seq=2 ttl=64 time=4.226 ms
^C
--- bb18038.local ping statistics ---
3 packets transmitted, 3 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 4.226/45.309/96.800/38.503 ms

You can see the IP address of this Bond is 192.100.0.61 .

Note that the lookup from Bond ID to IP address is performed using mDNS. You will need to make sure that mDNS is installed and enabled on
your system (this is the default for most Linux distros and on MacOS).

You can search for all Bonds on your local network. On Linux, do:

avahi-browse -a | grep bond

And on MacOS, do:

dns-sd -B _bond._tcp .

In both cases, you will see a list of Bonds on your Wi-Fi network and their IP addresses.

[Added in v2.18.2] If you want to check for �rmware version and discoverability of the Bond without connecting to it, you may look into the text

4 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

properties of the _bond._tcp mDNS service:

dns-sd -Z _bond._tcp .

You should see a line like this in the reply:

ZPEA77090._bond._tcp TXT "v=v2.18.0-2-gf4ddfba8-dirty-merck-discoverability" "d=0"

Next, let's check the Bond's �rmware version. To do this, we will use a command-line utility called cURL. cURL is installed by default on MacOS
and most Linux distributions.

To check the �rmware version, run this command:

curl -i http://192.100.0.61/v2/sys/version

The �ag -i means "display header information". You should see output similar to this:

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

{"target":"snowbird","fw_ver":"v2.5.2","fw_date":"Fri Feb 22 14:13:25 -03 2019","make":"Olibra LLC","model":"model"

Where, we see the �rmware version is v2.5.2 .

5 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Note that no token is required for the version endpoint, but other endpoints will require token-based authentication.

The Bond Home app has the Bond's token in the Bond's "Settings" screen. Tapping it will copy it to your clipboard. If curl is more convenient
for you, please refer to the instructions below.

To get the token, follow this procedure:

Power cycle the Bond, and then within 10 minutes, access the token endpoint as follows:

curl -i http://192.100.0.61/v2/token

You should see a return body containing token such as this:

{locked":0,"pin_attempts_left":10,"token":"f074b61f628018fd","nonce":"0000000000000000","v1_nonce":"0000000000000000

Copy the token and use it with a BOND-Token header in subsequent requests.

Alternatively, the token may be provided by setting the _token �eld within the request body. [Since v2.6.23]

To get a list of devices on the Bond, do:

6 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

curl -H "BOND-Token: f074b61f628018fd" -i http://192.100.0.61/v2/devices

Or, to use the embedded token technique:

curl -i http://192.100.0.61/v2/devices -X GET -d "{\"_token\": \"f074b61f628018fd\"}"

You will get a list of devices such as this:

{"_":"f7e407f1","79135791":{"_":"599b0fc5"}}

Here we see there is one device with id 79135791 .

We can request the device details by doing:

curl -H "BOND-Token: f074b61f628018fd" -i http://192.100.0.61/v2/devices/79135791

And we can see the device name, location, and available Actions:

{"name":"Magic Fan","type":"CF","actions":["TurnOn","TurnOff","SetSpeed","IncreaseSpeed","DecreaseSpeed"],"location"

Finally, let's try setting the fan's speed:

7 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

curl -H "BOND-Token: f074b61f628018fd" -i http://192.100.0.61/v2/devices/79135791/actions/SetSpeed -X PUT -d "{\"argument\

As of v3.0.0 �rmware, Bond products have moved to 64-bit keys as resource identi�ers, instead of the previous 32-bit keys. So, rather than a
device being identi�ed by an 8-digit hex string, the ids for newly created devices will be 16-digit hex strings.

In an effort to minimize distruption to API clients, already created resources (devices, commands, skeds, etc.) will continue to be represented
using the same exact string on the API. Additional leading zeros will not be added. So, for example, a device with id 01abcdef will continue
to enumerate as 01abcdef in v2.22. The Bond API is however libral in what it accepts, removing leading zeros. So any of the following
received ids will be understood to point to this device: 1abcdef , 01abcdef , 0000000001abcdef .

Internally, the Bond API uses this rule:

If the upper 32-bits of an ID are zero, then send as 8 hex digits (32-bit). Otherwise, send as 16 hex digits (64-bit).

8 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The Bond API is organized as a tree of endpoints, starting at the root. Here's an incomplete example:

- v2
- devices
- 00000001
- commands
- state
- 00000002
- commands
- state
- 00000003
- commands
- state
- sys
- network

Clearly, if the entire tree were expanded on a request of the root, then the resulting request may be very large! This large response body would
cause several problems, including taking a long time to transmit over slow networks, taking time to generate, and being too large to be
effectively transmitted over the message-based protocol MQTT.

Therefore, Bond only returns a single level of the tree on every request.

Each node of the tree has a 32-bit "hash" value which is changed whenever that node, or any of the child nodes, are modi�ed. This hash is
provided in every reply body as the "_" object.

When a requested endpoint has children that are not expanded, the child values are replaced with just the child hashes.

For example, when requesting the devices endpoint, you may receive the following response:

9 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{"_":"f7e407f1","79135791":{"_":"599b0fc5"}}

Let's break this down:

• "_":"f7e407f1" : This is the hash value of the devices object. If any devices are added, modi�ed, or deleted, this hash will change.

• "79135791" : This is the device id of the one device on this Bond.

• {"_":"599b0fc5"} : This is the hash object representing device with id 79135791 .

If the API client wants to get the name of the device, it is necessary to make a seperate request on the device itself: GET devices/
79135791 , which would return the name and location directly associated with the device, as well as hash objects for the child nodes of
device: commands and state .

The _ hashes discussed above are designed to allow a client to quickly discover changes to a Bond's state. As we've shown, this requires
the hash at a particular endpoint to incorporate not only that endpoint's state but also the state of all the children. However, it is sometimes
desireable to have a hash of just the data local to that endpoint, that is, data not contained within a child.

[As of v3 �rmware] we introduce a new __ (double underscore) �eld called a "local hash". This is intended to be used by the Bond Cloud and
Bond Apps speci�cally for downwards synchronization as required for the Groups and Scenes features.

Most integrators can safely ignore the local hashes.

10 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The purpose of the Request ID is to allow a client to retry a non-idempotent request (PUT, POST, PATCH, or DELETE) without risk of Bond
taking the same action twice.

If you need to implement a retry mechanism in your integration, please contact the Bond Engineering Team via the Bond Forums https://
forum.bondhome.io/

Each request may contain a number of request �ags, which can be speci�ed on HTTP via the Bond-Flags header (or via the f �eld for
BPUP and MQTT transports). These �ags are not needed in most integrations, but are used by Bond Home app and some partner integrations
to facilitate debugging at scale.

Flags are:

• bit 0: (reserved)
• bit 1: DOWNSYNC: request is part of downward synchronization
• bit 2: UP: request is moving away from Bond
• bit 3: DUP: request is retransmitted or cached reply
• bit 4: UCAST: (internal use)
• bit 5: QUIET: (internal use)
• bit 6: BCAST: (internal use)
• bit 7: PASSTHRU: (internal use)

11 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Certain endpoints may track their last modi�ed time in a special __modified �eld. The modi�ed time is an integer representing the time in
seconds since the Unix epoch when the endpoint was last modi�ed.

Currently the endpoints exposing __modified are:

groups/{}
groups/{}/skeds
groups/{}/skeds/{}
scenes/{}
scenes/{}/skeds
scenes/{}/skeds/{}

The modi�ed times are set using the request time as speci�ed in the BOND-Unixtime HTTP header (or u �ag on BPUP and MQTT).
Example:

BOND-Unixtime: 1643114517

{ ..., "u":"1643114517", ... }

Clients who may modify any shard endpoints should specify this header on all reqeusts. If this "unixtime" �eld is not provided, the Bond will
use its internal real-time clock, if already set.

Conversely, if the Bond's internal clock is not yet set, it will use the timestamp speci�ed in this �eld as the internal time. For this reason, only
use the BOND-Unixtime header on systems with accurate clocks, such as smart phones. Incorrectly set times may result in shard
synchronization issues and skeds running unexpectedly.

12 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Bond Home V3 introduces Groups and Scenes as major new features. In designing these features, we needed to meet several requirements
requested by the Bond community:

1. Groups and Scenes must work o�ine. A loss of internet connection must not interfere with control and feedback, and should not prevent
creation and management, when the Bond Home app is on the same local network as the devices in question.
2. Smart by Bond devices can be grouped or added to a Scene with no Bond Bridge required as a hub.
3. Groups and Scenes must be resiliant to any individual Bond units going o�ine. That is, there must not be a central controller as a single
point of failure. If only a subset of the Group or Scene devices are online, then they should still execute action requests.
4. Intuitive UI in the Bond Home app for creating, managing, and controling Groups and Scenes. The user should be blissfully unaware of
any lower-level complexities.

In order to achieve the above, we chose a design where a Group or Scene object is distributed among the participating Bond units. The Group
or Scene endpoint data that lives on a single Bond is called a shard. Each Bond unit acts as if it were the only participant in the Group or
Scene, using only the data in its own shard, with no communication among Bond units.

The API client is responsible for managing the various shards. The most di�cult aspects of this---involving correction of inconsistent data
between Bonds---is handled by the Bond Home apps. However, some complexity does remain for integrators who need to send multiple
requests to control a Group and must merge the data returned by those requests to present a sensible interface to the control system and
ultimately the user.

We will here discuss:

• discovery, control, and feedback (for all API clients)

• management (for Bond Home app)

The following discussion is in terms of Groups but should be understood as also applying to Scenes unless otherwise speci�ed.

13 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

To discover the Groups available on a Bond network, the client should �rst query the groups/ enumeration to get the group IDs in which
each Bond participates. The union of the Group IDs gives the list of Groups on the network.

For example:

ZZBL12345:groups = {
"0000000000000001":{...},
"0000000000000002":{...},
"0000000000000003":{...}
}

KSMJWCE12345:groups = {
"0000000000000002":{...},
"0000000000000004":{...}
}

There are a total of 4 groups on the network:

"0000000000000001"
"0000000000000002"
"0000000000000003"
"0000000000000004"

In this example, the Bond Bridge (ZZ...) participates in three groups with IDs 1, 2, and 3, while a Smart by Bond fan (K...) participates in groups
2 and 4.

Next, the client should query each of the group shard endpoints group/{} . The list of devices participating in the group is the union of the
devices in the group shards.

14 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

For example, if the result of querying the groups/{} endpoint for the group with ID 2 is:

ZZBL12345:groups/0000000000000002 = {
"__modified": 1642788966,
"name": "Great Room Fans",
"types": ["CF"],
"locations": ["Great Room"],
"devices": ["aabbccdd", "11223344"],
"actions": ["TurnOn", "TurnOff"]
}

KSMJWCE12345:groups/0000000000000002 = {
"__modified": 1642788968,
"name": "Great Room Fans",
"types": ["CF"],
"locations": ["Great Room"],
"devices": ["1"]
"actions": ["TurnOn", "TurnOff", "TurnLightOn", "TurnLightOff"]
}

Then the API client concludes that the group named "Great Room Fans" contains three devices:

ZZBL12345:aabbccdd
ZZBL12345:11223344
KSMJWCE12345:1

In the case of a disagreement of the name between shards, the client should use the name from the group shard with the most recent
modi�ed time ( __modified ). If there is a tie for modi�ed time, the client may choose arbitrarily among the shards.

The type of the group is indicated by the types array, which is typically only of length one. In this case we see it is CF for Ceiling Fan.

15 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Determining Available Actions

The actions available on a group is the intersection of the actions available on the group shards. So, using the example from the previous
section, although the group shard on the Smart by Bond fan (serial number K...) supports TurnLightOn and TurnLightOff actions, the
shard on the Bond Bridge does not. So the intersection of the actions arrays is just:

["TurnOn", "TurnOff"]

Executing a Group Action

To execute an action on the group, the client should send PUT requests to the actions on each group shard. So, to turn on the Great Room
Fans group, the client would send two requests using the same Group ID:

PUT http://ZZBL12345/v2/groups/0000000000000001/actions/TurnOn
PUT http://KSMJWCE12345/v2/groups/0000000000000001/actions/TurnOn

Preferably these requests should be run concurrently so that the time required to process the �rst request does not delay the execution of the
action on the second shard.

Success, Error, and Timeout

If all requests complete successfully, then the group action can be considered a success. If any errors or timeouts occur, then an error should
be reported to the user.

Whenever a group changes state, a state update is sent for the group shards and all member devices. Whenever a device state changes, a
state update is sent for that devices plus an update for the state of any groups which contain that device.

16 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Group shards report state under groups/{}/state . The schema of this endpoint is similar to that of devices/{}/state , except that
state variables on a group can take the value null when the member devices disagree, as discussed below in the documentation for this
endpoint. Although the Bond Bridge will combine the states of the member devices into a single state for the group shard, it is the
responsibility of the API client to merge the states of each group shard to obtain an overall state for the group.

For example, suppose the client receives the following state updates:

ZZBL12345:groups/0000000000000001/state = {
"power": 1,
}

KSMJWCE12345:groups/0000000000000001/state = {
"power": 1,
"light": 0
}

The client would intersect the state keys to remove any state variables not shared by all shards, and then set the values to either null if
there is disagreement between shards, or to the common value. In this case the client would conclude the group state to be:

{"power": 1}

If now one of the member devices, say the Smart by Bond fan, is turned off, then the client would receive a state update for the device and
group:

KSMJWCE12345:devices/1/state = {
"power": 0,
"light": 0
}

KSMJWCE12345:groups/0000000000000001/state = {
"power": 0,
"light": 0
}

The client would now combine the two group shard states to conclude:

17 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{"power": null}

That is, that the power state of the group is indeterminate. On a UI with seperate ON/OFF buttons, this would usually be represented by
highlighting neither button.

Group Creation

To create a new group, the client should send requests to each of the participating Bonds with the list of devices to include. Crucially, all
shards must have the same group ID so that they will be understood as a single group by other clients. The preferred way to accomplish this is
to allow the Bond to generate a random ID for the �rst shard, and then to specify that ID in the _post_id �eld during the subsequent POST
requests to the other Bonds.

For example, suppose we want to add 3 Smart by Bond lights to a group called "Kitchen Lights". The requests and responses might go like
this:

> POST http://TWCTBXX00001/v2/groups {"name": "Kitchen Lights", "devices": [1]}

< 201 OK {"_post_id": "0000000000000001"}

> POST http://TWCTBXX00002/v2/groups {"_post_id": "0000000000000001", "name": "Kitchen Lights", "devices": [1]}
< 201 OK {"_post_id": "0000000000000001"}

> POST http://TWCTBXX00003/v2/groups {"_post_id": "0000000000000001", "name": "Kitchen Lights", "devices": [1]}
< 201 OK {"_post_id": "0000000000000001"}

The last two requests could be parallelized.

Alternatively the client could pre-generate the ID and parallelize all three requests. However, the client MUST be sure to use a good random
number generator and generate a 64-bit (16-nibble) hex string in lower-case with leading zeros.

18 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Group Deletion

To delete a group, the client should send a DELETE request to each of the shards. If one of the Bonds is o�ine, then the group will only be
partially deleted. The user must bring that Bond back online in order to �nish deleting the group. In the meantime, the group will still exist
containing just the devices on the o�ine Bond.

Removing Device from Group

Devices may be removed from the Group via DELETE groups/{}/devices/{} . When the last device is removed from a group, the shard
containing that device will disappear (an implicit deletion).

Changing Group Name

To change the name of a group, the client should send a PATCH request to each of the shards. The name can be changed as long as there is
at least one online Bond participating in the group. If any Bonds are o�ine, their group/{} endpoints will still have the old name. However,
this does not pose a problem for API clients because the name should be taken from the group shard with the most recent __modified
�eld.

The Bond Home app performs a special downward synchronization whereby out-of-date group shard names are updated with the latest. That
is, when Bonds previously o�ine come back online, they are PATCHed with the name of the most recent shard in the group. Other API clients
do not need to perform this downward sync function.

Schedules on groups and scenes need to be installed into each shard, and the Bond Home app performs downward synchronization on the
skeds.

Sked Creation

Similar to group creation, Bond Home app creates the sked on each shard using the same 64-bit ID for that sked on each shard. The sked ID
must be different than the group ID. Example:

19 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

> POST http://TWCTBXX00001/v2/groups/0000000000000001/skeds {"action":"SetBrightness", "argument":75, "mark":"sunrise"

< 201 OK {"_post_id": "0000000000000007"}

> POST http://TWCTBXX00002/v2/groups/0000000000000001/skeds {"_post_id": "0000000000000007", "action":"SetBrightness"

< 201 OK {"_post_id": "0000000000000007"}

> POST http://TWCTBXX00003/v2/groups/0000000000000001/skeds {"_post_id": "0000000000000007", "action":"SetBrightness"

< 201 OK {"_post_id": "0000000000000007"}

The last two requests could be parallelized.

Sked Modi�cation

Similar to changing the name of a group, the client can modify the sked settings by broadcasting a PATCH to the sked on each group shards.

Here, in the event that a Bond is o�ine, the sked will continue being executed with the outdated parameters until the Bond Home app
performs downward synchronization to update that sked.

Sked Deletion

Deleting a group or scene sked is as simple as sending DELETE to the sked on each shard.

In the event of one or more Bonds being o�ine, they will continue to execute the sked until the Bond Home app syncs with them and removes
the sked which was supposed to be deleted. The Bond Home app knows that a sked was deleted by checking the __modified timestamp
on the group shard skeds enumeration groups/{}/skeds . If a sked is present on an older enumeration but absent on a newer one, it will be
removed from the old enumeration. Similarly, if a sked is present on the newer enumeration but absent on the old one, then the Bond Home
app will downwards-synchronize by POSTing the missing sked.

CAVEAT: BPUP is currently in Beta status. Breaking changes may occur to this API as we collect community feedback.

20 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

A common problem in writing drivers to support Bond devices is a need to update the client whenever device state changes. With the HTTP
API, this implies ine�cient polling. So we've added support for "Bond Push", a UDP-based API for low-latency control and feedback within the
local network.

A client initiates a connection by opening a UDP socket to the Bond on port 30007 and sending a Keep-Alive datagram, which is just a single
newline character. This subscribes the client to state updates from devices. Equivalent to the regex devices/.*/state .

The Bond will acknowledge the subscription by immediately replying with the Bond ID:

{"B":"ZZBL12345"}\n

The client should continue to send the Keep-Alive datagram on the same socket every 60 seconds to keep the connection active. If no Keep-
Alive datagram is received after 125 seconds, Bond will stop sending feedback to the client.

A future update will allow subscribing to a different topic pattern.

The Bond will send to all active clients Update datagrams consisting of a JSON object terminated by a newline character. Here's an example
Update datagram:

{"B":"ZZBL12345","d":0,"v":"v2.18.2","t":"devices/aabbccdd/state","i":"00112233bbeeeeff","s":200,"m":0,"f":255,

Breaking down the �elds:

• B : the Bond ID
• d : discoverability (0=not discoverable, 1=setup mode, 2=sos mode) [new in v2.18.2]
• v : �rmware version [new in v2.18.2]
• t : topic (the path from HTTP URL)
• i : request ID
• s : HTTP status code
• m : HTTP method (0=GET, 1=POST, 2=PUT, 3=DELETE, 4=PATCH)
• f : �ags (Olibra-internal use)
• x : source transport (transport from which the request was received. Can be: "http", "mqtt", "bond" (gratuitous reply), "cli" (serial terminal),

21 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

with other values reserved for future use) [Since v2.12.1]

• b : HTTP response body

There's also some client-speci�c error messages,

{"B":"ZZBL12345","err_id":631,"err_msg":"BPUP client timeout"}\n

For feature requests and concerns, please contact the Bond Engineering Team via the Bond Forums https://forum.bondhome.io/

IMPORTANT NOTE: MQTT redirection is implemented, but is currently untested. It may not work at all. If you have a use case for this API,
please let us know on the forums so that we can better prioritize implementing and testing this API.

You can con�gure your Bond to communicate with a custom MQTT broker through the api/mqtt endpoint.

When the Bond connects to its con�gured MQTT broker, it subscribes to the topic v2/<Bond ID>/down/# , where # is a wildcard. It
publishes messages to v2/<Bond ID>/up/<subtopic> , where the subtopic is that indicated in this documentation less the v2/ pre�x.

A concrete example: requesting devices from the Bond.

The equivalent to HTTP GET v2/devices from a Bond with ID ZZBL12345 is publishing a message to v2/ZZBL12345/down/devices with
the payload {"m": 0} (since the default for "m" (HTTP method) is 0 ( GET ), this payload could also just be {} )

The Bond, if it had a single device with id 12345678 , would then publish to v2/ZZBL12345/up/devices with the payload

{"B": "ZZBL12345", "d": 2, "v": "v2.18.2", "t": "devices", "m": 0, "i": <randomly-generated request ID>, "s":
200, "f": 255, "b" {"_": <devices hash>, "12345678": {"_": <12345678's hash>}}}

Breaking down the �elds:

22 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

• B : the Bond ID
• d : discoverability (0=not discoverable, 1=setup mode, 2=sos mode) [new in v2.18.2]
• v : �rmware version [new in v2.18.2]
• t : subtopic (the path from HTTP URL, without the v2/ pre�x)
• i : request ID
• s : HTTP status code
• m : HTTP method (0=GET, 1=POST, 2=PUT, 3=DELETE, 4=PATCH)
• f : �ags (Olibra-internal use)
• b : HTTP response body

(Note: the �rst two �elds are redundant, they could be extracted from the MQTT topic)

The MQTT broker to which the Bond is connected is treated as trusted, so token authentication is not necessary. Make sure you check the
server certi�cate using the appropriate �elds in the api/mqtt endpoint to avoid man-in-the-middle attacks.

[Added in v3.5.1] The HomeKit integration is available on Bond Bridge Pro and support Shade devices. The integration is disabled by default,
but you can enable/disable it through the Bond Home iOS app or the api/bhk endpoint.

The Setup Code is generated based on your Bond PIN (your Bond PIN two times). The Bond PIN is located on the product label. The Setup
Code is also available on the Bond Home iOS app.

23 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Setup Code example

For Bond PIN "1234", your HomeKit Setup Code is "12341234".

As of iOS app version v2.40.2, the HomeKit info is available in both the Bond Settings screen and the Manage Integrations screen.

In the Bond Settings screen, the HomeKit info is presented under the Advanced Settings section.

In the Manage Integrations screen you should see the HomeKit listed if at least one of your Bonds supports it. The HomeKit cell shows how
many Bonds have the HomeKit integration enabled (not available) at the moment. Tapping on the cell will take you to the HomeKit List screen,
showing the HomeKit info for every Bond that supports it.

The HomeKit info consists of a toggle switch to enable/disable the feature and shows its Setup Code.

Open the Home app on your iPhone/iPad and follow these steps:

• Tap on "Add Accessory"

• Choose the "I Don't Have a Code or Cannot Scan" option
• Tap on your Bond Bridge name in the list of Nearby Accessories
• Select the "Add Anyway" option for the "Uncerti�ed Accessory" prompt
• Enter yours Bond Bridge Setup code and hit Continue
• Set the Location and Name for your Bridge
• Set the location and Name for your Bridge's devices, if any

24 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Bonds may be discovered via either mDNS or BPUP. A Bond on the network will reply to queries regardless of its discoverability. However,
clients (especially the Bond Home app) need to know if the device should be shown in the list of devices available for setup, or whether it is
functioning normally and should be ignored. (This is a usability rather than a security consideration.)

To this end, we have added [in v2.18.2] a discoverability �ag in the mDNS, BPUP, and even MQTT replies, with the following possible values:

• 0 = not discoverable: Bond is on an account and functioning normally. Should not appear in any list of Bonds ready to set up.

• 1 = setup mode: Bond is not on an account. This is either a new unit, or a unit that has had a GREEN or WHITE reset performed. The unit's
light ring will be either Solid Green (ready on Ethernet) or Flashing Green (ready on Wi-Fi).

• 2 = SOS mode: the Bond is on an account, however there is either a cloud connection problem, or for Smart by Bond devices where the
user has held down the Power button to re-enable discoverability. In this case, the light ring (if present) will indicate an error, and the
Con�g AP will be opened. SOS mode is automatically exited if the cloud connection is restored.

25 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The Bond Bridge, also referred to simply as "Bond", connects RF- and IR-controlled devices to Wi-Fi. Learn more at https://bondhome.io/
product/.

A "Smart by Bond" appliance is a smart appliance that uses the API described here, other than those parts designated as "Bridge Only".

Within the Bond ecosystem, the term "device" always refers to a home appliance connected to Bond. A Bond Bridge is not itself a device.

Bond devices support one or more "features", such as Speed or Brightness, which come with a set of Actions, State Variables, and Properties

26 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

that de�ne and control some aspect of the device.

For example, a device which supports the Light feature will always have actions for TurnLightOn, TurnLightOff, and ToggleLight. Furthermore,
it will always have the light state variable.

See the Features section below for detail on all supported features.

Devices are controlled by calling "actions" such as SetSpeed or TurnOff.

Some actions require an "argument" to be included. For example, SetSpeed requires an integer argument with the speed number to set.

Actions represent a user's intent, but do not nessisarly map one-to-one onto the commands that are sent to a device. Actions abstract away
the complexity of the underlying commands needed to achieve the desired change in state of a device.

Bond Bridges operate by translating actions into "commands". While actions are in a user's language, commands are in the device's remote
control's language. Often there is a one-to-one mapping from actions to commands, for example, most ceiling fans have distinct RF
commands for each speed. So the action "SetSpeed(3)" is always translated into the same RF signal that tells the device to go to the third
speed.

However, sometimes a device does not have a single command which always accomplishes a speci�c action. For example, most ceiling fans
do not have a speci�c command corresponding to the TurnOn action, but rather, Bond remembers the previous speed that the fan was set to,
and uses a particular SetSpeed command to accompish the TurnOn action. On the other hand, certain ceiling fans do have a speci�c TurnOn
command. In that case the TurnOn action will always map to the TurnOn command. This results in the correct speed being restored even if the

27 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

factory remote control was used.

The term "signal" refers to the actual RF or IR transmission sent to the remote-controlled device to accomplish a particular command.

Every command should have exactly one corresponding signal. However, the Bond Bridge supports a number of signal endpoints which
allow manipulation of signals directly, such as signal/scan to receive signals, or signal/tx to transmit a signal without association to a
device.

The Bond Bridge makes an effort to track the state of devices, and this state is represented by a set of "state variables", such as speed and
brightness.

Speed variables cannot be set directly, but rather are manipulated indirectly through actions. For example, the SetSpeed action with an
argument of 3 has the side-effect of setting the speed state variable to 3 and the power variable to 1.

Some device Features have a "Property" which parameterizes the devices capabilities. For example, multi-speed ceiling fans supporting the
Speed feature will always have a max_speed property which gives the maximum speed which the speed state variable may take.

28 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Some properties are read-only, others are PATCH-able.

Feature Toggles

Properties starting with feature_ are called feature toggles, and always default to true. When a feature toggle is set to false, the
corresponding feature is disabled along with all dependent features, leaving only the top-level feature toggle.

For example, on a device with Light, UpDownLight, Brightness, and UpDownLightBrightness features, setting feature_light to false will
cause all properties, state variables, and actions for all four of these features to be removed from the API, including the feature toggles
feature_brightness and feature_up_down_light . Only feature_light will remain.

The intended use of feature toggles is in the Bond Home application's device settings screen, wherein the currently visible feature toggles
should correspond exactly to toggle switches. Furthermore, the client need not have any feature-speci�c code for this: the order of feature
toggles in the properties JSON object may be used as the UI display order, and the display names may be programmatically derived from the
property names, e.g. feature_up_down_light displayed as "Up Down Light".

Feature toggles are only available for some features, and are currently only available for Smart by Bond devices.

Devices have a combination of actions, state variables, and �xed properties. In order to understand how these relate to each other, it is helpful
to organize actions into features and study one feature at a time.

The Power feature controls the basic on/off state of a device.

29 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

For Ceiling Fans, it refers to the state of the fan motor. Note that most ceiling fans have lights which are not governed by the Power feature.

For Fireplaces, it refers to the state of the �ame. Note that many �replaces have separate light or fan functions, which are not governed by the
Power feature.

Properties

(none)

State Variables

• power: (integer) 1 = on, 0 = off

Actions

• TurnOn(): Turn device power on.

• TurnOff(): Turn device power off.
• TogglePower(): Change device power from on to off, or off to on.

The Timer feature allows turning off a device after a speci�ed delay, similar to the dial timer interface on toaster ovens.

The Timer feature requires the Power feature.

Properties

(none)

State Variables

• timer: (integer) seconds remaining on timer, or 0 meaning no timer running

30 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Actions

• SetTimer(s): Start timer for s seconds. If power if off, device is implicitly turned on. If argument is zero, the timer is canceled without
turning off the device.

NOTE: The timer is canceled implicitly by any action on the Power, Speed, or Breeze features, other than TurnOn. For example, if a timer is
running, and the user turns off the device and then turns it back on, the timer will be canceled and therefore the device will not turn off again
unexpectedly. The intention that a timer is designed to help reduce energy consumption, but should never surprise the user who forgot that
they enabled the timer function earlier. When the timer reaches zero it runs TurnOff, so it will turn off the device whether it is set at a speci�c
speed or it is set to breeze.

The Speed feature is used by multiple-speed Ceiling Fans to track the motor speed.

The Speed feature requires the Power feature.

Note that while many Fireplaces have a built-in fan, they do not use the Speed feature. See FpFan feature.

Properties

• max_speed: (integer, read-only) highest speed available

State Variables

• speed: (integer) value from 1 to max_speed. If power=0, speed represents the last speed setting and the speed to which the device
resumes when user asks to turn on.

Actions

• SetSpeed(speed): Set speed and turn on. If speed>max_speed, max_speed is assumed. If the fan is off, implicitly turn on the power.
Setting speed to zero or a negative value is ignored.

31 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

• IncreaseSpeed(speeds): Increase speed of fan by speci�ed number of speeds. If the fan is off, implicitly turn on the power.
• DecreaseSpeed(speeds): Decrease fan speed by speci�ed number of speeds. If attempting to decrease fan speed below 1 , the fan will
remain at speed 1. That is, power will not be implicitly turned off. If the power is already off, DecreaseSpeed is ignored.

NOTE: When the device is turned off, the previous speed is remembered. When the fan is then turned back on, it will resume at the previous
speed.

The Breeze feature of many multi-speed Ceiling Fans provides a randomized breeze.

Breeze works by pseudorandomly changing the power and speed of the fan over time to create a natural breeze effect. There are two
parameters of the breeze which may be adjusted to provide the desired breeze effect.

The Breeze feature requires the Speed feature.

Properties

(none)

State Variables

• breeze: (array) array of the form [ <mode>, <mean>, <var> ] :

◦ mode: (integer) 0 = breeze mode disabled, 1 = breeze mode enabled
◦ mean: (integer) sets the average speed. 0 = minimum average speed (calm), 100 = maximum average speed (storm)
◦ var: (integer) sets the variability of the speed. 0 = minimum variation (steady), 100 = maximum variation (gusty)

Actions

• BreezeOn(): Enable breeze with remembered parameters. Defaults to [50,50].

• BreezeOff(): Stop breeze. Fan remains on at current speed.
• SetBreeze(breeze): Enable breeze with speci�ed parameters (same as breeze state variable). Example SetBreeze([1, 20, 90]) .

32 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

NOTE: If breeze is enabled when the fan is powered off, then breeze will be restored at power on.

NOTE: Calling SetBreeze with �rst parameter equal to 0 will disable breeze, but still set the speci�ed mean and var parameters.

NOTE: SetSpeed implicitly disables breeze mode.

The Direction feature is used by reversible Ceiling Fans to track the direction of the fan motor.

The Direction feature requires the Power feature.

Properties

(none)

State Variables

• direction: (integer) 1 = forward, -1 = reverse.

The forward and reverse modes are sometimes called Summer and Winter, respectively.

Actions

• SetDirection(direction): Control forward and reverse.

• ToggleDirection(): Reverse the direction of the fan.

33 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The Light feature governs the basic on/off status of a device's main light.

This is a very common feature of Ceiling Fans, and present on many Fireplaces.

See the UpDownLight feature for the behavior of devices with dual lights.

Properties

• feature_light: (boolean, PATCH-able) true = Light feature enabled (default), false = Light feature disabled

State Variables

• light: (integer) 1 = light on, 0 = light off

Actions

• TurnLightOn(): Turn light on.

• TurnLightOff(): Turn off light.
• ToggleLight(): Change light from on to off, or off to on.

The UpDownLight feature governs the on/off status of a device's upwards- and downards-facing lights, such as the ceiling-wash "up light" and
direct "down light" found on some high-end ceiling fans.

34 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The corresponding physical remote often has seperate buttons for the UpLight and DownLight, but no button for just "Light". However, Bond
always makes the Light feature available along with UpDownLight to make these devices easy to integrate. For example, saying "Alexa, Turn
on the Light" corresponds to the TurnLightOn action, which will have a reasonable result for devices with UpDownLight.

UpDownLight depends on Light feature.

Properties

• feature_up_down_light: (boolean, PATCH-able) true = Up Down Light feature enabled (default), false = Up Down Light feature disabled,
both physical light circuits will operate as one Light.

State Variables

• up_light: (integer) 1 = up light enabled, 0 = up light disabled

• down_light: (integer) 1 = down light enabled, 0 = down light disabled

If both up_light and light are 1, then the up light will be on, and similar for down light.

Note that both up_light and down_light may not be simultaneously zero, so that the device is always ready to respond to a TurnLightOn
request.

Actions

• TurnUpLightOn(): Turn up light on.

• TurnDownLightOn(): Turn down light on.
• TurnUpLightOff(): Turn off up light.
• TurnDownLightOff(): Turn off down light.
• ToggleUpLight(): Change up light from on to off, or off to on.
• ToggleDownLight(): Change down light from on to off, or off to on.

Note that TurnLightOff/TurnLightOn honor the up_light and down_light enable variables. That is, the user is able to use the factory remote to
select a prefered combination of up and down light, and that combination is restored when TurnLightOn is called, perhaps through a voice
integration.

35 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The Brightness feature governs lights which can be dimmed to speci�ed brightness level.

This feature is common on classic Ceiling Fans whose remotes have displays. Note, however, that classic Ceiling Fans whose remotes do not
have displays typically only support HoldToDim or HoldToDimUpDown feature.

Properties

• feature_brightness: (boolean, PATCH-able) true = Brightness feature enabled (default), false = Brightness feature disabled. When PATCH-
ing to false, brightness is set to 100 prior to disabling the feature.

State Variables

• brightness: (integer) percentage value of brightness, 1-100. If light=0, brightness represents the last brightness setting and the brightness
to resume when user turns on light. If fan has no dimmer or a non-stateful dimmer, brightness is always 100.

Actions

• SetBrightness(brightness): Set the brightness of the light to speci�ed percentage. Value of 0 is ignored, use TurnLightOff instead.
• IncreaseBrightness(amount): Increase brightness of light by speci�ed percentage. If light is off, it will be turned on at (0 + amount).
• DecreaseBrightness(amount): Decrease light brightness by speci�ed percentage. If attempting to decrease brightness below 1%, light
will remain at 1%. Use TurnLightOff to turn off the light. If the light is off, the light will remain off but the remembered brightness will be
decreased.
• CycleBrightness(amount): Cycle brightness up/down. Implicitly turns on light. NOTE: This action is for the sake of remote controls with a
hold-to-dim button. Please do not use in integrations because it tends to be a frustrating experience. SetBrightness is strongly preferred
for its predictability.

NOTE: The brightness level is remembered on TurnLightOff and restored on TurnLightOn.

36 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The LowEndTrim feature allows a remapping of the brightness levels to increase the minimum physical brightness sent to the lights. This is
useful with landscape lighting dimmers where the installer has a choice of luminaires which may have different minimum duty-cycle
requirements.

When a value of X% brightness is requested via the API (or, of course, via the app), the value will be remapped to Y% before being sent to the
lights, accoring to the formula:

Y = (X - 1)*(100 - low_end_trim)/99 + low_end_trim

In plain English: low_end_trim sets the minimum brightness of the lights.

Availability: Currently on SBB low-voltage dimmers only.

Properties

• low_end_trim: (integer) percentage value of minimum physical brightness to send to lights. Set to 1% for full brightness range. Allowed
range: 1 to 90, inclusive. PATCH to null to restore factory default.

State Variables

(none)

Actions

(none)

37 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The UpDownBrightness feature extends the Brightness feature to cover the ability of ceiling fans with separately dimmable up and down
lights.

This feature is almost only found on Smart by Bond Ceiling Fans.

Properties

(none)

State Variables

• up_light_brightness: (integer) percentage value of up light brightness, 1-100.

• down_light_brightness: (integer) percentage value of down light brightness, 1-100.

Actions

• SetUpLightBrightness(brightness): Similar to SetBrightness but only for the up light.

• SetDownLightBrightness(brightness): Similar to SetBrightness but only for the down light.
• IncreaseUpLightBrightness(amount): Similar to IncreaseBrightness but only for the up light.
• IncreaseDownLightBrightness(amount): Similar to IncreaseBrightness but only for the down light.
• DecreaseUpLightBrightness(amount): Similar to DecreaseBrightness but only for the up light.
• DecreaseDownLightBrightness(amount): Similar to DecreaseBrightness but only for the down light.

NOTE: The brightness level of each light is remembered on TurnLightOff, TurnUpLightOff, TurnDownLightOff and restored on TurnLightOn, etc.

NOTE: IncreaseBrightness and DecreaseBrightness operate on whichever of the up and down lights are enabled, but will never enable or
disable one or the other light.

38 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Temp

The ColorTemp feature is used to control the correlated color temperature (CCT) of a light.

The ColorTemp feature requires the Light and Brightness features, and there are currently no products with both ColorTemp and UpDownLight.
In other words, all CCT-adjustable products have exactly one dimmable light, and if the Brightness option is disabled via feature toggles, the
ColorTemp feature will also be disabled.

Note that the color temperature is works in 100 Kelvin (K) steps. Attempts to set non-multiples of 100 K will result in unde�ned rounding
behavior.

Properties

• max_color_temp: (integer) maximum color temperature in Kelvin

• min_color_temp: (integer) minimum color temperature in Kelvin

State Variables

• color_temp: (integer) color temperature in Kelvin. Resolution: 100 K

Actions

39 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

• SetColorTemp(int): Set color temperature. Implicitly turns Light on.

• IncreaseColorTemp(int): Increase color temperature a speci�ed number of degrees K. Implicitly turn Light on.
• DecreaseColorTemp(int): Increase color temperature a speci�ed number of degrees K. Implicitly turns Light on.
• CycleColorTemp(int): Change color temperature in cyclical fashion, similar to CycleBrightness. Implicitly turns on Light. NOTE: This exists
for the sake of remote controls, it is generally not useful for integrations, please use SetColorTemp instead.
• CycleColorTempPreset(): Jump to next preset CCT value from an internal list of presets. Number and value of presets unde�ned and may
vary by model. Useful for very basic integrations where you have just a single push button.

The Color feature is available on full color lighting products.

The Color feature requires the Light and Brightness features. The ColorTemp is optionally also available at the same time as Color.

Whenever SetBrightness or other brightness-changing actions are called, rgb and hsv values are updated to re�ect the change. For
example, if the rgb values are (128, 0, 0) with brightness 50, and brightness is increased to 100, then rgb values are updated to (255, 0, 0).

Properties

(none)

State Variables

• rgb: (object) JSON object containing the following keys which describe the apparent color of the light.
◦ r - (0--255) apparent red value
◦ g - (0--255) apparent green value
◦ b - (0--255) apparent blue value
• hsv: (object) similar to rgb but for the HSV colorspace.
◦ h - (0--359) apparent hue (in degrees)
◦ s - (0--100) apparent saturation (in percent)
◦ v - (0--100) apparent value in HSV colorspace (in percent). Note that v and brightness are the same value. Users should
typically use brightness rather than v .

Actions

40 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

• SetRGB({r:int, g:int, b:int}) Set color by RGB values. Light is implicitly turned on if off. A subset of the apparent color components may be
speci�ed, in which case unspeci�ed values are left unchanged. Example use case is an integration with seperate R, G, and B sliders, which
would do SetRGB(r:int) when the red slider is adjusted.

• SetHSV({h:int, s:int, v:int}) Set color by HSV values. Light is implicitely turned on if off. A subset of the h , s , and v parameters may
be provided. Unspeci�ed parameters will remain unchanged.

The recommended use case is a 2-D color picker where only the h and s parameters would be supplied, leaving brightness
unchanged.

• CycleColorPreset() Change to next color preset. In HSV-space, these presets are line segments of constant hue and maximum saturation,
seperated by 60 degrees. The next color preset is skipped if current hue is within 30 degrees. Light is implicitely turned on if off. Different
devices will specify different sets of color presets. This is intended to be used with tapping action on "Color" button of RGB SBB products'
front-panels.

• CycleColor(amount) Implicitly increase Hue by speci�ed amount, wrapping around. Saturation remains unchanged. Value (brightness) is
unchanged. Light is implicitely turned on if off. This is intended to be used with holding action on "Color" button of RGB SBB products'
front-panels.

The RGBW feature is available on products which under-the-hood actually have four-channel LEDs with a seperate white channel.

The RGBW feature requires the RGB feature.

We use a mapping between RGB/HSV-space and RGBW-space, which is currently to use only the W channel when S is zero, and to use only the
RGB channels when S is non-zero. However this is subject to change.

RGBW mapping with ColorTemp feature is currently unde�ned.

Properties

41 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

(none)

State Variables

• rgbw: (object) JSON object containing the following keys which describe the low-level values of the LED channels. These values are
updated whenever the color changes. All are integers in the range 0-255:
◦ r - low-level red channel
◦ g - low-level green channel
◦ b - low-level blue channel
◦ w - low-level white channel

Actions

• SetRGBW({r:int, g:int, b:int, w:int}) Set low-level values of LED channels. Light is implicitely turned on if off. Note that with SetRGBW,
combinations of LED channels can be achieved which are unreachable with SetRGB.

The Flame feature is used by �replaces to indicate �ame level.

The Flame feature requires the Power feature.

Properties

State Variables

• �ame: (integer) value from 1 to 100. If power=0, �ame represents the last �ame setting and the �ame to which the device resumes when
user asks to turn on.

Actions

42 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

• SetFlame(�ame): Set �ame and turn on. If �ame>100, 100 is assumed. If the �replace is off, implicitly turn on the power. Setting �ame to
zero or a negative value is ignored.
• IncreaseFlame(�ame): Increase �ame level of �replace by speci�ed number of �ames. If the �replace is off, implicitly turn on the power.
• DecreaseFlame(�ame): Decrease �ame level by speci�ed number of �ames. If attempting to decrease �replace �ame below 1 , the
�replace will remain at �ame 1. That is, power will not be implicitly turned off. If the power is already off, DecreaseFlame is ignored.

The Open feature is used to describe a device that can be opened and closed. Common use cases are motorized shades and garage doors.

Properties

(none)

State Variables

• open: (integer) 1 = open, 0 = closed

Actions

• Open(): Open the device.

• Close(): Close the device.
• ToggleOpen(): Close the device if it's open, open it if it's closed

Notes

If your remote has a discrete stopping command, consider using the Hold() action to stop the motion of the device.

43 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The Position feature is used to describe a device that can be opened to a speci�c position as a percentage. The common use case is
motorized shades.

The Position feature requires the Open feature.

Properties

(none)

State Variables

• position: (integer) value from 0 to 100: 0 = open, 100 = closed.

Actions

• SetPosition(position): Set device to speci�ed position percentage.

• IncreasePosition(amount): Close the device by the speci�ed percentage of the full range.
• DecreasePosition(amount): Open the device by the speci�ed percentage of the full range.

Notes

[March 2021] At this time, the Position feature is available only for certain Motorized Shades on the Bond Bridge Pro.

The feature may be enabled or disabled via the feature toggle property feature_position , analogous to the other feature toggles.
However, if course_time is present, it will need to also be set to a non-negative value before the actions and state variables will be exposed,
so as to avoid integrations from showing a slider interface without the Bridge having the capability of setting position.

44 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The CourseTime feature is used for shades whose RF protocols do not natively support Position. Bond Bridge Pro emulates a Position feature
using a custom dead reckoning algorithm. This requires the client to specify the time required for the shade to open or close.

The CourseTime feature requires the Position feature.

Properties

• course_time: (integer) speci�es the amount of time, in milliseconds, required for the device to fully open or close. Depending on the
device template, this property may or may not be present. Defaults to -1, meaning uncon�gured.

State Variables

(none)

Actions

(none)

The FpFan feature controls a �replace fan. The FpFan feature is independent of the power feature, which for �replaces indicates whether the
�ame is on or off.

Properties

(none)

State Variables

• fpfan_power: (integer) 1 = on, 0 = off

• fpfan_speed: (integer) from 1-100

45 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Actions

• TurnFpFanOff(): Turn the �replace fan off

• TurnFpFanOn(): Turn the �replace fan on, restoring the previous speed
• SetFpFan(speed): Sets the speed of the �replace fan

Collected here are some actions that may be used with other features, but have no state-change behavior on the Bond.

Actions

• Stop(): This action tells the Bond to stop any in-progress transmission and empty its transmission queue.
• Hold(): Can be used when a signal is required to tell a device to stop moving or the like, since Stop is a special "stop transmitting" action
• Pair(): Used in devices that need to be paired with a receiver.
• StartDimmer(): Start dimming. The Bond should time out its transmission after 30 seconds, or when the Stop action is called.
• StartUpLightDimmer(): Use this and the StartDownLightDimmer instead of StartDimmer if your device has two dimmable lights.
• StartDownLightDimmer(): The counterpart to StartUpLightDimmer
• StartIncreasingBrightness(): Similar to StartDimmer, but doesn't cycle and only increases brightness.
• StartDecreasingBrightness(): Similar to StartDimmer, but doesn't cycle and only decreases brightness.

46 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Returns a list of device IDs and the corresponding device hashes. The hashes change if any part of the device (its name, location, state) has
changed. Please see the "Hash Tree" documentation for an example.

AUTHORIZATIONS: None

Responses

200 List active devices

401 Unauthorized

500 Internal Server Error

/v2/devices

Response samples

200 401 500

47 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy Expand all Collapse all

{
"_": "7fc1e84b",
- "3b20f300": {
"_": "9a5e1136"
},
- "4caf6472": {
"_": "409d124b"
}
}

REQUEST BODY SCHEMA: application/json

name
string
required

type string
required
• CF : Ceiling Fan
• FP : Fireplace
• MS : Motorized Window Coverings (Shades, Screens, Drapes) and Awnings
• GX : Generic device
• LT : Light
• BD : Bidet

This type �eld does not impact the functionality of the device. The type �eld should be used by API
clients to improve the user experience. For example, the Bond Home app uses this �eld to determine what
icon to show when browsing a list of Devices on the Bridge.

48 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The type �eld may be used by integrations to determine the category of interface to be selected when
such a selection is mandated by the platform. For example, Google Assistant integration requires
developers to choose a device type such as Fan or Light. however we strongly encourage developers to
implement the functional aspects of integrations based on Features (i.e., available Actions, State variables,
and Properties).

subtype string
[Added in v2.21]

The subtype �eld is used to distinguish between categories of devices sublter than the type �eld
permits.

Currently, subtype is only used for Motorized Window Coverings and Awnings ( type = MS ), with the
following options:

• ROLLER : a roller blackout shade which blocks light and provides privacy
• SHEER : a shade which permits light to pass and does not provide privacy
• AWNING : an outdoor patio covering

This �eld does not impact functionality in any way. Furthermore, the subtype �eld must only be used for
analytics and aesthetic purposes by the API client. New subtypes may be introduced without notice. API
clients should always be prepared to fall back to a reasonable default based on the device type .

The subtype �eld is not limited by the �rmware, but rather speci�ed by Bond internally and included in
Device creation requests from the Bond Home app.

WARNING: Although currently it is not the case, at some point the same subtype string may be re-used
with different meanings between different device types . To take a hypothetical example, we may have a
gas-powered �replace device ( type = FP, subtype = GAS ) but also a gas-powered bidet ( type =
BD, subtype = GAS ).

template string
An internal name describing what sort of protocol the remote represented by the device implements. Upon
a POST with a valid template string, the device self-populates its panel with some default controls,
initializes its state, and �nds a script to de�ne its behavior.

49 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Most templated devices need additional parameters, such as an address addr , frequency freq , bits
per second bps , and length of the zeros between repetititions zero_gap . These should be speci�ed in
an object properties in the POST body.

location string

Responses

201 Resource Created

400 Bad request

401 Unauthorized

409 Con�ict

500 Internal Server Error

/v2/devices

Request samples

Payload

50 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"name": "My Fan",
"type": "CF",
"subtype": "AWNING",
"template": "A1",
"location": "Kitchen"
}

Response samples

201 400 401 409 500

Copy
{
"_id": "01234567"
}

AUTHORIZATIONS: None

51 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

PATH PARAMETERS

device_id
number
required

Responses

— 204 Remove device

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}

Response samples

401 404 500

Copy

52 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

Basic device information. The "_" in each of state , properties , actions , and commands will change if that endpoint's resource
changes.

NOTE: commands are only present on Bridge devices

AUTHORIZATIONS: None

PATH PARAMETERS

device_id
number
required

Responses

200 Get device

401 Unauthorized

404 Not Found

53 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

500 Internal Server Error

/v2/devices/{device_id}

Response samples

200 401 404 500

Copy Expand all Collapse all

{
"name": "My Fan",
"type": "CF",
"subtype": "AWNING",
"template": "A1",
"location": "Kitchen",
- "actions": [
"TurnOn",
"TurnOff",
"TogglePower",
"SetSpeed",
"IncreaseSpeed",
"DecreaseSpeed"
],

54 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

- "properties": {
"_": "84cd8a43"
},
- "state": {
"_": "ad9bcde4"
},
- "commands": {
"_": "ad9bcde4"
}
}

AUTHORIZATIONS: None

PATH PARAMETERS

device_id
number
required

REQUEST BODY SCHEMA: application/json

name
string
required

type string
required
• CF : Ceiling Fan
• FP : Fireplace
• MS : Motorized Window Coverings (Shades, Screens, Drapes) and Awnings

55 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

• GX : Generic device
• LT : Light
• BD : Bidet

This type �eld does not impact the functionality of the device. The type �eld should be used by API
clients to improve the user experience. For example, the Bond Home app uses this �eld to determine what
icon to show when browsing a list of Devices on the Bridge.

The type �eld may be used by integrations to determine the category of interface to be selected when
such a selection is mandated by the platform. For example, Google Assistant integration requires
developers to choose a device type such as Fan or Light. however we strongly encourage developers to
implement the functional aspects of integrations based on Features (i.e., available Actions, State variables,
and Properties).

subtype string
[Added in v2.21]

The subtype �eld is used to distinguish between categories of devices sublter than the type �eld
permits.

Currently, subtype is only used for Motorized Window Coverings and Awnings ( type = MS ), with the
following options:

• ROLLER : a roller blackout shade which blocks light and provides privacy
• SHEER : a shade which permits light to pass and does not provide privacy
• AWNING : an outdoor patio covering

This �eld does not impact functionality in any way. Furthermore, the subtype �eld must only be used for
analytics and aesthetic purposes by the API client. New subtypes may be introduced without notice. API
clients should always be prepared to fall back to a reasonable default based on the device type .

The subtype �eld is not limited by the �rmware, but rather speci�ed by Bond internally and included in
Device creation requests from the Bond Home app.

WARNING: Although currently it is not the case, at some point the same subtype string may be re-used

56 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

with different meanings between different device types . To take a hypothetical example, we may have a
gas-powered �replace device ( type = FP, subtype = GAS ) but also a gas-powered bidet ( type =
BD, subtype = GAS ).

template string
An internal name describing what sort of protocol the remote represented by the device implements. Upon
a POST with a valid template string, the device self-populates its panel with some default controls,
initializes its state, and �nds a script to de�ne its behavior.

Most templated devices need additional parameters, such as an address addr , frequency freq , bits
per second bps , and length of the zeros between repetititions zero_gap . These should be speci�ed in
an object properties in the POST body.

location string

Responses

200 Change device �eld

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}

57 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Request samples

Payload

Copy
{
"name": "My Fan",
"type": "CF",
"subtype": "AWNING",
"template": "A1",
"location": "Kitchen"
}

Response samples

200 401 404 500

Copy Expand all Collapse all

{
"name": "My Fan",
"type": "CF",
"subtype": "AWNING",
"template": "A1",
"location": "Kitchen",

58 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

- "actions": [
"TurnOn",
"TurnOff",
"TogglePower",
"SetSpeed",
"IncreaseSpeed",
"DecreaseSpeed"
],
- "properties": {
"_": "84cd8a43"
},
- "state": {
"_": "ad9bcde4"
},
- "commands": {
"_": "ad9bcde4"
}
}

59 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

AUTHORIZATIONS: None

PATH PARAMETERS

device_id
number
required

Responses

200 Get device

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/state

Response samples

200 401 404 500

60 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy Expand all Collapse all

{
- "breeze": [
1,
0.2,
0.9
],
"brightness": 75,
"light": 1,
"power": 0,
"speed": 2,
"timer": 3599
}

Update the Bond's belief about the state of a device.

This is useful, for example, for Ceiling Fans that have a command for ToggleLight, but no discrete commands TurnLightOn and TurnLightOff.
In this case, it is possible for the Bond's belief about the device state to be incorrect, and so this method allows that belief to be corrected.

This does NOT cause the Bond to transmit any control signal.

(Bridge-Only)

AUTHORIZATIONS: None

PATH PARAMETERS

61 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

device_id
number
required

REQUEST BODY SCHEMA: application/json

any (State)

Responses

— 200 State belief updated

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/state

Request samples

Payload

62 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy Expand all Collapse all

{
- "breeze": [
1,
0.2,
0.9
],
"brightness": 75,
"light": 1,
"power": 0,
"speed": 2,
"timer": 3599
}

Response samples

401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

63 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

See the Features section above for other properties which may be available on your devices.

A quick description of trust_state by example follows:

The scenario: the Bond has a "ToggleLight" command, and the Bond believes the light to be on. The user requests the action "LightOn". If the
Bond trusts its state, it will do nothing, as the light is already on, and sending a toggle command would turn it off. If, however, the Bond does
not trust its state, it will send the toggle, and believe that now it knows the true state of the physical device.

trust_state set to false is mostly useful if the user intends to use a physical remote together with the Bond and is the default, trust
state set to true is mostly useful if the user would like to control their device remotely with complete con�dence that what the Bond
reports is the device's actual state.

AUTHORIZATIONS: None

PATH PARAMETERS

device_id
number
required

Responses

200 Get device properties

64 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/properties

Response samples

200 401 404 500

Copy
{
"trust_state": false,
"addr": "10101",
"freq": 434300,
"bps": 3000,
"zero_gap": 30
}

65 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

See the documentation of the individual properties for whether they can be PATCHed.

AUTHORIZATIONS: None

PATH PARAMETERS

device_id
number
required

REQUEST BODY SCHEMA: application/json

trust_state boolean
Whether or not the Bond should trust its toggleable state belief. This is the con�dence the Bond has that
this device's state belief is accurate, and is only present if a "Toggle" command is present (for power ,
light , direction , etc.), and is false by default. (Bridge-only)

Responses

— 200 Properties updated

401 Unauthorized

404 Not Found

500 Internal Server Error

66 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/devices/{device_id}/properties

Request samples

Payload

Copy
{
"trust_state": false
}

Response samples

401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

67 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

action_name is the name of the action from the actions list in the response to GET /devices/{device_id} .

This endpoint blocks until con�rmation that the Bond has executed the action. Timeout shall be no more than 7 seconds.

To check the resulting state, the client may query /devices/{device_id}/state .

See the Features section to learn what the various actions mean, and what argument is expected, if any. For example, the action SetSpeed
takes an integer parameter which is the desired speed number.

AUTHORIZATIONS: None

PATH PARAMETERS

action_name
string
required

device_id
number
required

REQUEST BODY SCHEMA: application/json

object

68 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

200 Action executed [since v2.12.4]

— 204 Action executed [prior to v2.12.4]

400 Bad request

401 Unauthorized

500 Internal Server Error

/v2/devices/{device_id}/actions/{action_name}

Request samples

Payload

69 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"argument": 4
}

Response samples

200 400 401 500

Copy
{
"argument": 4
}

70 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

[SBB-only] Provides the current SBB remote address and information about the learn window. The SBB unit will only honor commands
received with a matching address.

NOTE: If addr0_is_dip is present and true, then the �rst address (addr0) corresponds to physical "DIP" switches on the receiver. The client
may take this into account by seperately listing this "DIP" setting from the rest of the addresses which may be set via the API. Note that the
special address 0xdead indicates that the DIP setting is being ignored (after it has been explicitely deleted via the API).

AUTHORIZATIONS: None

PATH PARAMETERS

device_id
number
required

Responses

200 Get SBB Remote Address

401 Unauthorized

404 Not Found

500 Internal Server Error

71 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/devices/{device_id}/addr

Response samples

200 401 404 500

Copy Expand all Collapse all

{
- "addr": [
"dead",
"0f2a",
"0002",
"0003"
],
"addr_slots": 5,
"learn_window_ms": 60000,
"learn_window_remaining_ms": 1100,
"learn_window_open": true,
"learn_count": 0,
"addr0_is_dip": true
}

72 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

[SBB-only] Modify either the Device Remote Address or open/close the learn window. While the learn window is open, the SBB unit may learn a
new physical remote when user presses the Learn button (or holds down the Power/Stop button for 5 seconds).

Note that on most SBB receivers, the learn window is automatically opened when electrical power is �rst connected. This is the typical "auto-
learning" function. However, on recievers with DIP switches ( addr0_is_dip ), the learn window must be opened manually. This is because
those receivers follow the conceptually simpler model of "you gotta set the DIP switches on the reciever and transmitter to match" without any
"magic learning" occuring---at least until you use the Manage Remotes feature of the Bond Home app or this endpoint directly.

Note that to add a new remote address, the addr �eld should be PATCHed with a single string, not an array. The provided address will be
appended to the array of addresses, with the oldest address being overwritten if len( addr[] ) was already equal to addr_slots .

If the same address is learned which was already in the list, the duplicate will indeed be added. This is to allow an installer to use a low-tech
way of forgetting unwanted remotes---by re-learning the same remote 5 times---which the installers are used to doing with similar receivers.

This endpoint is useful especially where there are multiple SBB devices on the same mains circuit.

AUTHORIZATIONS: None

PATH PARAMETERS

device_id
number
required

REQUEST BODY SCHEMA: application/json

addr Array of strings

Learned remote address(es) in hexadecimal, may be patched only with a single address string to be
added.

learn_window_open boolean

73 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Whether new address can be learned via RF. True iff learn_window_remaining_ms is nonzero.

addr0_is_dip boolean
If present and true, indicates that the receiver has DIP switches which may be adjusted to set the zeroth
address.

Responses

200 Modify Device Remote Address or Learn Window

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/addr

Request samples

Payload

Copy Expand all Collapse all

74 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
- "addr": [
"dead",
"0f2a",
"0002",
"0003"
],
"learn_window_open": true,
"addr0_is_dip": true
}

Response samples

200 401 404 500

Copy Expand all Collapse all

{
- "addr": [
"dead",
"0f2a",
"0002",
"0003"
],
"addr_slots": 5,
"learn_window_ms": 60000,
"learn_window_remaining_ms": 1100,
"learn_window_open": true,
"learn_count": 0,

75 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"addr0_is_dip": true
}

[SBB-only] If no addr is provided, then: Restores factory default Device Remote Address and closes learn window. If the receiver has DIP
switches ( addr0_is_dip ) then the default address will be determined by the position of those DIP switches.

However, if addr is provided, then: Removes just the speci�ed address from the list. If the receiver has DIP switches ( addr0_is_dip ) and
the address being deleted is the �rst one (addr0) then that address will be changed to 0xdead . This is useful if a receiver is installed with
DIP switches indicating an address which is being used by a neighbor. To avoid interference, the user can delete addr0 via the app. NOTE: Any
change to the DIP switches on the reciever will cause the addr0 to change to re�ect that new DIP setting.

AUTHORIZATIONS: None

PATH PARAMETERS

device_id
number
required

Responses

200 Remote address successfully reset, learn window closed.

401 Unauthorized

76 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/addr

Response samples

200 401 404 500

Copy Expand all Collapse all

{
- "addr": [
"dead",
"0f2a",
"0002",
"0003"
],
"addr_slots": 5,
"learn_window_ms": 60000,
"learn_window_remaining_ms": 1100,
"learn_window_open": true,
"learn_count": 0,
"addr0_is_dip": true

77 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Reload the command table for the given device de�nition. This deletes all current commands and rebuilds the device de�nition's default
commands. This will overwrite any user customization of the commands, such as renaming, icon changes, and deleting commands.

The device's state and properties are preserved, in order to avoid a loss of control.

This endpoint may be called after a template device de�nition has been updated to cause newly-de�ned or modi�ed commands to be
exported to the device panel.

This endpoint is only available for a device with a template string.

AUTHORIZATIONS: None

PATH PARAMETERS

device_id
number
required

78 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

— 204 Device de�nition reloaded

401 Unauthorized

404 Not Found

500 Internal Server Error

79 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/devices/{device_id}/reload

Response samples

401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

This feature is intended to be used with smart Ceiling Fan receivers that are connected to "dumb" wall switches. Many users have existing

80 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

non-smart ceiling fans which are connected to non-smart wall switches. These non-smart ceiling fans typically have some pull switches
where the user can set the desired state, and then the wall switch is used as the means of operating the device. For example, the ceiling fan
may be the primary light source in the room, and the user relies on the wall switch as a normal light switch. When they then make the fan
smart by adding a Smart By Bond receiver to the fan, they expect that they can continue to use the wall switch. A problem arises when the
user turns off the fan light using the API (Alexa, app, etc.) and then enters the room and attempts to operate using the wall switch. The fan will
remain in the state with light off. The Power On State feature allows users to guarantee a prefered state every time the device powers on,
making it easier to use in a situation where the wall switch is relied upon.

This feature is only available on certain SBB products where it makes sense, speci�cally all ceiling fans. We have not enabled it on in-wall
switches and dimmers and other SBB products where there is only a power supply or circuit breaker behind the product, rather than there
possibly being a user-facing "dumb" wall switch.

[SBB-only, added in v2.17]

AUTHORIZATIONS: None

PATH PARAMETERS

device_id
number
required

Responses

200 Current Power Cycle State

401 Unauthorized

404 Not Found

500 Internal Server Error

81 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/devices/{device_id}/power_cycle_state

Response samples

200 401 404 500

Copy Expand all Collapse all

{
"enabled": false,
- "state": {
"light": 1,
"brightness": 100,
"power": 0,
"speed": 3
}
}

AUTHORIZATIONS: None

PATH PARAMETERS

82 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

device_id
number
required

REQUEST BODY SCHEMA: application/json

enabled boolean
If true, device will revert to speci�ed state after power loss. If false, device will maintain previous state
across power loss ("Last State" feature).

state object
State to revert to after power loss. Same schema as for Device state.

Responses

200 Power Cycle State updated

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/power_cycle_state

Request samples

83 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Payload

Copy Expand all Collapse all

{
"enabled": false,
- "state": {
"light": 1,
"brightness": 100,
"power": 0,
"speed": 3
}
}

Response samples

200 401 404 500

Copy Expand all Collapse all

{
"enabled": false,

84 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

- "state": {
"light": 1,
"brightness": 100,
"power": 0,
"speed": 3
}
}

Deleting the Power Cycle State for a Device will cause it to revert to the default as programmed from the factory. This is typically a disabled
state. For most API clients, it makes more sense to use PATCH rather than DELETE.

AUTHORIZATIONS: None

PATH PARAMETERS

device_id
number
required

Responses

200 Power Cycle State restored to factory default

401 Unauthorized

85 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/power_cycle_state

Response samples

200 401 404 500

Copy Expand all Collapse all

{
"enabled": false,
- "state": {
"light": 1,
"brightness": 100,
"power": 0,
"speed": 3
}
}

86 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Returns a list of command IDs and the corresponding command hashes. Please see the "Hash Tree" documentation for an explanation of
hashes.

PATH PARAMETERS

device_id
string
required

Responses

200 Command list returned

401 Unauthorized

404 Not Found

500 Internal Server Error

87 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/devices/{device_id}/commands

Response samples

200 401 404 500

Copy Expand all Collapse all

{
"_": "7fc1e84b",
- "3b20f300": {
"_": "9a5e1136"
},
- "4ad874d2": {
"_": "84819a9f"
},
- "a94328bc": {
"_": "23141efa"
},
- "d87d6ef2": {
"_": "2425a8bc"
}
}

88 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Creates a Command under a speci�c Device.

PATH PARAMETERS

device_id
string
required

REQUEST BODY SCHEMA: application/json

name string
required
Name of corresponding button displayed in Bond App

action string
required
Action which should be triggered when button is pressed.

argument any or null

Argument of action . If absent, no argument will be used. May be any JSON value, not only an object.

icon string
Icon slug. (This is the base of the name of the icon to use to represent this command in the App.)

category_name string
The category in which to group this command.

button_type string
The type of button to use for this command.

hidden boolean
Whether to hide this command in the mobile app. Useful for exposing an action, but not showing its

89 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

command on the device panel.

Responses

201 Resource Created

400 Bad request

401 Unauthorized

500 Internal Server Error

/v2/devices/{device_id}/commands

Request samples

Payload

Copy
{
"name": "Light",
"action": "SetSpeed",

90 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"argument": 3,
"icon": "speed_3",
"category_name": "fan",
"button_type": "tap",
"hidden": true
}

Response samples

201 400 401 500

Copy
{
"_id": "01234567"
}

Get information about a Command.

PATH PARAMETERS

device_id
string
required

91 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

command_id
string
required

Responses

200 Command object returned

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/commands/{command_id}

Response samples

200 401 404 500

Copy
{
"name": "Light",

92 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"action": "SetSpeed",
"argument": 3,
"icon": "speed_3",
"category_name": "fan",
"button_type": "tap",
"hidden": true
}

Modi�es any �elds of an existing Command.

PATH PARAMETERS

device_id
string
required

command_id
string
required

REQUEST BODY SCHEMA: application/json

name string
required
Name of corresponding button displayed in Bond App

action string
required
Action which should be triggered when button is pressed.

argument any or null

93 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Argument of action . If absent, no argument will be used. May be any JSON value, not only an object.

icon string
Icon slug. (This is the base of the name of the icon to use to represent this command in the App.)

category_name string
The category in which to group this command.

button_type string
The type of button to use for this command.

hidden boolean
Whether to hide this command in the mobile app. Useful for exposing an action, but not showing its
command on the device panel.

Responses

— 200 Command modi�ed

400 Bad request

401 Unauthorized

404 Not Found

500 Internal Server Error

94 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/devices/{device_id}/commands/{command_id}

Request samples

Payload

Copy
{
"name": "Light",
"action": "SetSpeed",
"argument": 3,
"icon": "speed_3",
"category_name": "fan",
"button_type": "tap",
"hidden": true
}

Response samples

400 401 404 500

Copy

95 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

Deletes speci�ed Command.

Any associated Signal will be implicitly deleted.

PATH PARAMETERS

device_id
string
required

command_id
string
required

Responses

— 204 Command deleted

401 Unauthorized

404 Not Found

96 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

500 Internal Server Error

/v2/devices/{device_id}/commands/{command_id}

Response samples

401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

97 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Get signal associated with this command.

PATH PARAMETERS

device_id
string
required

command_id
string
required

Responses

200 Signal returned

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/commands/{command_id}/signal

98 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Response samples

200 401 404 500

Copy
{
"freq": 434000,
"modulation": "OOK",
"data": "110100110110H",
"encoding": "cq",
"bps": 1000,
"reps": 12
}

Creates a Signal associated with this Command.

PATH PARAMETERS

device_id
string
required

command_id
string
required

99 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

REQUEST BODY SCHEMA: application/json

freq number
required
Frequency in kHz:

• >= 1000 is RF
• < 1000 is IR

Bond Bridge can only receive IR signals at or near 38 kHz, and will report all IR signals as 38 kHz.

Bond Bridge currently transmits all IR signals at 38 kHz also.

modulation string
• OOK = on-off keying
• GFSK = gaussian frequency-shift keying

If not provided, defaults to OOK .

data string
required
String representation of data bits to be transmitted.

The maximum length of the data string is 6144 bytes.

encoding string
required
Speci�es the encoding of the data string.

In all cases, the duration of each bit is 1/ bps seconds.

CQ encoding ( "cq" )

This is a simple encoding where bits are represented using 0 and 1 , with some abbreviations for
sequences of bits.

Each character represents one or more bits:

100 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

• 0 single zero bit

• 1 single one bit
• C 2^0 (1) zero bits
• D 2^1 (2) zero bits
• E 2^2 (4) zero bits
• F 2^3 (8) zero bits
• ...
• Q 2^14 (16384) zero bits
• c thru q are just like C thru Q , but for one bits
• A the three bits 110
• B the three bits 011

Hex ( "hex" )

This is a simple encoding where the data string consists of hex bytes. Each hex byte represents 8 bits of
data.

Hex encoding is currently limited to only work at 40000 bps.

This is the default encoding for scan results.

bps number
required
Bitrate of data . Range is 100 to 40000.

reps number
Number of times that data should be repeated.

If not provided, 1 is assumed.

use_scan boolean
If present and true, the Signal recorded by the most recent scan will be used, with all other �elds ignored

101 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

— 200 Signal set

400 Bad request

401 Unauthorized

500 Internal Server Error

/v2/devices/{device_id}/commands/{command_id}/signal

Request samples

Payload

Copy
{
"freq": 434000,
"modulation": "OOK",
"data": "110100110110H",
"encoding": "cq",

102 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"bps": 1000,
"reps": 12,
"use_scan": true
}

Response samples

400 401 500

Copy
{
"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

Modi�es any �elds of an existing Signal.

PATH PARAMETERS

device_id
string
required

103 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

command_id
string
required

REQUEST BODY SCHEMA: application/json

freq number
required
Frequency in kHz:

• >= 1000 is RF
• < 1000 is IR

Bond Bridge can only receive IR signals at or near 38 kHz, and will report all IR signals as 38 kHz.

Bond Bridge currently transmits all IR signals at 38 kHz also.

modulation string
• OOK = on-off keying
• GFSK = gaussian frequency-shift keying

If not provided, defaults to OOK .

data string
required
String representation of data bits to be transmitted.

The maximum length of the data string is 6144 bytes.

encoding string
required
Speci�es the encoding of the data string.

In all cases, the duration of each bit is 1/ bps seconds.

CQ encoding ( "cq" )

This is a simple encoding where bits are represented using 0 and 1 , with some abbreviations for
sequences of bits.

104 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Each character represents one or more bits:

• 0 single zero bit

• 1 single one bit
• C 2^0 (1) zero bits
• D 2^1 (2) zero bits
• E 2^2 (4) zero bits
• F 2^3 (8) zero bits
• ...
• Q 2^14 (16384) zero bits
• c thru q are just like C thru Q , but for one bits
• A the three bits 110
• B the three bits 011

Hex ( "hex" )

This is a simple encoding where the data string consists of hex bytes. Each hex byte represents 8 bits of
data.

Hex encoding is currently limited to only work at 40000 bps.

This is the default encoding for scan results.

bps number
required
Bitrate of data . Range is 100 to 40000.

reps number
Number of times that data should be repeated.

If not provided, 1 is assumed.

use_scan boolean
If present and true, the Signal recorded by the most recent scan will be used, with all other �elds ignored

105 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

— 200 Signal modi�ed

400 Bad request

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/commands/{command_id}/signal

Request samples

Payload

Copy
{
"freq": 434000,
"modulation": "OOK",

106 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"data": "110100110110H",
"encoding": "cq",
"bps": 1000,
"reps": 12,
"use_scan": true
}

Response samples

400 401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

Deletes speci�ed Signal.

Attempts to use the corresponding Actions will return 500 until a new Signal is associated with this Command or the Command is deleted.

PATH PARAMETERS

107 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

device_id
string
required

command_id
string
required

Responses

— 204 Signal deleted

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/commands/{command_id}/signal

Response samples

401 404 500

Copy

108 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

Transmits the signal associated with the command.

Note: This does NOT execute the associated Action, but rather just transmits the signal as if it had been PUT to signal/tx, so the device state
will not be updated and light gating will not be checked.

PATH PARAMETERS

device_id
string
required

command_id
string
required

REQUEST BODY SCHEMA: application/json

Schema not provided

109 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

— 204 Command transmitted

400 Bad request

401 Unauthorized

500 Internal Server Error

/v2/devices/{device_id}/commands/{command_id}/tx

Request samples

Payload

Copy
{ }

Response samples

110 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

400 401 500

Copy
{
"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

Returns a list of Group IDs and the corresponding Group hashes. The hashes change if any part of the Group (its name, state, type, etc.) has
changed. The hash is not updated if underlying Devices are updated in a way which does not effect the Group state or type.

Groups are only supported on Bond Bridges, not on Smart by Bond. Furthermore, Groups may only include Devices on the same Bridge.

AUTHORIZATIONS: None

111 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

200 List Groups

401 Unauthorized

500 Internal Server Error

/v2/groups

Response samples

200 401 500

Copy Expand all Collapse all

{
"_": "7fc1e84b",
- "3b20f300": {
"_": "9a5e1136"
},

112 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

- "4caf6472": {
"_": "409d124b"
}
}

For the creation of a Group distributed across multiple Bonds, clients should provide a 64-bit ID for the Group and provide that same ID in each
Group POST request in the _id �eld. See introductory section "Groups and Scenes" for detail. If the _id �eld is not provided, a random ID
will be assigned as with POST requests to other enumerations.

A Group is created containing the device IDs in the devices array. Using the devices �eld requires the client to predetermine what
devices are compatible in the sense of having a non-empty Actions intersection. If even a single device is incompatible, then the entire POST
will fail with a 400 error. For this reason, it is simpler for the client to make individual Groups Devices POSTs for each device to be added to the
Group, so that the Bond �rmware may provide a 400 error in case a device cannot be added due to incompatability.

Note that types and locations �elds cannot be speci�ed when creating a Group: these �elds are calculated based on the member
Devices.

REQUEST BODY SCHEMA: application/json

name
string
required

devices Array of arrays

List of member Device IDs.

This �eld may be set during Group creation, or may be updated using PATCH.

Alternatively, use the Group Devices endpoint's POST/DELETE methods to add/remove Devides from the

113 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Group.

Responses

201 Resource Created

400 Bad request

401 Unauthorized

409 Con�ict

500 Internal Server Error

/v2/groups

Request samples

Payload

Copy Expand all Collapse all

{

114 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"name": "Kitchen Shades",

- "devices": [
"aabbccdd",
"11223344",
"deadbeef"
]
}

Response samples

201 400 401 409 500

Copy
{
"_id": "01234567"
}

Groups are collections of Devices on a single Bridge.

AUTHORIZATIONS: None

PATH PARAMETERS

115 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

group_id
number
required

Responses

200 Get Group

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/groups/{group_id}

Response samples

200 401 404 500

Copy Expand all Collapse all

{
"name": "Kitchen Shades",

116 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

- "devices": [
"aabbccdd",
"11223344",
"deadbeef"
],
- "types": [
"MS"
],
- "locations": [
"Kitchen"
],
- "actions": [
"Open",
"Close",
"Preset"
],
- "state": {
"_": "ad9bcde4"
}
}

The devices list may be PATCHed to perform a bulk change to the membership in the group. A 400 error is returned if the devices are
incompatible.

If the devices list is PATCHed to empty, the group shard will vanish. That is, the group shard will be removed from the groups enumeration.
The groups enumeration will be sent as a gratuitous GET response.

117 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

To add Devices to the Group, use POST method on the Group Devices enumeration. To remove a Device from the Group, use the DELETE
method of the Group Device resource.

AUTHORIZATIONS: None

PATH PARAMETERS

group_id
number
required

REQUEST BODY SCHEMA: application/json

name
string
required

devices Array of arrays

List of member Device IDs.

This �eld may be set during Group creation, or may be updated using PATCH.

Alternatively, use the Group Devices endpoint's POST/DELETE methods to add/remove Devides from the
Group.

Responses

200 Change Group �eld

401 Unauthorized

404 Not Found

118 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

500 Internal Server Error

/v2/groups/{group_id}

Request samples

Payload

Copy Expand all Collapse all

{
"name": "Kitchen Shades",
- "devices": [
"aabbccdd",
"11223344",
"deadbeef"
]
}

Response samples

200 401 404 500

119 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy Expand all Collapse all

{
"name": "Kitchen Shades",
- "devices": [
"aabbccdd",
"11223344",
"deadbeef"
],
- "types": [
"MS"
],
- "locations": [
"Kitchen"
],
- "actions": [
"Open",
"Close",
"Preset"
],
- "state": {
"_": "ad9bcde4"
}
}

The entire Group is deleted.

120 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

AUTHORIZATIONS: None

PATH PARAMETERS

group_id
number
required

Responses

— 204 Delete Group

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/groups/{group_id}

Response samples

401 404 500

121 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

Device with the speci�ed ID is added to the Group.

A gratuitous update of the corresponding Group endpoint will occur to update clients as to the new devices, actions, state, and properties.

AUTHORIZATIONS: None

PATH PARAMETERS

group_id
string
required

REQUEST BODY SCHEMA: application/json

122 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

device string
ID of Device to add

Responses

— 204 Add Device to Group

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/groups/{group_id}/devices

Request samples

Payload

Copy
{
"device": "aabbccdd"

123 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Response samples

401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

Device with the ID speci�ed in the URL is removed from the Group.

A gratuitous update of the corresponding Group endpoint will occur to update clients as to the new devices, actions, state, and properties.

When the last device is removed from a group shard, the group shard will vanish. This applies whether the removal is explicit or implicit when
the device is deleted entirely from the Bridge.

That is, the group shard will be removed from the groups enumeration. The groups enumeration will be sent as a gratuitous GET response.

AUTHORIZATIONS: None

PATH PARAMETERS

124 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

group_id
string
required

device_id
string
required

Responses

— 204 Remove Device from Group

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/groups/{group_id}/devices/{device_id}

Response samples

401 404 500

Copy

125 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

Group State lists those state variables which are common to all member Devices. If all member Devices have the same value for a particular
state variable, then the Group variable will take that value. However, if member Devices differ in value, then the Group variable will take the
value null .

Note that Group states cannot be PATCHed.

AUTHORIZATIONS: None

PATH PARAMETERS

group_id
number
required

126 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

200 Get Group State

401 Unauthorized

404 Not Found

500 Internal Server Error

127 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/groups/{group_id}/state

Response samples

200 401 404 500

Copy
{
"open": 1
}

See the Features section above for other properties which may be available on your Groups.

Similar to the Group State object, the Properties available for a Group are those Properties which exist on every Device in the Group. If all

128 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Devices have the same value for a Property, then that value will be provided here. If Devices do not agree on a value, then that Property will be
listed but with a null value.

AUTHORIZATIONS: None

PATH PARAMETERS

group_id
number
required

Responses

200 Get Group properties

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/groups/{group_id}/properties

Response samples

200 401 404 500

129 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"trust_state": false,
"addr": "10101",
"freq": 434300,
"bps": 3000,
"zero_gap": 30
}

PATCHing one or more Group Properties implicitely PATCHes those Properties on all Devices in the Group. Gratuitous PATCH replies are sent
for each Device before this PATCH reply returns. If any errors occur in any of the underlying Device PATCH requests, this request will return a
500 error and the Devices' Properties will be left in unde�ned condition.

Example: If you set up 8 individual shades in your kitchen and then add them all to a Group, you can then, with a single request, enable or
disable the feature_position Property to enable/disable the "slider" feature. [This "slider" feature is avaiable only on the Bond Bridge Pro.]

AUTHORIZATIONS: None

PATH PARAMETERS

group_id
number
required

130 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

REQUEST BODY SCHEMA: application/json

trust_state boolean
Whether or not the Bond should trust its toggleable state belief. This is the con�dence the Bond has that
this device's state belief is accurate, and is only present if a "Toggle" command is present (for power ,
light , direction , etc.), and is false by default. (Bridge-only)

Responses

— 200 Properties updated

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/groups/{group_id}/properties

Request samples

Payload

131 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"trust_state": false
}

Response samples

401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

132 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

action_name is the name of the action from the actions list in the response to GET /groups/{group_id} .

This endpoint blocks until con�rmation that the Bond has executed the Action on all member Devices. Timeout shall be no more than 7
seconds.

To check the resulting state, the client may query /groups/{group_id}/state , but the member Device States are also updated.

AUTHORIZATIONS: None

PATH PARAMETERS

action_name
string
required

group_id
number
required

REQUEST BODY SCHEMA: application/json

object

Responses

200 Action executed

400 Bad request

401 Unauthorized

500 Internal Server Error

133 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/groups/{group_id}/actions/{action_name}

Request samples

Payload

Copy
{
"argument": 4
}

Response samples

200 400 401 500

Copy
{
"argument": 4
}

134 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Returns a list of sked_ids and the corresponding sked hashes. Please see the "Hash Tree" documentation for an explanation of hashes.

PATH PARAMETERS

device_id
string
required

Responses

200 Device Schedule list returned

401 Unauthorized

404 Not Found

500 Internal Server Error

135 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/devices/{device_id}/skeds

Response samples

200 401 404 500

Copy Expand all Collapse all

{
"_": "7fc1e84b",
- "3b20f300": {
"_": "9a5e1136"
},
- "4ad874d2": {
"_": "84819a9f"
},
- "a94328bc": {
"_": "23141efa"
},
- "d87d6ef2": {
"_": "2425a8bc"
}
}

136 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Creates a Device Schedule under a speci�c Device.

If the timezone or location settings in sys/time are not set, a 400 error may result depending on what mark is requested. Speci�cally, the
following requests will result in an 400 error:

• POSTed mark is midnight but sys/time.tz is null

• POSTed mark is dawn , dusk , sunrise , or sunset , but sys/time.grid is null

PATH PARAMETERS

device_id
string
required

REQUEST BODY SCHEMA: application/json

enabled boolean
If false, schedule will never execute, but will remain in device database.

Oneshot schedules (with days_of_week all False) automatically disable after executing once.

Defaults to true on PUT and POST.

action string
required
Action which will be run on device when schedule executes. If action requires an argument, argument
�eld is required.

argument any
Argument to action, if needed.

137 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

seconds integer
required
Time at which schedule should execute, relative to mark , in seconds. Negative numbers indicate "before"
the mark, positive numbers indicate "after" the mark.

days_of_week Array of booleans

required
Days of week on which the schedule should execute.

First element is for Sunday, last element is for Saturday.

The example value is for a schedules that executes only on weekdays.

Special case: if array is all false , the sked will run exactly once and will then disable itself
(enabled=false). This is rendered on UIs as a "Run Once" option.

Default: run every day, that is, array of 7 trues

mark string
required
Event which serves as the benchmark for the daily relative time. Options are:

• midnight : seconds is the time in seconds since midnight in the timezone speci�ed by the sys/
time endpoint.
• sunrise : seconds is seconds before or after local sunrise, as calculated using the Grid Locator
(see sys/time endpoint).
• sunset : like sunrise but when the sun goes down!
• dawn : seconds is seconds before or after local civil dawn: that is, when it gets light outside before
sunrise. This is when sun is 6 degrees below the horizon.
• dusk : like dawn, but for civil dusk: when it actually gets dark some time after sunset, when the sun
has descending 6 degrees below the horizon.

For our beloved customers near or within the Arctic Circle: please note that there will be periods of days
around the solstices that schedules based on the solar marks will not execute.

138 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

201 Resource Created

400 Bad request

401 Unauthorized

500 Internal Server Error

/v2/devices/{device_id}/skeds

Request samples

Payload

Copy Expand all Collapse all

{
"enabled": true,
"action": "SetBrightness",
"argument": 80,
"seconds": -3600,

139 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

- "days_of_week": [
false,
true,
true,
true,
true,
true,
false
],
"mark": "sunset"
}

Response samples

201 400 401 500

Copy
{
"_id": "01234567"
}

Get information about a Device Schedule.

140 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

PATH PARAMETERS

device_id
string
required

sked_id
string
required

Responses

200 Device Schedule object returned

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/skeds/{sked_id}

Response samples

200 401 404 500

141 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy Expand all Collapse all

{
"enabled": true,
"action": "SetBrightness",
"argument": 80,
"seconds": -3600,
- "days_of_week": [
false,
true,
true,
true,
true,
true,
false
],
"mark": "sunset"
}

Modi�es any �elds of an existing Device Schedule.

PATH PARAMETERS

device_id
string
required

142 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

sked_id
string
required

REQUEST BODY SCHEMA: application/json

enabled boolean
If false, schedule will never execute, but will remain in device database.

Oneshot schedules (with days_of_week all False) automatically disable after executing once.

Defaults to true on PUT and POST.

action string
required
Action which will be run on device when schedule executes. If action requires an argument, argument
�eld is required.

argument any
Argument to action, if needed.

seconds integer
required
Time at which schedule should execute, relative to mark , in seconds. Negative numbers indicate "before"
the mark, positive numbers indicate "after" the mark.

days_of_week Array of booleans

required
Days of week on which the schedule should execute.

First element is for Sunday, last element is for Saturday.

The example value is for a schedules that executes only on weekdays.

Special case: if array is all false , the sked will run exactly once and will then disable itself
(enabled=false). This is rendered on UIs as a "Run Once" option.

Default: run every day, that is, array of 7 trues

143 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

mark string
required
Event which serves as the benchmark for the daily relative time. Options are:

• midnight : seconds is the time in seconds since midnight in the timezone speci�ed by the sys/
time endpoint.
• sunrise : seconds is seconds before or after local sunrise, as calculated using the Grid Locator
(see sys/time endpoint).
• sunset : like sunrise but when the sun goes down!
• dawn : seconds is seconds before or after local civil dawn: that is, when it gets light outside before
sunrise. This is when sun is 6 degrees below the horizon.
• dusk : like dawn, but for civil dusk: when it actually gets dark some time after sunset, when the sun
has descending 6 degrees below the horizon.

For our beloved customers near or within the Arctic Circle: please note that there will be periods of days
around the solstices that schedules based on the solar marks will not execute.

Responses

— 200 Device Schedule modi�ed

400 Bad request

401 Unauthorized

404 Not Found

500 Internal Server Error

144 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/devices/{device_id}/skeds/{sked_id}

Request samples

Payload

Copy Expand all Collapse all

{
"enabled": true,
"action": "SetBrightness",
"argument": 80,
"seconds": -3600,
- "days_of_week": [
false,
true,
true,
true,
true,
true,
false
],
"mark": "sunset"
}

Response samples

145 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

400 401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

Deletes speci�ed Device Schedule. Naturally, the Device Schedule will be canceled.

PATH PARAMETERS

device_id
string
required

sked_id
string
required

Responses

— 204 Device Schedule deleted

146 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/devices/{device_id}/skeds/{sked_id}

Response samples

401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

147 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Returns a list of sked_ids and the corresponding sked hashes. Please see the "Hash Tree" documentation for an explanation of hashes.

PATH PARAMETERS

group_id
string
required

Responses

200 Group Schedule list returned

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/groups/{group_id}/skeds

Response samples

148 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

200 401 404 500

Copy Expand all Collapse all

{
"_": "7fc1e84b",
- "3b20f300": {
"_": "9a5e1136"
},
- "4ad874d2": {
"_": "84819a9f"
},
- "a94328bc": {
"_": "23141efa"
},
- "d87d6ef2": {
"_": "2425a8bc"
}
}

Creates a Group Schedule under a speci�c Group.

If the timezone or location settings in sys/time are not set, a 400 error may result depending on what mark is requested. Speci�cally, the

149 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

following requests will result in an 400 error:

• POSTed mark is midnight but sys/time.tz is null

• POSTed mark is dawn , dusk , sunrise , or sunset , but sys/time.grid is null

PATH PARAMETERS

group_id
string
required

REQUEST BODY SCHEMA: application/json

enabled boolean
If false, schedule will never execute, but will remain in device database.

Oneshot schedules (with days_of_week all False) automatically disable after executing once.

Defaults to true on PUT and POST.

action string
required
Action which will be run on device when schedule executes. If action requires an argument, argument
�eld is required.

argument any
Argument to action, if needed.

seconds integer
required
Time at which schedule should execute, relative to mark , in seconds. Negative numbers indicate "before"
the mark, positive numbers indicate "after" the mark.

days_of_week Array of booleans

required
Days of week on which the schedule should execute.

First element is for Sunday, last element is for Saturday.

150 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

The example value is for a schedules that executes only on weekdays.

Special case: if array is all false , the sked will run exactly once and will then disable itself
(enabled=false). This is rendered on UIs as a "Run Once" option.

Default: run every day, that is, array of 7 trues

mark string
required
Event which serves as the benchmark for the daily relative time. Options are:

• midnight : seconds is the time in seconds since midnight in the timezone speci�ed by the sys/
time endpoint.
• sunrise : seconds is seconds before or after local sunrise, as calculated using the Grid Locator
(see sys/time endpoint).
• sunset : like sunrise but when the sun goes down!
• dawn : seconds is seconds before or after local civil dawn: that is, when it gets light outside before
sunrise. This is when sun is 6 degrees below the horizon.
• dusk : like dawn, but for civil dusk: when it actually gets dark some time after sunset, when the sun
has descending 6 degrees below the horizon.

For our beloved customers near or within the Arctic Circle: please note that there will be periods of days
around the solstices that schedules based on the solar marks will not execute.

Responses

201 Resource Created

400 Bad request

401 Unauthorized

151 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

500 Internal Server Error

/v2/groups/{group_id}/skeds

Request samples

Payload

Copy Expand all Collapse all

{
"enabled": true,
"action": "SetBrightness",
"argument": 80,
"seconds": -3600,
- "days_of_week": [
false,
true,
true,
true,
true,
true,
false
],
"mark": "sunset"

152 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Response samples

201 400 401 500

Copy
{
"_id": "01234567"
}

Get information about a Group Schedule.

PATH PARAMETERS

group_id
string
required

sked_id
string
required

153 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

200 Group Schedule object returned

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/groups/{group_id}/skeds/{sked_id}

Response samples

200 401 404 500

Copy Expand all Collapse all

{
"enabled": true,
"action": "SetBrightness",
"argument": 80,
"seconds": -3600,

154 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

- "days_of_week": [
false,
true,
true,
true,
true,
true,
false
],
"mark": "sunset"
}

Modi�es any �elds of an existing Group Schedule.

PATH PARAMETERS

group_id
string
required

sked_id
string
required

REQUEST BODY SCHEMA: application/json

enabled boolean
If false, schedule will never execute, but will remain in device database.

155 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Oneshot schedules (with days_of_week all False) automatically disable after executing once.

Defaults to true on PUT and POST.

action string
required
Action which will be run on device when schedule executes. If action requires an argument, argument
�eld is required.

argument any
Argument to action, if needed.

seconds integer
required
Time at which schedule should execute, relative to mark , in seconds. Negative numbers indicate "before"
the mark, positive numbers indicate "after" the mark.

days_of_week Array of booleans

required
Days of week on which the schedule should execute.

First element is for Sunday, last element is for Saturday.

The example value is for a schedules that executes only on weekdays.

Special case: if array is all false , the sked will run exactly once and will then disable itself
(enabled=false). This is rendered on UIs as a "Run Once" option.

Default: run every day, that is, array of 7 trues

mark string
required
Event which serves as the benchmark for the daily relative time. Options are:

• midnight : seconds is the time in seconds since midnight in the timezone speci�ed by the sys/
time endpoint.
• sunrise : seconds is seconds before or after local sunrise, as calculated using the Grid Locator
(see sys/time endpoint).
• sunset : like sunrise but when the sun goes down!

156 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

• dawn : seconds is seconds before or after local civil dawn: that is, when it gets light outside before
sunrise. This is when sun is 6 degrees below the horizon.
• dusk : like dawn, but for civil dusk: when it actually gets dark some time after sunset, when the sun
has descending 6 degrees below the horizon.

For our beloved customers near or within the Arctic Circle: please note that there will be periods of days
around the solstices that schedules based on the solar marks will not execute.

Responses

— 200 Group Schedule modi�ed

400 Bad request

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/groups/{group_id}/skeds/{sked_id}

Request samples

Payload

157 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy Expand all Collapse all

{
"enabled": true,
"action": "SetBrightness",
"argument": 80,
"seconds": -3600,
- "days_of_week": [
false,
true,
true,
true,
true,
true,
false
],
"mark": "sunset"
}

Response samples

400 401 404 500

Copy
{

158 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

159 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Deletes speci�ed Group Schedule. Naturally, the Group Schedule will be canceled.

PATH PARAMETERS

group_id
string
required

sked_id
string
required

Responses

— 204 Group Schedule deleted

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/groups/{group_id}/skeds/{sked_id}

160 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Response samples

401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

Adds a Sidekick by ID. The Sidekick ID shall be speci�ed by client in the _id �eld of POST request body. The newly created resource can be
found at sidekicks/{sk_id} where sk_id is the ID provided in _id .

REQUEST BODY SCHEMA: application/json

161 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

_id string
Provided only on POST request to specify the Sidekick ID.

name string
Name of Sidekick on Bond Home app and suggested name for control system integrations.

location string
Location of Sidekick.

chan_links object
Object describes every link between channels of this Sidekick and the devices which they control. (In
future will permit specifying group instead of device .)

Each channel number maps to an array, each element of which is called a "channel link". Each link has two
�elds:

• device : device id channel is linked to

• direct :
◦ 0 = channel con�gured for relay
◦ 1 = channel con�gured for correct direct technology
◦ -1 = channel con�gured for incorrect direct technology, Bridge will relay signal.

Note that there are valid circumstances where direct �eld is -1. For example, a channel may be linked
to an RTS motor and an ARC motor. The user can only pick a single direct technology, for example RTS.
The ARC motor will then be in the -1 case.

key_links object
Object describes every link between key events from this Sidekick and the device, group, and scene
actions which they trigger. (In future will permit specifying group or scene instead of device .)

Each key number maps to an array, each element of which is called a "key link". Each key link has three or
four �elds:

• event : which key event to trigger on

162 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

◦ TAP
◦ DOUBLE_TAP
◦ HOLD_START
◦ HOLD
◦ HOLD_END
• device : which device will act in response to trigger
• action : action to call on device
• argument : (optional) argument to above action, such as position percentage

Responses

201 Resource Created

400 Bad request

401 Unauthorized

500 Internal Server Error

/v2/sidekicks

Request samples

Payload

163 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy Expand all Collapse all

{
"_id": "SNAXX12345",
"name": "My Sidekick",
"location": "My Room",
- "chan_links": {
+ "1": [ … ],
"2": [ ],
"3": [ ],
"4": [ ],
"5": [ ]
},
- "key_links": {
"1": [ ],
+ "2": [ … ],
"3": [ ]
}
}

Response samples

201 400 401 500

Copy

164 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"_id": "01234567"
}

Get information about a Sidekick.

PATH PARAMETERS

sk_id
string
required

Responses

200 Sidekick object returned

401 Unauthorized

404 Not Found

500 Internal Server Error

165 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/sidekicks/{sk_id}

Response samples

200 401 404 500

Copy Expand all Collapse all

{
"name": "My Sidekick",
"location": "My Room",
"keys": 3,
"chans": 5,
- "chan_links": {
+ "1": [ … ],
"2": [ ],
"3": [ ],
"4": [ ],
"5": [ ]
},
- "key_links": {
"1": [ ],
+ "2": [ … ],
"3": [ ]
},
"signal": 97,
"battery": 80,

166 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"model": "SKN-386"
}

Modi�es metadata and/or links of a Sidekick. The chan_link �eld has complex PATCH logic allowing adding, modifying, and deleting links.
Example·s:

Please note, in the following examples, we abbreviate. Be sure to add double-quotes around strings for correct JSON, especially the channel
and key numbers which must be strings by JSON standard.

Adding a Link

Assume we start with nothing linked:

chan_links:{ 1:[], 2:[], 3:[], 4:[], 5:[] }

Now let's add a link to channel 4:

PATCH {chan_links={4:[{device=abcdef0abcdef0}]}
→ chan_links : { 1:[], 2:[], 3:[], 4:[{device=abcdef0abcdef0, direct=1}], 5:[] }

Note how the direct �eld is populated based on the channel technology and the technology of the linked device. This is not modifyable
from the API. Users need to manually change channel technology via Sidekick's menu codes if needed.

And now let's add another link to the same channel:

PATCH {chan_links={4:[{}, {device=1122334400000000}]}

→ chan_links : { 1:[], 2:[], 3:[], 4:[{device=abcdef0abcdef0, direct=1}, {device=1122334400000000, direct=0}], 5:[]}

Note that we do not need to pass the previous device ID, instead using an empty object as a placeholder for the link in the array which we want
to leave alone.

167 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Multiple new links can be added in a single PATCH by specifying more than one additional element in the array. Links can even be added for
multiple channels, for example:

PATCH {chan_links={1:[{device=aaaaaaaa}], 2:[{device=bbbbbbbb}]}} → chan_links : { 1:[{device=aaaaaaaa}], 2:[{device=bbbbbbbb}], 3:[],

4:[{device=1234567aabbccdd, direct=1}, {device=1122334400000000, direct=0}], 5:[]}

Deleting Links

To delete a link, put a null in the array location(s) which you want to remove.

PATCH {chan_links={4:[null, {}]}} → chan_links : { 1:[], 2:[], 3:[], 4:[{device=1122334400000000, direct=0}, {device=1234567aabbccdd,
direct=1}], 5:[]}

Be sure to specify the correct number of array elements. In the above, it would be an error to just patch [null] ; you must send [null,
{}] to delete the �rst element but preserve the second element. To delete both elements, you could send [null, null] .

You can also delete links from multiple channels at once:

PATCH {chan_links={1:[null], 2:[null]} → chan_links : { 1:[], 2:[], 3:[], 4:[{device=1122334400000000, direct=0}], 5:[]}

Editing a Link

You can edit a link to change the device ID:

PATCH {chan_links={4:[{device=1234567aabbccdd}, {}]}}

→ chan_links : { 1:[], 2:[], 3:[], 4:[{device=1234567aabbccdd, direct=1}, {device=1122334400000000, direct=0}], 5:[]}

Be sure to specify the exact number of elements in the channel array being modi�ed. In the above example, we still need {} for the second
link as a placeholder.

It is possible to mix adding, editing, and deleting links in a single PATCH request.

PATH PARAMETERS

sk_id
string
required

168 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

REQUEST BODY SCHEMA: application/json

_id string
Provided only on POST request to specify the Sidekick ID.

name string
Name of Sidekick on Bond Home app and suggested name for control system integrations.

location string
Location of Sidekick.

chan_links object
Object describes every link between channels of this Sidekick and the devices which they control. (In
future will permit specifying group instead of device .)

Each channel number maps to an array, each element of which is called a "channel link". Each link has two
�elds:

• device : device id channel is linked to

• direct :
◦ 0 = channel con�gured for relay
◦ 1 = channel con�gured for correct direct technology
◦ -1 = channel con�gured for incorrect direct technology, Bridge will relay signal.

Note that there are valid circumstances where direct �eld is -1. For example, a channel may be linked
to an RTS motor and an ARC motor. The user can only pick a single direct technology, for example RTS.
The ARC motor will then be in the -1 case.

key_links object
Object describes every link between key events from this Sidekick and the device, group, and scene
actions which they trigger. (In future will permit specifying group or scene instead of device .)

Each key number maps to an array, each element of which is called a "key link". Each key link has three or
four �elds:

169 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

• event : which key event to trigger on

◦ TAP
◦ DOUBLE_TAP
◦ HOLD_START
◦ HOLD
◦ HOLD_END
• device : which device will act in response to trigger
• action : action to call on device
• argument : (optional) argument to above action, such as position percentage

Responses

— 200 Sidekick modi�ed

400 Bad request

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/sidekicks/{sk_id}

170 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Request samples

Payload

Copy Expand all Collapse all

{
"_id": "SNAXX12345",
"name": "My Sidekick",
"location": "My Room",
- "chan_links": {
+ "1": [ … ],
"2": [ ],
"3": [ ],
"4": [ ],
"5": [ ]
},
- "key_links": {
"1": [ ],
+ "2": [ … ],
"3": [ ]
}
}

Response samples

400 401 404 500

171 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

Deletes speci�ed Sidekick.

PATH PARAMETERS

sk_id
string
required

Responses

— 204 Sidekick deleted

401 Unauthorized

404 Not Found

172 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

500 Internal Server Error

/v2/sidekicks/{sk_id}

Response samples

401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

173 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

[BBP-only]

Provides information about the Sidekick learn window on this Bond.

When the learn window is open, the Bond will listen for a link intent. Speci�cally, it listens for a BondSync message of type LINK or type
KEYSTREAM with HOLD event and duration greater than 2 seconds.

[New in v3.10]

PATH PARAMETERS

sk_id
string
required

Responses

200 Get Sidekick learn status

401 Unauthorized

404 Not Found

500 Internal Server Error

174 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/sidekicks/_learn

Response samples

200 401 404 500

Copy
{
"learn_window_ms": 60000,
"learn_window_remaining_ms": 1100,
"learn_window_open": true,
"learn_count": 0
}

[BBP-only] Open/close the learn window.

The learn window is never automatically opened. Must be opened by API.

PATH PARAMETERS

175 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

sk_id
string
required

REQUEST BODY SCHEMA: application/json

learn_window_open boolean
Whether new Sidekick can be learned. True iff learn_window_remaining_ms is nonzero.

Responses

200 Open or close Sidekick learn window

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/sidekicks/_learn

Request samples

Payload

176 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"learn_window_open": true
}

Response samples

200 401 404 500

Copy
{
"learn_window_ms": 60000,
"learn_window_remaining_ms": 1100,
"learn_window_open": true,
"learn_count": 0
}

Close the learn window. Identical to PATCH learn_window_open=false.

177 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

PATH PARAMETERS

sk_id
string
required

Responses

200 Learn window closed.

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/sidekicks/_learn

Response samples

200 401 404 500

Copy

178 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"learn_window_ms": 60000,
"learn_window_remaining_ms": 1100,
"learn_window_open": true,
"learn_count": 0
}

This endpoint is pushed whenever a new key event occurs on the corresponding Sidekick. This is only intended to be used via BPUP and/or
MQTT. GET requests via HTTP will only ever return 204 No Content.

PATH PARAMETERS

sk_id
string
required

Responses

179 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

200 Keystream object

— 204 No content, only available via BPUP.

401 Unauthorized

404 Not Found

500 Internal Server Error

180 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/sidekicks/{sk_id}/keystream

Response samples

200 401 404 500

Copy
{
"seq": 3210,
"event": "TAP",
"key": 3,
"hold_ms": 1760
}

181 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

AUTHORIZATIONS: None

Responses

200 Get Bridge info

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/bridge

Response samples

200 401 404 500

Copy Expand all Collapse all

{
"location": "My Room",
"name": "My Bridge",

182 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"bluelight": 127,
- "frequencies": [
+ [ … ],
+ [ … ]
]
}

AUTHORIZATIONS: None

REQUEST BODY SCHEMA: application/json

location string

name string

bluelight integer
Amount of blue light emitted from the Bond when it's idle: at 0 the light is off, and at 255 the light is at
its maximum brightness.

Responses

200 Change Bridge info

401 Unauthorized

183 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

404 Not Found

500 Internal Server Error

/v2/bridge

Request samples

Payload

Copy
{
"location": "My Room",
"name": "My Bridge",
"bluelight": 127
}

Response samples

200 401 404 500

184 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy Expand all Collapse all

{
"location": "My Room",
"name": "My Bridge",
"bluelight": 127,
- "frequencies": [
+ [ … ],
+ [ … ]
]
}

After deletion, default values will be restored.

AUTHORIZATIONS: None

Responses

— 204 Reset Bridge info

401 Unauthorized

404 Not Found

185 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

500 Internal Server Error

/v2/bridge

Response samples

401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

186 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

If a Signal is being transmitted, it is immediately interrupted, and a 204 is returned.

A 204 is also returned even if there was no Signal being transmitted.

NOTE: Internally, this �ushes the radio command queue, so any requested transmissions which were queued waiting for an earlier tranmission
to complete will also be canceled. This also cancels any queued scans, but does not cancel a scan already in progress.

Responses

— 204 Signal transmission canceled

400 Bad request

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/signal/tx

Response samples

187 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

400 401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

Transmit an RF or IR signal from a Bond Bridge.

If use_scan is present and true, the signal recorded by the previous scan will be used, and all other �elds will be ignored

REQUEST BODY SCHEMA: application/json

freq number
required
Frequency in kHz:

• >= 1000 is RF
• < 1000 is IR

Bond Bridge can only receive IR signals at or near 38 kHz, and will report all IR signals as 38 kHz.

Bond Bridge currently transmits all IR signals at 38 kHz also.

188 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

modulation string
• OOK = on-off keying
• GFSK = gaussian frequency-shift keying

If not provided, defaults to OOK .

data string
required
String representation of data bits to be transmitted.

The maximum length of the data string is 6144 bytes.

encoding string
required
Speci�es the encoding of the data string.

In all cases, the duration of each bit is 1/ bps seconds.

CQ encoding ( "cq" )

This is a simple encoding where bits are represented using 0 and 1 , with some abbreviations for
sequences of bits.

Each character represents one or more bits:

• 0 single zero bit

• 1 single one bit
• C 2^0 (1) zero bits
• D 2^1 (2) zero bits
• E 2^2 (4) zero bits
• F 2^3 (8) zero bits
• ...
• Q 2^14 (16384) zero bits
• c thru q are just like C thru Q , but for one bits
• A the three bits 110
• B the three bits 011

189 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Hex ( "hex" )

This is a simple encoding where the data string consists of hex bytes. Each hex byte represents 8 bits of
data.

Hex encoding is currently limited to only work at 40000 bps.

This is the default encoding for scan results.

bps number
required
Bitrate of data . Range is 100 to 40000.

reps number
Number of times that data should be repeated.

If not provided, 1 is assumed.

use_scan boolean
If present and true, the Signal recorded by the most recent scan will be used, with all other �elds ignored

Responses

— 204 Signal transmit started

400 Bad request

401 Unauthorized

500 Internal Server Error

190 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/signal/tx

Request samples

Payload

Copy
{
"freq": 434000,
"modulation": "OOK",
"data": "110100110110H",
"encoding": "cq",
"bps": 1000,
"reps": 12,
"use_scan": true
}

Response samples

400 401 500

Copy

191 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

Start scanning for RF/IR signals.

REQUEST BODY SCHEMA: application/json

freq number
Frequency to scan in kHz.

If not provided, scan will search all RF frequencies, but not IR.

Specify 38 to explicitly scan IR.

modulation string
• OOK = on-off keying
• GFSK = gaussian frequency-shift keying

192 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

If not provided, defaults to OOK .

Only applicable to RF.

(GFSK scanning currently unimplemented.)

Responses

— 201 Signal transmit started

400 Bad request

401 Unauthorized

500 Internal Server Error

/v2/signal/scan

Request samples

Payload

Copy

193 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"freq": 434000,
"modulation": "OOK"
}

Response samples

400 401 500

Copy
{
"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

Get information about a scan in progress, or the last completed scan.

Responses

200 Scan info returned

194 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/signal/scan

Response samples

200 401 404 500

Copy
{
"freq": 434000,
"modulation": "OOK",
"running": false,
"total_timeout": 30,
"success": true
}

195 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Immediately stop scanning, and delete results.

Responses

— 204 Scan canceled

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/signal/scan

Response samples

401 404 500

Copy

196 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

197 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Get the signal resulting from the most recent scan

Responses

200 Signal resulting from scan

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/signal/scan/signal

Response samples

200 401 404 500

Copy

198 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"freq": 434000,
"modulation": "OOK",
"data": "110100110110H",
"encoding": "cq",
"bps": 1000,
"reps": 12
}

Sweeps over the frequency range supported by the product, and returns a list of frequency-rssi ordered pairs.

This is useful for determining tuning of antennas.

Responses

200 Receive Signal Strength

199 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/signal/rssi

Response samples

200 401 404 500

200 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy Expand all Collapse all

{
- "format": [
"freq",
"rssi"
],
- "results": [
+ [ … ],
+ [ … ],
+ [ … ]
]
}

Request token for accessing Bond over local network.

If locked is true, reply will contain neither token nor account_code .

201 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Typical use case for this endpoint is:

• request GET, �nding that the endpoint is locked

• perform PATCH with "locked": 0 , the correct pin , and your account_code (if you want to take ownership of the Bond)
• request GET again to get token
• perform PATCH with "locked": 1

Alternatively, user may perform the proof-of-ownership event (such as holding down the Power button on a SBB remote for 5 sec), which will
unlock the endpoint. In that case, the API client should poll GET waiting for unlock.

Lastly, this endpoint is unlocked for 10 minutes following power cycle.

Note: The token is not required for /sys/version and /token endpoints. However, all other endpoints require token to be provided in a BOND-
Token HTTP header.

Responses

200 Local token status

401 Unauthorized

/v2/token

Response samples

200 401

202 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"locked": 0,
"token": "8f514567acaf9869",
"account_code": "1234567890",
"nonce": "876a2b14c55b3e5a",
"pin_attempts_left": 9,
"disable": false
}

If locked, provide pin (located on the product label) to unlock this endpoint. If pin is not provided or incorrect, a 401 will be returned.

If an account_code is provided, saves it to the Bond. When the Bond communicates with the backend, the Bond will be added to the
account associated with account_code . You can �nd your account_code on the user screen in the mobile app.

You can also use this endpoint to simply �nd out your Bond's locked token by providing a pin

REQUEST BODY SCHEMA: application/json

203 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

locked integer
If 1, means that the client wants to immediately re-lock this endpoint.

If 0, means that the client wants to unlock the endpoint.

account_code string
10-digit account code, used to specify which account to associate the Bond with.

(Absolute maximum for this �eld is 16 alpha-numeric characters)

This does NOT include any checksum digits which may be added when displayed for the customer in the
app, and required by the Bond WebGUI to eliminate typo issues.

pin string
Pin number, if required, as part of unlocking procedure.

disable boolean
If disabled, HTTP and other local APIs will not require token to function. Only disable on trusted networks,
and only when using �xed IP addresses to avoid controlling the wrong Bond. Defaults to false, i.e., token
required by default.

Responses

200 Token unlocked

400 Bad request

401 Unauthorized

500 Internal Server Error

204 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/token

Request samples

Payload

Copy
{
"locked": 0,
"account_code": "1234567890",
"pin": "1234",
"disable": false
}

Response samples

200 400 401 500

Copy
{
"locked": 0,

205 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"account_code": "1234567890",
"pin": "1234",
"disable": false
}

IMPORTANT NOTE: MQTT redirection is currently untested. If you have a use case for this API, please let us know on the forums so that we
can better prioritize implementing this API.

Con�gure the Bond's MQTT Transport, which is used for communication with the Bond Cloud or an o�ine MQTT broker. Note that Bond uses
MQTT over TLS with certi�cate-based authentication. Password-based authentication is not supported.

Some advanced users may elect to run their own MQTT brokers, so this endpoint allows customizing of the MQTT broker address and the
various related security settings.

Note that any manipulation of this endpoint will result in the Bond disconnecting from Bond Cloud, and therefore integrations and control
away from home will become unavailable.

NOTE: All settings only take effect after reboot.

AUTHORIZATIONS: None

206 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

REQUEST BODY SCHEMA: application/json

host string
IP address or domain name of the MQTT broker. If set to empty string, the default Bond Cloud server will
be used.

port number
Specify a different port number for the MQTT broker. If set to 0, the Bond Cloud default port number will be
used (8883). Note that the communication is secured by TLS (SSL).

cert string
Specify a custom Bond certi�cate. Typically, this is the Bond-speci�c certi�cate concatenated with the
Bond-signing CA certi�cate. Write to empty string to go back to the Bond's default certi�cate.

key string
Specify a custom Bond private key. Write to empty string to go back to the Bond's default private key.

enabled boolean
[Added in v3.3.3] If true (default), Bond will attempt MQTT connection. If MQTT connection fails, Bond
becomes discoverable again via Con�g AP. If false, Bond will not attempt MQTT connection and Con�g AP
will remain deactivated.

server_cert string
Specify a custom MQTT server CA. Set to empty string to return to default.

server_cert_check boolean
Set to false to disable veri�cation of the MQTT server CA. It is strongly recommend to leave this option
enabled, because otherwise a man-in-the-middle attack is possible.

Responses

207 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

— 200 MQTT Recon�gured

401 Unauthorized

500 Internal Server Error

/v2/api/mqtt

Request samples

Payload

Copy
{
"host": "my-mqtt-server.myhome.com",
"port": 8883,
"cert": "certificate_goes_here",
"key": "key_goes_here",
"enabled": true,
"server_cert": "certificate_goes_here",
"server_cert_check": true
}

Response samples

208 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

401 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

209 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

AUTHORIZATIONS: None

Responses

200 MQTT Con�guration

— 204 No custom MQTT con�guration found

401 Unauthorized

500 Internal Server Error

/v2/api/mqtt

Response samples

200 401 500

Copy

210 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"host": "my-mqtt-server.myhome.com",
"port": 8883,
"cert_set": true,
"key_set": true,
"server_cert_set": true,
"enabled": true,
"server_cert_check": true
}

AUTHORIZATIONS: None

Responses

— 204 MQTT con�g reset to default

401 Unauthorized

500 Internal Server Error

211 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/api/mqtt

Response samples

401 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

Con�gure the Bond's BPUP transport.

212 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

AUTHORIZATIONS: None

REQUEST BODY SCHEMA: application/json

broadcast boolean
If true, the Bond will broadcast all state updates on port 30007 (disabled by default)

Responses

— 200 BPUP Recon�gured

401 Unauthorized

500 Internal Server Error

/v2/api/bpup

Request samples

Payload

Copy

213 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"broadcast": true
}

Response samples

401 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

AUTHORIZATIONS: None

Responses

200 BPUP Con�guration

214 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

401 Unauthorized

500 Internal Server Error

/v2/api/bpup

Response samples

200 401 500

Copy
{
"broadcast": true
}

AUTHORIZATIONS: None

215 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

— 204 BPUP con�g reset to default

401 Unauthorized

500 Internal Server Error

/v2/api/bpup

Response samples

401 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

216 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

AUTHORIZATIONS: None

Responses

200 Bond HomeKit con�guration.

401 Unauthorized

500 Internal Server Error

/v2/api/bhk

Response samples

217 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

200 401 500

Copy
{
"enabled": false,
"paired": false,
"setup_code": "12341234"
}

AUTHORIZATIONS: None

REQUEST BODY SCHEMA: application/json

enabled boolean
• false : HomeKit logic and operations will not be executed. All settings remains in device database.
(default)
• true : HomeKit logic and operations will run.

Responses

218 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

— 200 Bond HomeKit enabled info updated.

400 Bad request

401 Unauthorized

500 Internal Server Error

/v2/api/bhk

Request samples

Payload

Copy
{
"enabled": false
}

Response samples

400 401 500

219 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

AUTHORIZATIONS: None

Responses

— 204
Bond HomeKit info reseted. That means the Bond will delete all info, unpairing if paired and set enabled to default (0). If you have not removed the
Bond from your account on Home app, the Bond and its devices will show as not responding. You can remove from the Home app later as usual.

401 Unauthorized

500 Internal Server Error

220 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/api/bhk

Response samples

401 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

A GET request starts a new Wi-Fi network scan (unless a scan is already in progress), and returns the results of the most recently completed

221 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

scan. It is not an error for scan to be called before the scan has completed; however, the old results will be returned. A 204 is returned if no
scan has been run yet since boot.

The results are returned as a nested JSON array (a 2D table) rather than a JSON object for compactness. The format array gives the
meaning of each column of the results table.

The ssid �eld contains the network name. It is base64-encoded because arbitrary characters are allowed by the Wi-Fi standard.

The auth �eld gives the type of network security:

• 0 = unsecured (open)
• 1 = WEP
• 2 = WPA PSK
• 3 = WPA2 PSK
• 4 = WPA/WPA2 PSK
• 5 = WPA2 Enterprise [currently unsupported by Bond]

Note that for auth types 0 and 1, the application should warn the user that the network could be more secure, and should be set to WPA2 for
best security.

The signal �eld contains an indication of access point signal quality (which may be derived from signal strength and/or signal-to-noise
ratio), ranging from 0 to 100.

If hidden_requires_bssid is present and true, and the user wants to connect to a hidden network, the user must supply the BSSID (that is,
the MAC address of the access point).

AUTHORIZATIONS: None

Responses

200 Scan results

222 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

— 204 No results available yet

401 Unauthorized

500 Internal Server Error

/v2/sys/wifi/scan

Response samples

200 401 500

Copy Expand all Collapse all

{
"hidden_requires_bssid": true,
- "format": [
"ssid",
"bssid",
"auth",
"ch",
"signal"
],

223 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

- "results": [
+ [ … ],
+ [ … ],
+ [ … ],
+ [ … ],
+ [ … ],
+ [ … ],
+ [ … ],
+ [ … ],
+ [ … ],
+ [ … ],
+ [ … ],
+ [ … ],
+ [ … ],
+ [ … ]
]
}

224 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Get the name (base64-encoded in ssid ) of the Wi-Fi network to which the Bond is currently connected.

A numerical status �eld is also provided (see details below).

The BSSID of the network's access point is provided, hex-encoded in bssid . If bssid_set is present and true , then the Bond has been
con�gured to only connect to an access point with a speci�c BSSID, speci�ed in an earlier PUT.

The MAC address of the Bond is also provided, hex-encoded in mac . If this MAC address is not available, it will be null .

Some network con�guration �elds are returned: the Bond's IP address ( ip ), its default gateway ( gw ), its netmask ( netmask ), and its DNS
and fallback DNS ( dns and dns_alt ). static_ip_set is present and true if a previous PUT has con�gured the Bond to use static
values for these �eld. dns_set and dns_alt_set are present and true if an earlier PUT has con�gured the DNS used by the Bond.

AUTHORIZATIONS: None

Responses

200 Current Wi-Fi settings

401 Unauthorized

/v2/sys/wifi/sta

Response samples

200 401

225 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"status": 2,
"ssid": "bGlua3N5cw==",
"bssid": "001122334455",
"bssid_set": true,
"mac": "30aea48fa8e8",
"static_ip_set": false,
"ip": "192.168.1.42",
"gw": "192.168.1.1",
"netmask": "255.255.255.0",
"dns_set": true,
"dns": "8.8.8.8",
"dns_alt": "8.8.4.4"
}

For compatibility reasons, the PATCH endpoint can also be accessed using the PUT method.

Instruct the Bond to connect to the network speci�ed.

The Bond immediately saves the settings in non-volatile storage, and therefore the settings will persist even after power cycle.

The network name must be speci�ed in ssid (base64-encoded). A password (again base64-encoded) is required unless it is an unsecured

226 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

(open) network. The required security type (WEP/WPA/WPA2) is automatically determined by the Bond.

For DNS, Bond always tries default DNS servers �rst. However, our chosen DNS servers are blocked on some networks, so Bond will fall back
to DNS servers provided by DHCP or speci�ed by dns and dns_alt . If dns or dns_alt are provided, Bond will ignore any DNS servers
proposed by DHCP. This behavior was decided upon after many customer service interactions which revealed an epidemic of bad ISP DNS
servers which prevent what we originally though was reasonable: respecting the DHCP-provided servers by default.

If bssid is present, the Bond will only connect to an access point with the supplied, hex-encoded BSSID.

AUTHORIZATIONS: None

REQUEST BODY SCHEMA: application/json

status number
Indication of whether the Wi-Fi settings have been successful:

• -4 = Wi-Fi not con�gured

• -3 = disabled because Ethernet is selected
• -2 = authentication failure
• -1 = network not found
• 0 = attempting to connect
• 1 = connected, but no IP address yet
• 2 = connected with IP address assigned
• 3 = connected to cloud (MQTT)

ssid string or null

Can be null if it's not set.

bssid string or null

Can be null if it's not set.

static_ip_set boolean
[changed in v2.16.2] If true on write, the ip, gw, netmask �elds are required. If false on write, the ip, gw,

227 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

netmask �elds will be ignored and DHCP con�gured.

ip string or null
Can be null if it's not connected.

gw string or null
Can be null if it's not connected.

netmask string or null

Can be null if it's not connected.

dns_set boolean
[changed in v2.16.2] If true on write, the dns and dns_alt �elds are required. If false on write, the dns and
dns_alt �elds will be ignored and the default dns behavior will take effect.

dns string or null

Can be null if it's not connected.

dns_alt string or null

Can be null if it's not connected.

password string or null <password>

Can be null if it's not set.

Responses

200 New Wi-Fi settings

401 Unauthorized

228 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

500 Internal Server Error

/v2/sys/wifi/sta

Request samples

Payload

Copy
{
"status": 2,
"ssid": "bGlua3N5cw==",
"bssid": "001122334455",
"static_ip_set": false,
"ip": "192.168.1.42",
"gw": "192.168.1.1",
"netmask": "255.255.255.0",
"dns_set": true,
"dns": "8.8.8.8",
"dns_alt": "8.8.4.4",
"password": "cGFzc3dvcmQ="
}

Response samples

229 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

200 401 500

Copy
{
"status": 2,
"ssid": "bGlua3N5cw==",
"bssid": "001122334455",
"bssid_set": true,
"mac": "30aea48fa8e8",
"static_ip_set": false,
"ip": "192.168.1.42",
"gw": "192.168.1.1",
"netmask": "255.255.255.0",
"dns_set": true,
"dns": "8.8.8.8",
"dns_alt": "8.8.4.4"
}

The Bond will disconnect from the current Wi-Fi network, and will not attempt to reconnect, even after a power cycle. It will be necessary to
use PUT again to recon�gure Wi-Fi.

AUTHORIZATIONS: None

230 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

— 204 Wi-Fi network disconnected

401 Unauthorized

500 Internal Server Error

/v2/sys/wifi/sta

Response samples

401 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

231 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Note that there are seperate DNS settings for the Ethernet and Wi-Fi interfaces.

AUTHORIZATIONS: None

Responses

200 Current Etherent settings

401 Unauthorized

— 404 Ethernet unsupported on this product.

/v2/sys/eth

232 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Response samples

200 401

Copy
{
"status": 2,
"mac": "30aea48fa8e8",
"static_ip_set": false,
"ip": "192.168.1.42",
"gw": "192.168.1.1",
"netmask": "255.255.255.0",
"dns_set": true,
"dns": "8.8.8.8",
"dns_alt": "8.8.4.4"
}

For compatibility reasons, the PATCH endpoint can also be accessed using the deprecated PUT method.

Customize the Ethernet interface.

The Bond immediately saves the settings in non-volatile storage, and therefore the settings will persist even after power cycle.

233 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

For DNS, Bond always tries default DNS servers �rst. However, our chosen DNS servers are blocked on some networks, so Bond will fall back
to DNS servers provided by DHCP or speci�ed by dns and dns_alt . If dns or dns_alt are provided, Bond will ignore any DNS servers
proposed by DHCP. This behavior was decided upon after many customer service interactions which revealed an epidemic of bad ISP DNS
servers which prevent what we originally though was reasonable: respecting the DHCP-provided servers by default.

AUTHORIZATIONS: None

REQUEST BODY SCHEMA: application/json

status number
• 0 = no link
• 1 = link, but no IP address yet
• 2 = link and IP address assigned
• 3 = connected to cloud (MQTT)

static_ip_set boolean
[changed in v2.16.2] If true on write, the ip, gw, netmask �elds are required. If false on write, the ip, gw,
netmask �elds will be ignored and DHCP con�gured.

ip string

gw string

netmask string

dns_set boolean
[changed in v2.16.2] If true on write, the dns and dns_alt �elds are required. If false on write, the dns and
dns_alt �elds will be ignored and the default dns behavior will take effect.

dns string

dns_alt string

234 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

200 Ethernet settings updated

401 Unauthorized

500 Internal Server Error

/v2/sys/eth

Request samples

Payload

Copy
{
"status": 2,
"static_ip_set": false,
"ip": "192.168.1.42",
"gw": "192.168.1.1",
"netmask": "255.255.255.0",
"dns_set": true,

235 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"dns": "8.8.8.8",
"dns_alt": "8.8.4.4"
}

Response samples

200 401 500

Copy
{
"status": 2,
"mac": "30aea48fa8e8",
"static_ip_set": false,
"ip": "192.168.1.42",
"gw": "192.168.1.1",
"netmask": "255.255.255.0",
"dns_set": true,
"dns": "8.8.8.8",
"dns_alt": "8.8.4.4"
}

Bond will clear settings for Ethernet, defaulting to DHCP, DHCP-provided DNS (with fallback to hard-coded DNS servers), and Ethernet being

236 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

preferred over Wi-Fi if both are available.

This will NOT disable the Ethernet port. If the attached network supports DHCP and has an internet connection, the Bond will continue to
function on Ethernet.

AUTHORIZATIONS: None

Responses

— 200 Ethernet settings reset to defaults

401 Unauthorized

500 Internal Server Error

/v2/sys/eth

Response samples

401 500

Copy
{

237 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

AUTHORIZATIONS: None

Responses

200 Network Watchdog settings

401 Unauthorized

500 Internal Server Error

238 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/sys/wifi/watchdog

Response samples

200 401 500

Copy
{
"rwdg_disable": false,
"rwdg_timer_ms": 60000
}

Con�gure the Wi-Fi watchdog, which runs whenever the Wi-Fi station ( sta ) is con�gured.

This watchdog feature is useful on some Wi-Fi networks where the Bond may lose its connection after some period of time.

AUTHORIZATIONS: None

REQUEST BODY SCHEMA: application/json

239 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

rwdg_disable boolean
• true : disable Bond Cloud watchdog
• false : enable Bond Cloud watchdog (default)

If enabled, Bond will reboot if not connected to Bond Cloud within �rst 10 minutes of boot, or if
disconnected for 3 minutes.

Watchdog does not run if Bond is in Wi-Fi Setup mode.

NOTE: Any communication with the Bond over the HTTP transport will reset the timer as if the Bond were
connected to the cloud.

Responses

— 200 Network Watchdog con�g updated

401 Unauthorized

500 Internal Server Error

/v2/sys/wifi/watchdog

Request samples

Payload

240 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"rwdg_disable": false
}

Response samples

401 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

241 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Check the progress of a �rmware upgrade.

Note that when an upgrade completes successfully, this endpoint will return a 204 again. The client should check the sys/version endpoint
to determine whether the new �rmware is being used.

AUTHORIZATIONS: None

Responses

200 Upgrade progress

— 204 No upgrade in progress

401 Unauthorized

/v2/sys/upgrade

Response samples

200 401

242 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"progress": -1,
"error_msg": "net_connect"
}

Instruct the Bond to upgrade to the speci�ed �rmware.

The client may specify both port (HTTPS) and http_port (HTTP). Bond will use whichever protocol is implemented in the �rmware.

During the upgrade, the client SHOULD query GET to monitor progress.

Whether or not the Bond reboots spontaneously at the end of the upgrade process is dependent on the client specifying the reboot parameter.

If spontaneous reboot is requested, Bond will become unreachable for a period of time during the upgrade. When the Bond becomes
reachable again, GET will return 204 No Content, at which time the client should check sys/version to determine whether the upgrade was
successful.

Note that network connection is slow on some networks, especially with Bond Bridge 1st Generation, therefore the client MUST NOT declare
an error until a reasonable timeout period (7 minutes).

Note that network issues may cause the Bond to remain inaccessible despite the update having succeeded. Furthermore, the probability of a
failure of the upgrade mechanism after the reboot step is very low. Therefore the client should represent a timeout in upgrading as a
communication error rather than a �rmware upgrade error.

243 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

In the case that the client did not specify reboot=1, Bond will not reboot spontaneously and the progress indication will reach 1000 and remain
there until the client issues an explicit reboot (via sys/reboot). Afterwards the client can con�rm �rmware upgrade success by checking
version as usual.

AUTHORIZATIONS: None

REQUEST BODY SCHEMA: application/json

host string
required
Fully-Quali�ed Domain Name or IP address of server from which to download upgrade

port string
required
HTTPS port number of server. Used only if sys/version is missing key upgrade_http , or the key is
false.

http_port string
HTTP port number of server. Used only if sys/version contains true value for upgrade_http .

path string
required
Path of HTTPS URL to use to fetch the �rmware binary. Must not include any query or fragment. Must start
with a forward slash.

Note that only HTTPS is supported. Other protocols (including unsecured HTTP) are not supported.

info string
required
Firmware info string, consisting of SHA-256 hash of the �rmware binary, �rmware target, and new
�rmware version number.

The hash is checked after �rmware is downloaded and before it is written to �ash, to ensure integrity and
security.

sig string
required
Digital signature of info string, signed using Olibra's private key, and base-64 encoded. Note that, as a
security precaution, different key-pair is used for each �rmware target. The API client does not need to

244 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

worry about the key-pairs, but only be capable of providing the appropriate info and sig �elds that
correspond to a particular �rmware binary. This metadata is available in release notes from Olibra.

The Bond validates this signature before the �rmware update is completed.

reboot number
If non-zero, requests that the Bond reboot spontaneously upon successful completion of the upgrade
installation.

If zero, the Bond will wait for an explicit reboot via sys/reboot.

Defaults to zero.

Responses

200 Progress of newly started upgrade

400 Bad request

401 Unauthorized

— 409 Upgrade already in progress

500 Internal Server Error

/v2/sys/upgrade

245 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Request samples

Payload

Copy
{
"host": "s3.amazonaws.com",
"port": "443",
"http_port": "80",
"path": "/bond-updates/breck-mach1-v2.0.bin",
"info": "cc8d372f1b1ada5b99097e46f9d45107487e5f8b000d5ccd943100b3dc27fb55:bond-simulator:v2.0",
"sig": "PAGliMxpwYYkuG+48JDu6rYfF9V57xXGNy2xf8yXCoo2Gcdk8plHrez2bPWkL8TZ5ptaZBPE9UuQf8wx9nkQswBoX413GHnQhBmyX0n/DihqQCG5rR7o3dZWh
"reboot": 1
}

Response samples

200 400 401 500

246 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"progress": -1,
"error_msg": "net_connect"
}

The Bond will cancel any �rmware upgrade in progress.

Canceling a �rmware upgrade is always safe.

However, power cycling a Bond during a �rmware upgrade is not recommended.

AUTHORIZATIONS: None

Responses

— 204 No upgrade in progress (anymore)

401 Unauthorized

247 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

500 Internal Server Error

/v2/sys/upgrade

Response samples

401 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

248 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Get detailed version information about hardware and �rmware.

AUTHORIZATIONS: None

Responses

200 Product verison information

401 Unauthorized

500 Internal Server Error

/v2/sys/version

Response samples

200 401 500

249 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"upgrade_http": true,
"bondid": "KSMJWCE12345",
"target": "zermatt",
"api": 2,
"fw_ver": "v2.9",
"fw_date": "Wed Nov 22 15:45:19 UTC 2020",
"mcu_ver": "v1.234",
"make": "Olibra LLC",
"branding_profile": "BondHome",
"model": "BD-1000"
}

Shows whether a backup or a restore is running, including progress indication, and error messages. After operation completes, the backup
or restore �eld is set to 2 (or -1 in case of error) and the other �elds remain accessible for the client to con�rm operation completion.
Client should DELETE the endpoint after con�rming to return endpoint to empty (204 status).

Note that only one operation can run at once.

250 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

200 Backup status

— 204 No recent Backup/Restore.

/v2/sys/backup

Response samples

200

Copy Expand all Collapse all

{
"host": "192.168.1.107",
"http_port": "80",
"path": "/snapshots",
"timestamp": "1618599782",
"filename": "/ZZDE12345_v2.18.4-alpha_1618599782_0f8d01fa.bsnap",
- "dev_ids": [
"aabbccdd"
],

251 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"backup": 0,
"restore": -1,
"progress": 999,
"error_msg": "connection error"
}

Start a backup or restore operation,

NOTE: A backup will send all devices and associated data (commands, properties, state, skeds) the speci�ed server. Settings not associated
with a particular device (such as network settings, bridge name and location) are not included.

NOTE: A restore will update devices in an additive fashion. For each device (and command or sked), if a device already exists with the same
key, then it is updated. If no such device exists, then it will be created.

REQUEST BODY SCHEMA: application/json

host string
IP address of local HTTP server that will accept or serve snapshot.

http_port string
HTTP port number of server. Usually not 80 because mobile phone or other OS will generate a random
unused high port for the application.

path string
Path to directory on HTTP server to use. Must not include any query or fragment. Must start (but not end)
with a forward slash. Must not include the �lename.

252 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

timestamp string
Required only for backup operation. Timestamp for inclusion in the �lename.

filename string
Required only for restore operation. Firmware generates the �lename for backups.

Format:

/<bond-id>_<fw-ver>_<timestamp>_<random>.bsnap

Timestamp is as provided by client.

dev_ids string
If not provided, all devices are included in backup.

If provided, this list of device IDs are backed up.

Backup includes devices with their names, locations, schedules, commands & signals, properties, and
state.

Responses

— 200 Backup/Restore started

401 Unauthorized

500 Internal Server Error

253 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/sys/backup

Request samples

Payload

Copy Expand all Collapse all

{
"host": "192.168.1.107",
"http_port": "80",
"path": "/snapshots",
"timestamp": "1618599782",
"filename": "/ZZDE12345_v2.18.4-alpha_1618599782_0f8d01fa.bsnap",
- "dev_ids": [
"aabbccdd"
]
}

Response samples

401 500

254 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

Cancel a failed operation, or clear the success/error status.

Responses

— 204 Backup/Restore canceled

401 Unauthorized

500 Internal Server Error

/v2/sys/backup

Response samples

255 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

401 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

Perform a reset operation, of which there are several types:

Setup reset will cause:

• serves as proof-of-ownership event so as to:

◦ cause Bond Con�g AP to reappear
◦ allow the product to be set up on a new Wi-Fi network
◦ allow adding to a new Bond account
• Wi-Fi station details may be lost, depending on the product

256 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

• Bond will not reboot

Factory reset will cause:

• complete erasure of Bond's local database. Speci�cally:

◦ All devices and settings will be lost
◦ Bond will need to be reconnected to Wi-Fi
• Bond will also reboot
• Bond will remain on the current �rmware version.

REQUEST BODY SCHEMA: application/json

type string
• "factory" : factory reset (aka "White Reset")
• "setup" : setup reset (aka "Wi-Fi Reset" or "Green reset")

Responses

— 200 Reset started

401 Unauthorized

500 Internal Server Error

/v2/sys/reset

257 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Request samples

Payload

Copy
{
"type": "factory"
}

Response samples

401 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

258 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Reboot Bond. No settings are modi�ed.

This does NOT perform a factory reset!

Responses

— 200 Rebooting

401 Unauthorized

500 Internal Server Error

/v2/sys/reboot

Response samples

401 500

259 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

Get information about Bond system time, timezone, and grid location.

Responses

200 Time info

401 Unauthorized

260 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

404 Not Found

500 Internal Server Error

/v2/sys/time

Response samples

200 401 404 500

Copy
{
"unix_time": 1581708795,
"time_set": true,
"tz": "America/Sao_Paolo",
"grid": "FN30aw"
}

261 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Set timezone, grid location, and/or time.

If tz is set to null , all skeds based on a local time (mark=midnight) will be disabled.

Likewise, if grid is set to null , all skeds based on solar marks will be disabled.

REQUEST BODY SCHEMA: application/json

unix_time number
Absolute time, in seconds since the UNIX epoch.

Starts at zero at �rst boot for most products (with no backup battery). Automatically set via NTP (unless
NTP has been disabled or the NTP server is unreachable), at which time time_set is set.

time_set boolean
If false, then time has not (yet) been set or determined via NTP.

Device Schedules do not run unless time_set is true.

tz string or null
Timezone string, as per tz_database.

null if unset.

The current list of supported timezones is given at https://bond-updates.s3.amazonaws.com/tz_meta.json

262 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

grid string or null

Approximate geolocation of Bond unit, expressed as a 6-character Maidenhead Grid Locator. This
information is used to calculate the sunrise and sunset times for Device Schedules.

Regex: ([A-R]{2}[0-9]{2}[a-r]{2})?

null if unset.

See: https://en.wikipedia.org/wiki/Maidenhead_Locator_System

Responses

— 200 Time info updated

400 Bad request

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/sys/time

Request samples

263 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Payload

Copy
{
"unix_time": 1581708795,
"time_set": true,
"tz": "America/Sao_Paolo",
"grid": "FN30aw"
}

Response samples

400 401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "The resource wasn't created because of a validation problem (This field will have a description of the problem)"
}

264 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Forget time, timezone, and grid location.

As a consequence, all skeds will be immediately disabled (enabled=false).

Responses

— 204 Time info reset

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/sys/time

Response samples

401 404 500

Copy
{
"_error_id": 1,

265 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

"_error_msg": "You need authentication credentials to continue"

}

266 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Get information about Power Supply status (which supply is active).

Sent gratuitously upon change to active supplies.

Responses

200 Power Supply info

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/sys/power

Response samples

200 401 404 500

267 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"poe_active": true,
"usb_active": false
}

AUTHORIZATIONS: None

Responses

200 Get Locale info

401 Unauthorized

404 Not Found

268 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

500 Internal Server Error

/v2/sys/locale

Response samples

200 401 404 500

Copy
{
"compliance_region": "au"
}

AUTHORIZATIONS: None

REQUEST BODY SCHEMA: application/json

compliance_region string
Region for radio frequency compliance. This option must be set by the client (Bond Home app) during

269 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

setup. String is a two-digit country code (ISO 3166-1 alpha-2). Supported options:

• us: USA, Canada, Mexico

• au: Australia [v2.15]

Responses

200 Change Locale info

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/sys/locale

Request samples

Payload

Copy

270 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

{
"compliance_region": "au"
}

Response samples

200 401 404 500

Copy
{
"compliance_region": "au"
}

After deletion, default values will be restored.

AUTHORIZATIONS: None

Responses

— 204 Reset Locale info

271 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

401 Unauthorized

404 Not Found

500 Internal Server Error

/v2/sys/locale

Response samples

401 404 500

Copy
{
"_error_id": 1,
"_error_msg": "You need authentication credentials to continue"
}

272 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Get some statistics about the main Bond database such as free space available.

This endpoint exists for each of the partitions on the product which use the Beau database format:

• "db" - the main read-write database where devices and settings are stored
• "id" - the read-only partition containing Bond ID and certi�cates
• "state" - contains state of each device [Bridges only]

PATH PARAMETERS

partition
string
required

Responses

200 Database statistics

/v2/debug/beau/{partition}

Response samples

273 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

200

Copy
{
"live_records": 20,
"dead_records": 33,
"empty_pages": 0,
"total_dead": 110824,
"total_free": 900421,
"max_free": 4002,
"total_head": 900421,
"min_head": 15,
"compactions": 1,
"size": 1048576,
"page_size": 4096,
"dirty": false
}

274 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Get the current con�guration of the LiveLog component.

Responses

200 LiveLog con�guration

— 204 LiveLog disabled

/v2/debug/livelog

Response samples

200

275 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"ip": "192.168.1.102",
"port": 1337
}

Instructs Bond to start sending UDP packets to speci�ed IP address and port. Every log message is sent in a seperate UDP packet. Depending
on log verbosity, this may cause serious performance problems, so use wisely.

This setting does not persist reboot.

REQUEST BODY SCHEMA: application/json

ip string

port number

Responses

— 200 LiveLog con�gured

276 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

— 400 Error parsing request

/v2/debug/livelog

Request samples

Payload

Copy
{
"ip": "192.168.1.102",
"port": 1337
}

Responses

277 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

— 204 LiveLog disabled

/v2/debug/livelog

Get status from the BLED driver.

If manual is 0 , value re�ects the instantaneous value of the LEDs, and may change rapidly and automatically.

Responses

200 LED state

278 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

/v2/debug/leds

Response samples

200

Copy
{
"n": 5,
"manual": 1,
"value": "FF000000FF000000FFFFFFFF000000"
}

Use this endpoint to manually control LEDs, such as during factory test. Be sure to use the manual �eld to prevent value from being
overridden from automatic LED control.

If manual is 0 or absent, value may still be set, but may be overridden at any time.

REQUEST BODY SCHEMA: application/json

279 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

manual number
• 0 : LEDs behave normally (default)
• 1 : LED automatic control disabled, will remain �xed as set

value string
Concatinated 24-bit RGB hex values for each of the n LEDs.

In the example, the 5 LEDs are set to Red, Green, Blue, White, and Off, respectively.

Responses

— 200 LED state was changed successfully

— 400 Error parsing request

— 500 Driver error

/v2/debug/leds

Request samples

Payload

280 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"manual": 1,
"value": "FF000000FF000000FFFFFFFF000000"
}

The shutdown �eld indicates the power state of the Wi-Fi (+BLE) radio:

• 0 : normal operation
• 1 : low-power shutdown mode

If the shutdown �eld is not present, assume normal operation.

Responses

281 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

200 Wi-Fi power settings

/v2/debug/wifi

Response samples

200

Copy
{
"shutdown": 1
}

Set shutdown to 1 or 0 to control the Wi-Fi (+BLE) radio power level. A value of 1 turns this radio off.

These settings do not persist past reboot.

REQUEST BODY SCHEMA: application/json

282 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

shutdown number

Responses

— 200 Wi-Fi power settings changed

/v2/debug/wifi

Request samples

Payload

Copy
{
"shutdown": 1
}

283 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

(Bond Bridge only) Intended for use in debugging signal generation. All values false by default, and changes do not persist past reboot.

silence_tx stops the Bond Bridge from transmitting anything. It should otherwise behave normally: the LEDs �ash, device state should
change, etc.

log_signals causes all signals to be sent to sent to any listeners as they are generated. They are sent on the topic debug/rfman/
signal , and could be monitored by a BPUP client listening on this topic. This is intended as a testing tool, to verify whether signals are
generated as expected.

Responses

200 RF manager con�guration

/v2/debug/rfman

Response samples

200

284 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"log_signals": false,
"silence_tx": false
}

(Bond Bridge only) Intended for use in debugging signal generation. All values false by default, and changes do not persist past reboot.

silence_tx stops the Bond Bridge from transmitting anything. It should otherwise behave normally: the LEDs �ash, device state should
change, etc.

log_signals causes all signals to be sent to sent to any listeners as they are generated. They are sent on the topic debug/rfman/
signal , and could be monitored by a BPUP client listening on this topic. This is intended as a testing tool, to verify whether signals are
generated as expected.

REQUEST BODY SCHEMA: application/json

log_signals boolean

silence_tx boolean

285 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Responses

200 RF Manager con�gured

— 400 Error parsing request

/v2/debug/rfman

Request samples

Payload

Copy
{
"log_signals": false,
"silence_tx": false
}

Response samples

200

286 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

Copy
{
"log_signals": false,
"silence_tx": false
}

Responses

— 204 RF Manager settings reset

/v2/debug/rfman

287 of 288 3/6/2024, 8:36 PM

Bond Local API http://docs-local.appbond.com/#tag/Bridge/paths/~1v2~1bridge/get

288 of 288 3/6/2024, 8:36 PM