Notice: We're retiring Works with Nest. See the home page for more information.

Smoke+CO Alarm API

The Nest API works with all Nest Protect™ smoke + carbon monoxide alarm models.

Users can add multiple Nest Protects to the devices/smoke_co_alarms group, up to the maximum per structure. When you make a call to this data location, you can access Nest Protect data (data values for devices in the structure).

All the below values are found under each devices/smoke_co_alarms/device_id in the JSON document.

device_id

Nest Protect unique identifier.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/device_id
Returnsstring
Example: "RTMTKxsQTCxzVcsySOHPxKoF4OyCifrs"
Accessread-only
Available inSmoke+CO read / v1-v5

locale

Specifies language and region (or country) preference.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/locale
Returnsstring
Examples: "en-GB", "en-US", "es-US", "fr-CA", "fr-CA", "nl-NL"
Accessread-only
Available inSmoke+CO read / v1-v5

software_version

Software version.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/software_version
Returnsstring
Example: "1.0.1"
Accessread-only
Available inSmoke+CO read / v1-v5

structure_id

Structure unique identifier.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/structure_id
Returnsstring
Example: "VqFabWH21nw..."
Accessread-only
Available inSmoke+CO read / v1-v5

name

Display name of the device; can be any room name from a list we provide, or a custom name.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/name
Returnsstring
Example: "Hallway"
Accessread-only
Available inSmoke+CO read / v1-v5

name_long

Long display name of the device. Includes a custom (label), created by the user, or via wheres.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/name_long
Returnsstring
Example: "Hallway Protect (upstairs)"
Accessread-only
Available inSmoke+CO read / v1-v5

last_connection

Timestamp of the last successful interaction with the Nest service, in ISO 8601 format.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/last_connection
Returnsstring
Example: "2016-12-31T23:59:59.000Z"
Accessread-only
Available inSmoke+CO read / v1-v5

is_online

Device connection status with the Nest service.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/is_online
Returnsboolean
Values: true, false
Accessread-only
Available inSmoke+CO read / v1-v5

battery_health

Battery life/health; estimate of remaining battery power level.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/battery_health
Returnsstring enum
Values: "ok", "replace"
Accessread-only
Available inSmoke+CO read / v1-v5

co_alarm_state

Carbon monoxide (CO) alarm status.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/co_alarm_state
Returnsstring enum
Values: "ok", "warning", "emergency"
Accessread-only
Available inSmoke+CO read / v1-v5

smoke_alarm_state

Smoke alarm status.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/smoke_alarm_state
Returnsstring enum
Values: "ok", "warning", "emergency"
Accessread-only
Available inSmoke+CO read / v1-v5

is_manual_test_active

State of the manual smoke and CO alarm test.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/is_manual_test_active
Returnsboolean
Values: true, false
Accessread-only
Available inSmoke+CO read / v2-v5

last_manual_test_time

Timestamp of the last successful manual smoke and CO alarm test, in ISO 8601 format.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/last_manual_test_time
Returnsstring
Example: "2016-12-31T23:59:59.000Z"
Accessread-only
Available inSmoke+CO read / v2-v5

ui_color_state

Indicates device status by color in the Nest app UI. It is an aggregate condition for battery+smoke+CO states, and reflects the actual color indicators displayed in the Nest app.

For more information on color indicators, see Nest Protect lights and Nest Protect battery level.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/ui_color_state
Returnsstring enum
Values: "gray", "green", "yellow", "red"
Accessread-only
Available inSmoke+CO read / v1-v5

where_id

A unique, Nest-generated identifier that represents name, the display name of the device.

Learn more about where names for Nest Thermostats, Nest Protects and Nest Cams.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/where_id
Returnsstring
Example: "d6reb_OZTM..."
Accessread-only
Available inSmoke+CO read / v3-v5

where_name

The display name of the device. Associated with the Nest Protect where_id. Can be any room name from a list we provide, or a custom name. Learn more about where names for Nest Thermostats, Nest Protects and Nest Cams.

Details
https://developer-api.nest.com/devices/smoke_co_alarms/device_id/where_name
Returnsstring
Example: "Hallway"
Accessread-only
Available inSmoke+CO read / v5