API docs by Redocly

SkyBell Gen5 API (1.33.3)

Download OpenAPI specification:

SkyBell API

Welcome to the SkyBell API documentation. Please check back frequently. The version of this documentation should match the version of the API you're trying to access (see /health endpoint to get the current API version).

Overview

The SkyBell platform is backed by AWS to create a scalable and secure platform for your devices.

Requirements

Before you can actually begin working with the API you will need from SkyBell:

  • SkyBell doorbell or chime device

  • A SkyBell account using an email account you have access to

Personal API Keys

SkyBell offers their users access to the SkyBell API via API keys generated for them. This is a great alternative to managing JWT tokens. To obtain your API key, please login to the Developers section of the SkyBell website and generate your API key. User API keys are in UUID format.

⚠️ Your API key gives full access to your SkyBell account! Do not give it out and treat it with the same secrecy you would treat your password! ⚠️

⚠️ User API Keys are for personal use only! SkyBell has fantastic integration options for partners! Please contact us for more detail. ⚠️

Once you have your API key, simply include it in a "x-skybell-user-api-key" header of any HTTPS REST call you make to the SkyBell API. For example if your personal API key was adb4424f-09cf-42de-bec9-2a34f8f1d417 you could make a cURL call that looks like:

curl --location 'https://api.skybell.network/api/v5/user' --header 'x-skybell-user-api-key: adb4424f-09cf-42de-bec9-2a34f8f1d417'

Auth

SkyBell auth is available using JWT tokens, OAuth 2.0, or session/cookies. Authentication data is to be sent in the HTTP Authorization header.
💠 Notice: You do not need to login or interact with other authentication endpoints if you are using a personal API key. The personal API key is automatically authenticated for the user that it was generated by (which is why you must protect it the same as your password!)

💠 Notice: Requests made using JWT should include the HTTP header x-skybell-app providing the current mobile app version. If it is not provided, your request may be rejected. If you are using a personal API key instead of JWT you do not need to provide this header.

JSON Response format

The SkyBell API will respond in JSON with a standard format:

{
     error: Boolean,
     message: String,
     data: any
}

Expect HTTP Status 200 OK HTTP Status 201 Created or when an API call succeeds.
HTTP status codes in the 4XX indicate a problem with the syntax, format, or missing data from with the incoming request (you can fix it by changing the request).
HTTP status codes in the 5XX indicate a problem with the cloud processing the request (you probably can't fix it by changing the request).

MQTT

The SkyBell Platform is composed of HTTPS and MQTT protocols. Where possible SkyBell devices do not make HTTP(S) requests, instead they use MQTT to communicate with the cloud. However access to the Device to Cloud MQTT is restricted at this time. This document covers the HTTPS API interactions only. No direct user access via MQTT is possible at the moment.

If you make an API request that requires MQTT communication with the device, the response time of the request will be tied to how long it takes for your device to respond. If your device does not respond to the MQTT message within 30 seconds, the API request will fail with a specific 599 HTTP error code indicating that it was the device itself that failed to respond.

Provisioning Process

Setting up a new SkyBell device requires you to connect to the WiFi access point provided by a SkyBell doorbell ("Skybell_XXXXXXXXX", where "XXXXXXXXX" is the device serial number). Once connected you need to send an HTTP request to the device itself containing: the wifi information the device is to use, a previously obtained invite token, and the "backend number" to use (each backend number corresponds to a different SkyBell cloud environment -- your invite token must have also come from the selected environment).

After the device has that information it will connect to the SkyBell backend specified and complete the provisioning process.

SkyBell%20Wifi%20provisioning%20sequence%20diagram

Device LED Color Guide

Blue & Red | Flashing
Skybell is charging.

Yellow | Solid
Skybell is booting.

Red & Green | Alternating Flashing
Skybell is in standard WiFi mode (AP mode).

Orange | Rapid Double-Flash
Connecting to WiFi, No WiFi, or lost WiFi connection.

Blue & Green** | Alternating Flashing
Connected to WiFi network and now connecting to SkyBell servers.

Green | Solid
Skybell is ready to use. (Idle color can be set by user or turned off. Green is the default from factory)

White | Solid
In "call" mode or motion was detected by the camera. Live stream connection is available.

Factory reset:
Hold down button for an entire two minutes. Device will cycle through several LED color states, release the button when the device finally reaches solid yellow. This will take 90 - 150 seconds.

Blue | Rapid Double-Flash
A problem with the power supply is detected.

Blue & Yellow | Alternating Flashing
A firmware update is in progress.

SkyBell Doorbell UDP Broadcast

SkyBell devices will send and recieve UDP broadcast packets that you can use to:

  • Be notified of doorbell button push events by listening for these broadcasts

  • Be notified of doorbell motion detection events by listening for these broadcasts

  • Send your own button push and motion events that chime SkyBell devices when fired by sending your own

UDP Packet for Button Push

    0x2D, 0x00, 0x00, 0x00, 0x55, 0x32, 0x46, 0x73,
    0x64, 0x47, 0x56, 0x6B, 0x58, 0x31, 0x39, 0x49,
    0x32, 0x71, 0x62, 0x66, 0x59, 0x56, 0x6A, 0x45,
    0x78, 0x35, 0x35, 0x64, 0x45, 0x30, 0x49, 0x77,
    0x54, 0x31, 0x4D, 0x47, 0x4A, 0x51, 0x4F, 0x37,
    0x2B, 0x31, 0x30, 0x75, 0x59, 0x73, 0x51, 0x3D,
    0x0A

UDP Packet for Motion Detection

    0x2D, 0x00, 0x00, 0x00, 0x55, 0x32, 0x46, 0x73,
    0x64, 0x47, 0x56, 0x6B, 0x58, 0x31, 0x39, 0x44,
    0x35, 0x4D, 0x6B, 0x49, 0x6B, 0x6F, 0x4D, 0x64,
    0x4E, 0x61, 0x61, 0x52, 0x4C, 0x39, 0x6E, 0x64,
    0x43, 0x46, 0x59, 0x6E, 0x4D, 0x56, 0x4B, 0x70,
    0x69, 0x2F, 0x79, 0x6C, 0x42, 0x71, 0x38, 0x3D,
    0x0A

UDP Packet Broadcast Examples

In these examples we'll use the local IP address "192.168.2.15" and to broadcast on "255.255.255.255" port 5000. The local IP value is likely to be different on your network. Please use the appropriate local IP address for your client and network.

For example, we can broadcast the SkyBell button pressed UDP packet and any SkyBell devices online that network should play the sound they have configured for "button pressed":

In Windows, using PowerShell:

$bytes = [byte[]] (0x2d,0x00,0x00,0x00,0x55,0x32,0x46,0x73,0x64,0x47,0x56,0x6b,0x58,0x31,0x39,0x49,0x32,0x71,0x62,0x66,0x59,0x56,0x6a,0x45,0x78,0x35,0x35,0x64,0x45,0x30,0x49,0x77,0x54,0x31,0x4d,0x47,0x4a,0x51,0x4f,0x37,0x2b,0x31,0x30,0x75,0x59,0x73,0x51,0x3d,0x0a)
$client = New-Object System.Net.Sockets.UdpClient
$client.Client.Bind([System.Net.IPEndPoint] [System.Net.IPAddress]::Parse("192.168.2.15"), 6666)
$client.EnableBroadcast = $true
$client.Send($bytes, $bytes.Length, "255.255.255.255", 5000)
$client.Close()

In Linux, OSX, using BASH and socat:

echo -en '\x2d\x00\x00\x00\x55\x32\x46\x73\x64\x47\x56\x6b\x58\x31\x39\x49\x32\x71\x62\x66\x59\x56\x6a\x45\x78\x35\x35\x64\x45\x30\x49\x77\x54\x31\x4d\x47\x4a\x51\x4f\x37\x2b\x31\x30\x75\x59\x73\x51\x3d\x0a' | socat - udp-datagram:255.255.255.255:5000,bind=192.168.2.15:6666,broadcast,reuseaddr

UDP Packet Receive Example

Here is a small Python script you can use to watch for SkyBell UDP messages. Assuming you are running on the same local network as the SkyBell device:

import socket
import struct
def receive_udp_broadcasts(port=5000):
    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    sock.bind(('', port))
    print(f"Listening for UDP broadcasts on port {port}...")
    try:
        while True:
            data, addr = sock.recvfrom(1024)
            print(f"Received from SkyBell at IP: {addr}")
    except KeyboardInterrupt:
        print("Shutting down...")
    finally:
        sock.close()
if __name__ == "__main__":
    receive_udp_broadcasts()

Auth

SkyBell supports OAuth2.0 and JWTs for external API use. For deeper, or more unique integrations, please get in touch with us!

Access Tokens

Obtain your access, ID, and refresh tokens by logging in at the login endpoint with your SkyBell email address and password:

POST /api/v5/login

Upon success you will get several tokens. Please secure these tokens well as they are effectively the keys to your SkyBell account. Should you lose, or expose them and require all your current tokens expire, simply log out:

GET /api/v5/logout

The access token can found in the login response at:

data.AuthenticationResult.AccessToken

This is the token that should be placed in the HTTP "Authorization" header when making an authenticated API request:

curl --location 'https://api.skybell.network/api/v5/user' --header 'Authorization: Bearer YOURACCESSTOKENHERE'

When you login, you will also get the expiry time of your access tokens. You will need to call the token refresh endpoint before the expiry time otherwise your API requests will start to fail. The refresh token can found in the login response at:

data.AuthenticationResult.RefreshToken

To refresh the access token, send the refresh token you saved from /api/v5/login along to the token refresh endpoint:

PUT /api/v5/token

With a JSON body payload of:

{"refresh_token": "YOURFREFRESHTOKENHERE"}

This end point will return updated tokens for you to save, and then you can continue to make authenticated API requests.

Create User

Create new user

Use this endpoint to create SkyBell users.

Users will still have to confirm their email address.

Requirements

  • An email address not already signed up to this SkyBell environment

Request Body

  • email - String - The email address of the SkyBell user you wish to create
  • password - String - The password for the SkyBell user you wish to create
  • fname - String - The first name for the user signing up
  • lname - String - The last name for the user signing up
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "fname": "Sky",
  • "lname": "Bell",
  • "email": "skybelluser@example.com",
  • "password": "BellSky!2023"
}

Login User (JWT)

Get JWT Token

Use this endpoint to login SkyBell users. The returned JWT token is used in subsequent API calls authenticating a user by putting the JWT token in the Authorization HTTP header.

You will probably want to store the RefreshToken property so you can later refresh the access token using the PUT /api/v5/token endpoint.

Requirements

  • A username (email) and password for an existing SkyBell user

Request Body

  • username - String - The email address of the SkyBell user you wish to login
  • password - String - The password for the SkyBell user you wish to login

Example Response

The JWT token to use is .data.AuthenticationResult.IdToken
Place it in the Authorization HTTP header any API request you wish to authenticate with this user.

{
    "error": false,
    "message": "OK",
    "data": {
        "ChallengeParameters": {},
        "AuthenticationResult": {
            "AccessToken": "ThisIsAnOAuthStyleAccessToken",
            "ExpiresIn": 3600,
            "TokenType": "Bearer",
            "RefreshToken": "ThisIsARefreshTokenForBothTheJWTandOAuthTokens",
            "IdToken": "ThisIsTheJWTTokenYouPutInTheAuthorizationHTTPHeader"
        }
    }
}
Authorizations:
noauthAuth
header Parameters
Content-Type
string
Example: application/json
Request Body schema: */*
string

Responses

Token Refresh

Refresh JWT Access Token

Set the body of this endpoint to the refresh token you got when logging in and you will be provided with updated JWT access and ID tokens.

Example Response

{
    "error": false,
    "message": "Refreshed",
    "data": {
        "AccessToken": "ThisIsAnOAuthStyleAccessToken",
        "ExpiresIn": 86400,
        "TokenType": "Bearer",
        "IdToken": "ThisIsTheJWTTokenYouPutInTheAuthorizationHTTPHeader"
    }
}
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "AVeryLongStringOfCharactersThatWasTheValueOfTheRefreshTokenPropertyWhenFirstLoggingIn"
}

Logout

Log User Out, Revoke All Tokens

Use this endpoint to log a user out of everything. This will revoke all tokens and sessions for the user.

If this returns a 401, it means the token you are trying to user for logout is already invalidated or expired.

Example Response

{
    "error": false,
    "message": "OK"
}

Responses

OAuth2 Token

Responses

OAuth2 Authorization

Responses

Login User (OAuth2)

OAuth2.0 Login Endpoint

Use this endpoint to login SkyBell users who want to use the SkyBell API externally using OAuth2.0. The returned OAuth bearer tokens can used in subsequent API calls authenticating a user by putting the access_token token in the Authorization HTTP header.

Authorizations:
noauthAuth

Responses

Create Personal API Key

Generate Personal API Key

Use this endpoint to create or regenerate personal API keys for SkyBell users.

Request Body

(none)

Authorizations:
bearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
""

Get Personal API Key

Generate Personal API Key

Use this endpoint to retrieve your current personal API key for SkyBell users.

Request Body

(none)

Authorizations:
bearerAuth

Responses

Delete Personal API Key

Delete Personal API Key

Use this endpoint to remove a personal API key for SkyBell users.

Request Body

(none)

Authorizations:
bearerAuth

Responses

Activities

"activities" are what SkyBell calls the history of any event that happens to the device. A doorbell press generates an activity for example.

All API endpoints will start with: /api/v5/activities/

List Activities

Event History

Get a list of events for the logged in user.

Requirements

  • Logged in user, JWT token provided in header.

Query Parameters

All optional.

  • limit - Number - The limit of activities to return (default: 500). Typically used for pagination.
  • offset - Number - Start listing activities from this provided number instead of the default of 0. Typically used for pagination.
  • device - String, UUID - Filter events by the provided device.
  • type - String, enum("lstream", "doorbell", "motion", "sound") - Filter events out by the provided event type.
  • start - Number, Date in JS UNIX timestamp format - Apply a date filter between the start and end query params.
  • end - Number, Date in JS UNIX timestamp format - Apply a date filter between the start and end query params.
  • nopreviews - Boolean - If you provide a "true" or a 1 in this query param, the response will come back without the base64 JPEG "image" property on each activity. This will significantly reduce the size of activity queries.

Example Response

SkyBell returns the preview image as part of this response as a string in base64 format.

{
    "error": false,
    "status": 200,
    "message": "OK",
    "data": {
        "count": 1,
        "start": "2022-11-08T15:22:20.447Z",
        "end": null,
        "rows": [
            {
                "event_time": 1648493804113,
                "account_id": "33dae2fb-499a-496c-88b5-897da608a04a",
                "device_id": "dd767527-ec0a-41ad-a339-2fba0c26e457",
                "device_name": "Front Door",
                "activity_id": "a629c05f-8046-4f4e-8d96-dd7d78a691b8",
                "event_type": "lstream",
                "date": "03/28/2022",
                "video_url": "https://skybell-videos.s3.amazonaws.com/33dae2fb-499a-496c-88b5-897da608a04a/dd767527-ec0a-41ad-a339-2fba0c26e457/videos/a629c05f-8046-4f4e-8d96-dd7d78a691b8/a629c05f-8046-4f4e-8d96-dd7d78a691b8_dd767527-ec0a-41ad-a339-2fba0c26e457_video_stream.mp4?AWSAccessKeyId=AKIAXVAD7YUYAFPDN6V2&Expires=1648840939&Signature=o3YZsDG4eyv1q9uHCi19VKM4k7A=",
                "image": "ThisIsAGiantBase64EncodedStringThatDecodesToaJPEGImage",
                "edge_tags": null,
                "ai_ppe": null
            }
        ]
    }
}
Authorizations:
noauthAuth

Responses

Get Activity Video

Get Activity Video

Get a download URL for the provided activity by ID.

Requirements

  • Logged in user, JWT token provided in header.

Example Response

SkyBell returns the download URL as a presigned S3 URL. Please take notice of the expire time, the URL provided here is meant to be consumed within a very short period of time from calling this endpoint.

{
    "error": false,
    "message": "OK",
    "data": {
        "download_url": "https://skybell-videos.s3.amazonaws.com/ACCOUNTID/DEVICEID/videos/ACTIVITYID/ACTIVITYID_DEVICEID_video_stream.mp4?AWSAccessKeyId=AKIATEMPORARYKEY&Expires=UNIXTIMESTAMP_EXPIRY&Signature=SIGNATURESTRINGCHARACTERS"
    }
}
Authorizations:
noauthAuth

Responses

Delete Activity

Remove Event

Delete a single provided event from the users history. Be careful, this operation is not reversible!

Requirements

  • Logged in user, JWT token provided in header.

Request Body

(none)

Example Response

{
    "error": false,
    "status": 200,
    "message": "OK",
    "data": true
}

Responses

Delete Days Activity

Remove Whole Day of Events

Be very careful, this endpoint deletes all the events for all devices for a user on the provided day. This operation is not reversible!

Requirements

  • Logged in user, JWT token provided in header.

Request Body

  • day - String - The day in MM/DD/YYYY format (ex: 01/22/2022)

Example Response

{
    "error": false,
    "message": "OK",
    "data": true
}

Responses

Get Activity Short Summary

Return Short Summary of Daily Activities

Returns a list of activities sorted by day to be used on activity over-view pages.

Requirements

  • Logged in user, JWT token provided in header.

Example Response

{
    "error": false,
    "status": 200,
    "message": "OK",
    "data": {
        "start": 1673719149097,
        "end": "2023-02-14T17:59:09.097Z",
        "count": 16,
        "days": {
            "02/07/2023": [
                {
                    "activity_id": "88ba4005-2927-47ec-821d-258fd84707d7",
                    "device_id": "61dea457-f533-4851-9403-adaed9e9bd82",
                    "device_name": "Trim2 Board",
                    "event_type": "lstream",
                    "event_time": 1675812222233
                },
                {
                    "activity_id": "b8883372-ea27-4e02-81dc-4a1a1ae6b8d0",
                    "device_id": "61dea457-f533-4851-9403-adaed9e9bd82",
                    "device_name": "Trim2 Board",
                    "event_type": "lstream",
                    "event_time": 1675794916456
                },
                {
                    "activity_id": "afcff40a-a9a8-4721-b839-187a3f1dd390",
                    "device_id": "61dea457-f533-4851-9403-adaed9e9bd82",
                    "device_name": "Trim2 Board",
                    "event_type": "lstream",
                    "event_time": 1675789007701
                }
            ],
            "02/02/2023": [
                {
                    "activity_id": "fffa2207-09a6-4643-b7d1-bed9240225c8",
                    "device_id": "61dea457-f533-4851-9403-adaed9e9bd82",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1675298997494
                },
                {
                    "activity_id": "eac07784-5807-4707-ad8d-cab770fef9ad",
                    "device_id": "fb30e39c-60a0-47ed-9e64-ba4f2302ae53",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1675298973262
                },
                {
                    "activity_id": "cee09cc3-33cc-4178-99e7-cc798884a008",
                    "device_id": "61dea457-f533-4851-9403-adaed9e9bd82",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1675298959010
                },
                {
                    "activity_id": "dcc015ce-da53-4caf-92bf-bdb5de7c6c7c",
                    "device_id": "fb30e39c-60a0-47ed-9e64-ba4f2302ae53",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1675298066899
                },
                {
                    "activity_id": "a5720507-8aaa-4d5a-93d7-e53f8b33e6d1",
                    "device_id": "61dea457-f533-4851-9403-adaed9e9bd82",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1675297696752
                },
                {
                    "activity_id": "73f1654b-762c-45bb-984e-313ab8ea9de5",
                    "device_id": "61dea457-f533-4851-9403-adaed9e9bd82",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1675296996323
                }
            ],
            "01/17/2023": [
                {
                    "activity_id": "8a2bbdcd-51a8-4fa0-887a-9904d65c7487",
                    "device_id": "fb30e39c-60a0-47ed-9e64-ba4f2302ae53",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1673975308292
                },
                {
                    "activity_id": "e5832a8f-71be-4640-bb47-a6b6d1f9f49a",
                    "device_id": "61dea457-f533-4851-9403-adaed9e9bd82",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1673969023597
                },
                {
                    "activity_id": "f3b7126e-995a-4434-9597-59a4bb996e79",
                    "device_id": "fb30e39c-60a0-47ed-9e64-ba4f2302ae53",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1673968971852
                },
                {
                    "activity_id": "88430cfc-42a3-40f1-8d36-18d18e238800",
                    "device_id": "61dea457-f533-4851-9403-adaed9e9bd82",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1673968954209
                },
                {
                    "activity_id": "2821c86b-56d5-48de-abe3-f304025c5356",
                    "device_id": "61dea457-f533-4851-9403-adaed9e9bd82",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1673967750477
                },
                {
                    "activity_id": "4e7c5b54-f0e0-4550-a2c3-655f8a6a214a",
                    "device_id": "fb30e39c-60a0-47ed-9e64-ba4f2302ae53",
                    "device_name": "Front Door",
                    "event_type": "doorbell",
                    "event_time": 1673967720120
                },
                {
                    "activity_id": "627cd28a-2f81-4438-ab5a-7719f1e0e6cf",
                    "device_id": "61dea457-f533-4851-9403-adaed9e9bd82",
                    "device_name": "Front Door",
                    "event_type": "lstream",
                    "event_time": 1673967612259
                }
            ]
        }
    }
}

Responses

Sharing

Endpoints related to device access sharing.

Invite Email to Share Device

Share a Device with Another SkyBell User

Use this endpoint to create (or try to resend) an email to an existing SkyBell user inviting them to share access with the provided device.

Requirements

  • Logged in user, JWT token provided in header.

  • Invite user must already have SkyBell account

Request Body

  • invitedEmail - String, email - The email address of the user to invite to share access to this device.

For example:

{
    "invitedEmail": "anotherskybelluser@example.com",
}

Example Response

A newly created invite will generate a 201 status code and a response like:

{
    "error": false,
    "message": "Device share created, invite sent.",
    "data": {
        "invite_token": "1652311975344b675771b7cd741da8b750eb45bffaf1eb762606b4ab042048d6e30ea4744aa4c"
    }
}

The invited user must redeem that token by sending it (while logged in) to the GET /api/v5/devices/DEVICE_ID/share/redeem endpoint in an invite_token param as JSON data.

If the invite already exists and 10 minutes have passed since the last send, calling this endpoint will resend the invite email and you will get a 200 status response like:

{
    "error": true,
    "message": "Invite already exists. Resending.",
    "data": {
        "invite_token": "165231075983772e47b66e1b944d5b3f971e3a86b1d6d38e3a83d0bd846f8a797a6b88f7bc384",
        "last_invite_sent": "2022-05-11T23:26:44.657Z"
    }
}

If not enough time has passed, you'll be given a 202 response status the time when you can resend the invite:

{
    "error": true,
    "message": "Invite already exists. Not resending. Can resend in a minute",
    "data": {
        "invite_token": "165231075983772e47b66e1b944d5b3f971e3a86b1d6d38e3a83d0bd846f8a797a6b88f7bc384",
        "can_resend_at": "2022-05-11T23:32:56.963Z"
    }
}
Request Body schema: */*
string

Responses

Redeem Invite to Share Device

Share a Device with Another SkyBell User

Use this endpoint to accept a device share from another SkyBell user.

Requirements

  • Logged in user, JWT token provided in header.

Example Response

Accepting the invite by passing the token back to SkyBell will generate a 200 status code and a response like:

{
    "error": false,
    "message": "Device share accepted.",
    "data": {
        // Newly shared device info
    }
}

Afterwards the newly shared user can make any call to that SkyBell device as if it was their own. Shared devices will automatically appear in the users device list API calls with the shared field set on any device that is not owned by that user but shared to them.

Responses

Revoke Device Share

Share a Device with Another SkyBell User

Use this endpoint to revoke any existing device share from another SkyBell user.

Requirements

  • Logged in user, JWT token provided in header.

Request Body

  • share_id - String - The share ID to be deleted. Get this by calling the GET /api/v5/devices/shares and choosing the appropriate share_id to revoke here.

For example:

{
    "share_id": "9534f7a2-110f-479f-ae6b-9c426eb389d4",
}

Example Response

Revoking the device share will generate a 200 status code and a response like:

{
    "error": false,
    "message": "Device share revoked.",
    "data": false
}

The user who the device was shared with is not notified that they were unshared. The device simply stops appearing in their device list. Activities from the previously shared device will also remain in the the previously shared users activity history.

Responses

Modify Device Share Access Level

Modify a Shared Device Access Level

Shared devices on SkyBell support giving guest access the ability to read-only or change the devices settings.

If a shared user has "readOnly" set to true, they will be unable to change any settings on the device. (They will retain the ability to toggle their own notifications for motion and button presses).

Requirements

  • Logged in user, JWT token provided in header.

Example Response

Revoking the device share will generate a 200 status code and a response like:

{
    "error": false,
    "message": "OK",
    "data": []
}

The user who the device was shared with is not notified that they were unshared. The device simply stops appearing in their device list. Activities from the previously shared device will also remain in the the previously shared users activity history.

header Parameters
Authorization
string
Example: {{ACTIVE_JWT_TOKEN}}
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "readOnly": true
}

Shared Device Notification Settings

Shared User Specific Settings

All device settings are shared between Owner and Shared users with the exception of two:

- button_pressed - Boolean - Enable or disable notifications for button presses on the shared device (for the shared user only!)
- motion_detection - Boolean - Enable or disable notifications for motion detection on the shared device (for the shared user only!)

Requirements

  • Logged in user, JWT token provided in header.

Example Response

Revoking the device share will generate a 200 status code and a response like:

{
    "error": false,
    "message": "OK",
    "data": []
}
header Parameters
Authorization
string
Example: {{ACTIVE_JWT_TOKEN}}
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "button_pressed": false,
  • "motion_detection": true
}

List Devices Shared

List SkyBell Users Shared with this Device

Use this endpoint to list any existing device shares.

Requirements

  • Logged in user, JWT token provided in header.

Example Response

Revoking the device share will generate a 200 status code and a response like:

{
    "error": false,
    "message": "OK",
    "data": []
}
header Parameters
Authorization
string
Example: {{ACTIVE_JWT_TOKEN}}

Responses

Device

The "device" endpoints are how you interact with a provisioned SkyBell device. Calls that need to communicate with the device are handled in the cloud.

All API endpoints will start with: /api/v5/device/

Start Live Call

Start WebRTC Streaming

Calling this endpoint will return the information required to connect to a live call with a SkyBell device.

It does not matter if this is called when a user is requesting an on-demand live view or if it is in response to a button push event and the camera is already recording: the values returned will be the similar and allow you to establish a live audio and video WebRTC connection with the SkyBell device.

Requirements

  • Logged in user, JWT token provided in header.
  • Device provisioned, online, and reachable by the internet.

Request Body

(optional)

force - Boolean - If provided and set to true, this property will instruct the API to not wait for a response from the device before returning a result. This can be useful for multiple devices connecting.

Example Response

Getting back a successful response means that the cloud has requested the live stream from the device, and it heard the acknowledgement. A successful response here does not guarantee a successful video connection (the next step is for the client application to take the provided data from this endpoint and plug it into its WebRTC library to in order to begin the WebRTC stream STUN/ICE/TURN negotiations).

You'll notice the ChannelARN has your "Device Name" (1817380863_0579ce92-72a5-4b1f-8191-e360876705c3 in this example) which is your devices "SerialNumber_DeviceID".

{
    "error": false,
    "message": "OK",
    "data": {
        "state": true,
        "ice": [
            {
                "urls": "stun:stun.kinesisvideo.us-east-1.amazonaws.com:443"
            },
            {
                "urls": [
                    "turn:54-85-74-21.t-48d26ca8.kinesisvideo.us-east-1.amazonaws.com:443?transport=udp",
                    "turns:54-85-74-21.t-48d26ca8.kinesisvideo.us-east-1.amazonaws.com:443?transport=udp",
                    "turns:54-85-74-21.t-48d26ca8.kinesisvideo.us-east-1.amazonaws.com:443?transport=tcp"
                ],
                "username": "1709285761:djE6YXJuOmderpraW5lc2lzdmlkZW86dXMtZWFzdC0xOjUyNjE0MTg2NzMxMjpjaGFubmVsLzIyNzpurpAzMTlfYmUwZTNlZjEtY2YxMi00MzUwLWJkYzItY2U1MjY2YmRiODM4LzE3MDc1MDA3NTM3MDY=",
                "credential": "r07PxXkRJO/wdMhdsatDI/Ptdsdso1Tar/U1GRoCEjAY="
            },
            {
                "urls": [
                    "turn:54-83-80-165.t-48d26ca8.kinesisvideo.us-east-1.amazonaws.com:443?transport=udp",
                    "turns:54-83-80-165.t-48d26ca8.kinesisvideo.us-east-1.amazonaws.com:443?transport=udp",
                    "turns:54-83-80-165.t-48d26ca8.kinesisvideo.us-east-1.amazonaws.com:443?transport=tcp"
                ],
                "username": "1709285761:djE6YXJuOmderpraW5lc2lzdmlkZW86dXMtZWFzdC0xOjUyNjE0MTg2NzMxMjpjaGFubmVsLzIyNzpurpAzMTlfYmUwZTNlZjEtY2YxMi00MzUwLWJkYzItY2U1MjY2YmRiODM4LzE3MDc1MDA3NTM3MDY=",
                "credential": "r07PxXkRJO/wdMhdsatDI/Ptdsdso1Tar/U1GRoCEjAY="
            }
        ],
        "endpoints": [
            {
                "Protocol": "HTTPS",
                "ResourceEndpoint": "https://r-13e2a5fc.kinesisvideo.us-east-1.amazonaws.com"
            },
            {
                "Protocol": "WSS",
                "ResourceEndpoint": "wss://v-ef08a1db.kinesisvideo.us-east-1.amazonaws.com"
            }
        ],
        "signed": [
            "{\"service\":\"kinesisvideo\",\"host\":\"https://r-13e2a5fc.kinesisvideo.us-east-1.amazonaws.com\",\"headers\":{\"X-Amz-ChannelARN\":\"arn:aws:kinesisvideo:us-east-1:526141867312:channel/2274360319_be0e3ef1-cf12-4350-bdc2-ce5266bdb838/1707500753706\",\"X-Amz-ClientId\":\"VIEWER-FOR-CHANNELarn:aws:kinesisvideo:us-east-1:526141867312:channel/2274360319_be0e3ef1-cf12-4350-bdc2-ce5266bdb838/1707500753706\",\"Host\":\"https://r-13e2a5fc.kinesisvideo.us-east-1.amazonaws.com\",\"X-Amz-Date\":\"20240229T173111Z\",\"Authorization\":\"AWS4-HMAC-SHA256 Credential=undefined/20240229/us-east-1/kinesisvideo/aws4_request, SignedHeaders=host;x-amz-channelarn;x-amz-clientid;x-amz-date, Signature=52...019\"},\"path\":\"/\"}",
            "{\"service\":\"kinesisvideo\",\"host\":\"wss://v-ef08a1db.kinesisvideo.us-east-1.amazonaws.com\",\"headers\":{\"X-Amz-ChannelARN\":\"arn:aws:kinesisvideo:us-east-1:526141867312:channel/2274360319_be0e3ef1-cf12-4350-bdc2-ce5266bdb838/1707500753706\",\"X-Amz-ClientId\":\"VIEWER-FOR-CHANNELarn:aws:kinesisvideo:us-east-1:526141867312:channel/2274360319_be0e3ef1-cf12-4350-bdc2-ce5266bdb838/1707500753706\",\"Host\":\"wss://v-ef08a1db.kinesisvideo.us-east-1.amazonaws.com\",\"X-Amz-Date\":\"20240229T173111Z\",\"Authorization\":\"AWS4-HMAC-SHA256 Credential=undefined/20240229/us-east-1/kinesisvideo/aws4_request, SignedHeaders=host;x-amz-channelarn;x-amz-clientid;x-amz-date, Signature=c764....e86\"},\"path\":\"/\"}"
        ],
        "channelARN": "arn:aws:kinesisvideo:us-east-1:526141867312:channel/2274360319_be0e3ef1-cf12-4350-bdc2-ce5266bdb838/1707500753706",
        "credentials": {
            "AccessKeyId": "ASIA...",
            "SecretAccessKey": "zNo1.....FThrG",
            "SessionToken": "FwoGZXI.....F3w==",
            "Expiration": "2024-02-29T18:31:11.000Z"
        },
        "aws_region": "us-east-1",
        "signedWSS": "wss://v-ef08a1db.kinesisvideo.us-east-1.amazonaws.com/?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAXVAD7YUYDYGZKOJN/20240229/us-east-1/kinesisvideo/aws4_request&X-Amz-Date=20240229T173111Z&X-Amz-Expires=299&X-Amz-Security-Token=FwoG...RF3w==&X-Amz-Signature=93e1163afa4f2e7c9512e2ab5d8aea12015e502ec56b9592f1e20726cfe550e1&X-Amz-SignedHeaders=host",
        "signedHTTPS": "https://r-13e2a5fc.kinesisvideo.us-east-1.amazonaws.com/?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAXVAD7YUYDYGZKOJN/20240229/us-east-1/kinesisvideo/aws4_request&X-Amz-Date=20240229T173111Z&X-Amz-Expires=299&X-Amz-Security-Token=FwoG...RF3w==&X-Amz-Signature=40045810959904eaf4e8f271566b062e70edb5ed04f2c36fdc96e8b003190c09&X-Amz-SignedHeaders=host"
    }
Authorizations:
bearerAuth

Responses

End Live Call

End WebRTC Streaming

Instructs the SkyBell device to end any running live stream, stop any running recording, and finalize any running event (eg: upload the video).

Requirements

  • Logged in user, JWT token provided in header.
  • Device provisioned, online, and reachable by the internet.

Request Body

(none)

Example Response

This endpoint will always return true even if the device did not have anything to end or stop.

{
    "error": false,
    "message": "Ended stream",
    "data": false
}

Responses

Update Settings

Update Settings for Device

This endpoint allows logged in users to modify settings on their devices. In addition to saving the value in the cloud database it also dispatches an MQTT message to the device telling it to update settings.
If the device is not online, it will retrieve the updated settings automatically as soon as it comes online next.

Settings can be sent individually, only provided settings will be updated. (eg: There is no need to send the whole settings object up, just the values you wish to update).

Requirements

  • Logged in user, JWT token provided in header.

  • Device provisioned, online, and reachable by the internet.

Request Body

  • device_name - String (default "Front Door") -

  • time_zone - String (default EST5EDT,M3.2.0,M11.1.0) - Timezone in POSIX timezone format. For more information see details on the TZ variable.

  • led_color - String (default #00FF00) - A hexidecimal RGB value used to set the device LED color.

  • brightness - Number (default 0) - The brightness of the SkyBell LED. Supports SkyBell legacy style values where: 0 = low, 1 = medium, 2 = high. Also supports more more granular control by using a value at or above 3 and under 1000 expressed as percentage (0.3% and 100.0% respectively).

  • indoor_chime - Boolean (default true) - Enable or disable a mechanical indoor chime.

  • digital_chime - Boolean (default false) - Enable or disable a digital indoor chime.

  • outdoor_chime - Boolean (default true) - Enable or disable the SkyBell device speaker

  • outdoor_chime_volume - Number (default 0) - Volume of the speaker on the SkyBell device. Values can be:0 = low, 1 = medium, 2 = highOn SkyBell Chime devices, you can use a more granular scale. The values 0 - 3 work as described however you can also set a percentage based value 4 - 99 this is specific for Chime devices, NOT doorbells.

  • motion_detection - Boolean (default true) - Enable or disable trigger event/recording when motion is detected

  • debug_motion_detect - Boolean (default false) - Draws boxes around detected motion. These boxes are on both the live view and saved videos.

  • motion_sensitivity - Number (default 50 (very low)) - Motion detection sensitivity. Higher values mean more events will match (potentially leading to more false detections - adjust this value accordingly). Supports SkyBell legacy style values where: 0 = low, 1 = medium, 2 = high. Also supports more more granular control by using a value at or above 3 and under 1000 expressed as percentage (0.3% and 100.0% respectively).

  • hmbd_sensitivity - Number (default 0xFFFFFFFF) - Human Motion Body Detection sensitivity. If this value is not set or set to 4294967295 (0xFFFFFFFF) motion_sensitivity value is used instead! Higher values mean more events will match (potentially leading to more false detections - adjust this value accordingly). Supports SkyBell legacy style values where: 0 = low, 1 = medium, 2 = high. Also supports more more granular control by using a value at or above 3 and under 1000 expressed as percentage (0.3% and 100.0% respectively).

  • fd_sensitivity - Number (default 0xFFFFFFFF) - Facial detection sensitivity. If this value is not set or set to 4294967295 (0xFFFFFFFF) motion_sensitivity value is used instead! Higher values mean more events will match (potentially leading to more false detections - adjust this value accordingly). Supports SkyBell legacy style values where: 0 = low, 1 = medium, 2 = high. Also supports more more granular control by using a value at or above 3 and under 1000 expressed as percentage (0.3% and 100.0% respectively).

  • fr_sensitivity - Number (default 500) - Facial recognition sensitivity. Granular control by using a value between 0 and 1000 expressed as percentage (0% and 100.0% respectively).

  • image_quality - Number (default 0) - The quality to set the camera sensor to. This impacts all aspects of video. Values 0 - 3 correspond to resolutions: 0 is 480p, 1 is 720p low, 2 is 720p high, and 3 is 1080p

  • video_rotation - Number (default 0) - Rotate the way your SkyBell shoots video.

  • speaker_volume - Number (default 0) - This is the volume of the speaker during live streams. Only 3 volume levels are supported: 0 is low, 1 is medium and, 2 is high volume.

  • chime_file - String (default 1.wav), enum (One of: (user.wav, 1.wav, 2.wav, 3.wav, 4.wav, 5.wav, 8.wav, 9.wav, cartoon-melodic-bell.wav, home.wav, modern.wav, onemomentplease.wav, single-press.wav, wifi_ring.wav ) - Select the tone the SkyBell will play upon a button press. Set to user.wav to use a user uploaded tone.

  • motion_zone_config - Object - The motion zone configuration object. Please see next paragraph for details.

Motion Zone Config Object

Motion zones allow users to block out sections of their cameras from motion detection events.

The API to do this is very flexible. SkyBell recommends a default grid size of 8 x 5. However you can go higher or lower (upper ranges have not been tested beyond 10x10, use at your own risk).

The settings object for a very simple motion zone grid of 3x2 (that doesn't actually block out any motion yet) looks like this:

{
    "motion_zone_config": {
                "x": 3,
                "y": 2,
                "zones": [
                    [{"ignore": false, "sensitivity": 100}, {"ignore": false, "sensitivity": 100}, {"ignore": false, "sensitivity": 100}]
                    [{"ignore": false, "sensitivity": 100}, {"ignore": false, "sensitivity": 100}, {"ignore": false, "sensitivity": 100}]
                ],
                "threshold": 1
}

You can see that all 6 parts of our 3x2 grid have been represented in the zones property, each with their own {"ignore": false, "sensitivity": 100} object. To disable motion tracking on that part of your grid, simply set the ignore property of its object to true.

So to block out the upper left most part of our 3x2 grid use an object like:

{
    "motion_zone_config": {
                "x": 3,
                "y": 2,
                "zones": [
                    [{"ignore": false, "sensitivity": 100}, {"ignore": false, "sensitivity": 100}, {"ignore": false, "sensitivity": 100}]
                    [{"ignore": true, "sensitivity": 100}, {"ignore": false, "sensitivity": 100}, {"ignore": false, "sensitivity": 100}]
                ],
                "threshold": 1
}

Since SkyBell uses a default grid of 8x5, the resulting motion_zone_config object is quite large, that's OK and to be expected.

Finally, setting the threshold value to anything above 1 will instruct the device to wait for that number of boxes all having motion before triggering a motion alert.

Example Request Body

Change the SkyBell LED to magenta:

{"led_color": "#FF00FF"}

Turn all the Chimes to off/silent.

{
    "indoor_chime": false,
    "digital_chime": false,
    "outdoor_chime": false,
    "skybell_chime": false
}

Example Response

{
    "error": false,
    "message": "OK",
    "data": {}
}
header Parameters
Authorization
string
Example: {{ACTIVE_JWT_TOKEN}}
Content-Type
string
Example: application/json
Request Body schema: */*
string

Responses

List Devices

List Devices

List all the devices for the currently logged in user.

Requirements

  • Logged in user, JWT token provided in header.

  • Device provisioned, online, and reachable by the internet.

Query Parameters

  • limit - Number - The limit of devices to return (default: 50). Typically used for pagination.

  • offset - Number - Start listing devices from this provided number instead of the default of 0. Typically used for pagination.

Example Response

{
    "error": false,
    "message": "OK",
    "data": {
        "count": 1,
        "rows": [
            {
                "device_id": "b14b2fa8-2969-4cf0-aba7-17d38b64882b",
                "client_id": "7bc989e6-9459-4582-a518-1174dc5fee71",
                "account_id": "33dae2fb-499a-496c-88b5-897da608a04a",
                "serial": "A3BAB00473",
                "certificate_id": "711b0ae35767e0f5bc13be95d1438f4ca96eef6972ab05f66c5f30e170d808f7",
                "hardware": "Ver A:SB_TRIM2_0001",
                "firmware": "0.5.11",
                "invite_token": "rAVtAmkwIuljhZxHXxuBqG4dpZr7Ge1oVetqPqecMWxrOvGmvDVocVkY7AKXNHRtocs4tBskYxo0cQlZTYqRlyUeSKv4Q2O0iBSu2u6MO77APxmmdzEB0B2Q5IJ2L8d3",
                "last_event": "1650578210829",
                "last_connected": "2022-04-21T21:32:32.825Z",
                "last_disconnected": "2022-04-21T18:25:36.569Z",
                "lat": null,
                "lon": null,
                "name": "Front Door",
                "settings": {
                    "led_color": "#0055CC"
                },
                "device_settings": {
                    "ESSID": "chimeinternet",
                    "OTA_type": null,
                    "model_rev": "SB_TRIM2_0001",
                    "MAC_address": "9C:54:DA:10:D7:7E",
                    "OTA_version": null,
                    "OTA_signature": null,
                    "serial_number": "A3BAB00473",
                    "firmware_patch": 11,
                    "firmware_version": "0.5.11",
                    "hardware_version": "Ver A",
                    "firmware_major_release": 0
                },
                "manufactured": null,
                "created_at": "2022-04-12T14:28:40.672Z",
                "updated_at": "2022-04-21T21:56:50.829Z"
            },
            {
              "another": "device",
                "body": "similar",
                "to": "sibling"
            }
        ],
        "limit": 50,
        "offset": 0
    }
}
Authorizations:
bearerAuth

Responses

Single Device

Get Single Device Details

Returns all the details, settings, and last check-in information for the provided Device ID (assuming a valid JWT token has allowed access).

Requirements

  • Logged in user, JWT token provided in header.

Example Response

{
    "error": false,
    "message": "OK",
    "data": {
        "device_id": "b14b2fa8-2969-4cf0-aba7-17d38b64882b",
        "client_id": "7bc989e6-9459-4582-a518-1174dc5fee71",
        "account_id": "33dae2fb-499a-496c-88b5-897da608a04a",
        "serial": "A3BAB00473",
        "certificate_id": "711b0ae35767e0f5bc13be95d1438f4ca96eef6972ab05f66c5f30e170d808f7",
        "hardware": "Ver A:SB_TRIM2_0001",
        "firmware": "0.5.11",
        "invite_token": "rAVtAmkwIuljhZxHXxuBqG4dpZr7Ge1oVetqPqecMWxrOvGmvDVocVkY7AKXNHRtocs4tBskYxo0cQlZTYqRlyUeSKv4Q2O0iBSu2u6MO77APxmmdzEB0B2Q5IJ2L8d3",
        "last_event": null,
        "last_connected": "2022-04-12T14:28:41.793Z",
        "last_disconnected": null,
        "lat": null,
        "lon": null,
        "name": "Front Door",
        "settings": {
            "device_id": "",
            "led_color": "#00ff00",
            "account_id": "",
            "brightness": 0,
            "chime_file": "user.wav",
            "force_turn": false,
            "device_name": "Front Door",
            "indoor_chime": true,
            "digital_chime": false,
            "image_quality": 0,
            "outdoor_chime": true,
            "skybell_chime": true,
            "button_pressed": true,
            "event_duration": 30,
            "fd_sensitivity": 500,
            "fr_sensitivity": 500,
            "speaker_volume": 0,
            "video_datetime": true,
            "video_rotation": 0,
            "hmbd_sensitivity": 500,
            "motion_detection": false,
            "audio_cmd_enabled": false,
            "motion_sensitivity": 50,
            "motion_zone_config": {
                "x": 8,
                "y": 5,
                "zones": ["..."],
                "threshold": 1
            },
            "audio_alarm_enabled": false,
            "debug_motion_detect": false,
            "outdoor_chime_volume": 0
        },
        "device_settings": {
            "ESSID": "chimeinternet",
            "OTA_type": null,
            "model_rev": "SB_TRIM2_0001",
            "MAC_address": "9C:54:DA:10:D7:7E",
            "OTA_version": null,
            "OTA_signature": null,
            "serial_number": "A3BAB00473",
            "firmware_patch": 11,
            "firmware_version": "0.5.11",
            "hardware_version": "Ver A",
            "firmware_major_release": 0
        },
        "manufactured": null,
        "created_at": "2022-04-12T14:28:40.672Z",
        "updated_at": "2022-04-12T14:30:35.328Z",
        "telemetry": {
            "uptime": 12674,
            "boot_time": 1649773647,
            "timestamp": 1649786322438,
            "wifi_noise": "-100",
            "link_quality": "89/100",
            "signal_level": "-38",
            "wifi_bit_rate": "54",
            "network_frequency": "2.437"
        }
    }
}

Responses

Delete Device

Remove Device from Account

Removes the device from a users account and deletes all associated device resources (MQTT certificates, device shares) except old activities. Before removing the device the SkyBell cloud sends a Factory Reset command to the device to set it back to initial settings.

Requirements

  • Logged in user, JWT token provided in header.

Example Response

{
    error: false,
        message: "OK. Device deleted.",
        data: null
}

Responses

Image Snapshot

Get Device Snapshot

This endpoint calls the provided Device ID and requests a new image snapshot. The image is returned in the response body as a JPEG base64 encoded string.

Requirements

  • Logged in user, JWT token provided in header.
  • Device provisioned, online, and reachable by the internet.

Example Response

{
    "error": false,
    "message": "OK",
    "data": {
        "date_time": "2022-04-12T18:18:31.000Z",
        "preview": "ThisWillBeAVeryVeryVeryLargeStringThatYouCanBase64DecodeIntoAJpeg"
    }
}

Responses

Reboot Device

Send Doorbell Reboot Command

This endpoint instructs the cloud to send the device a reboot command. 10 - 60 seconds after getting a 200 response from this endpoint, the specified Device ID will reboot.

Requirements

  • Logged in user, JWT token provided in header.
  • Device provisioned, online, and reachable by the internet.

Example Response

{
    "error": false,
    "message": "OK, sent reboot command.",
    "data": {}
}

Responses

Device > Triggers

Triggers are what create new webhooks for events. Triggers are used by SkyBell partners to call other services. Webhooks, Alexa, and Google Home are all set up within "Triggers".

Webhook Trigger Payload

After setting up your trigger, the SkyBell will make a web request to the address you specified, using the method in the trigger, and any custom header/value you may have also defined when you created the trigger.

Webhook Payload Examples

Depending on the type of events subscribed, you may recieve different payload contents. Please note that only webhooks configured with POST requests will contain a payload body.

Doorbell motion, or button press

If a snapshot is available it will be included on the preview property as a string base64 encoded JPEG. Despite including a small image, the full JSON payload is usually only around 15-25 kB

{
  "event": "doorbell",
  "date_time": 1706025131324,
  "device_id": "751e37fa-2d43-4c98-9f6e-73db52f7f741",
  "name": "Front Door",
  "preview": "/A-Base64-Encoded-JPEG-Snapshot-String=",
  "activity_id": "36709519-97bc-42c6-b398-166dbfb5a3ae"
}
User/Mobile-App Requested Live Stream

If you have subscribed to the "lstream" event you will get webhook notifications whenever the user requests a live stream from that device. Due to the nature of the live stream event, no image preview or activity_id will be sent.

{
  "event": "lstream",
  "date_time": "2024-01-23T15:39:21.192Z",
  "device_id": "751e37fa-2d43-4c98-9f6e-73db52f7f741",
  "name": "SkyGuardian",
  "detail": {
    "state": "lstream",
    "device": "751e37fa-2d43-4c98-9f6e-73db52f7f741"
  }
}
Doorbell telemetry

The SkyBell device occasionally sends hardware information while it is connected to the SkyBell network. This information is used to troubleshoot customer service issues, and to ensure devices stated up to date with the latest firmware.

{
  "event": "telemetry",
  "date_time": "2023-11-28T22:02:27.586Z",
  "device_id": "751e37fa-2d43-4c98-9f6e-73db52f7f741",
  "name": "Front Door",
  "detail": {
    "gateway": "192.168.2.1",
    "signal_level": "-18",
    "wifi_bit_rate": "VHT2MCS5/VHT2MCS8 20MHz LGI",
    "link_quality": "88/100",
    "wifi_noise": "-100",
    "network_frequency": "2.432",
    "boot_time": 1704750069,
    "uptime": 1276,
    "timestamp": 1704751347283,
    "ip_address": "192.168.2.204",
    "ip_address_public": "163.250.165.212",
    "ip_subnet": "255.255.255.0"
  }
}
Doorbell availability

This webhook will fire if the device is disconnected from, or reconnected to, the internal SkyBell MQTT system. Please note that "disconnected" events take at least 40 seconds, usually around 1 minute, to actually fire once a doorbells internet connection becomes unavailable. "connected" events however, typically happen very quickly upon the device recovering internet access.

{
  "event": "availability",
  "date_time": "2024-01-08T21:41:46.958Z",
  "device_id": "751e37fa-2d43-4c98-9f6e-73db52f7f741",
  "name": "Front Door",
  "detail": {"state": "connected"}
}
New Video Activity Processed

The "vready" webhook will fire when the subscribed device has just had a successful activity upload from a live stream, button push, or motion doorbell event.

{
  "event": "vready",
  "date_time": "2024-01-31T17:34:37.846Z",
  "device_id": "a7b8da44-ed49-4a9b-9201-84c97fc60f59",
  "name": "Front Door",
  "detail": {
    "activity_id": "99facb31-0c35-4518-afe9-3e3cf29571d6",
    "size": 644483,
    "device_id": "a7b8da44-ed49-4a9b-9201-84c97fc60f59"
  }
}
Doorbell OTA and "SkyBell HD" Migration

The "ota" event will fire the webhook trigger upon the start, and the finish of any SkyBell OTA. The three values for the detail.status property you should expect are: "QUEUED", "SUCCEEDED", and (hopefully never but prepare) "FAILED"

{
  "event": "ota",
  "date_time": "2024-01-08T22:23:37.401Z",
  "device_id": "751e37fa-2d43-4c98-9f6e-73db52f7f741",
  "name": "Front Door",
  "detail": {
    "status": "SUCCEEDED",
    "version": "1.3.8"
  }
}
Doorbell Deleted

The "devicedeleted" event will fire the webhook trigger when a user manually deletes their device from the SkyBell app. It is important to note that this event only fires when a user deletes their device. It will not fire when they do a factory-reset by pressing and holding the SkyBell button.

{
  "event": "devicedeleted",
  "date_time": "2024-01-27T15:39:21.192Z",
  "device_id": "751e37fa-2d43-4c98-9f6e-73db52f7f741",
  "detail": {
    "state": "devicedeleted",
    "device": "751e37fa-2d43-4c98-9f6e-73db52f7f741"
  }
}

New Trigger

Create a Trigger

Create a new SkyBell Trigger that calls a third party service with a Webhook.

Request Body

  • type - String - What kind of Trigger is this. Must be one of: "webhook", "ifttt", "google", "amazon". If you are calling this API you want "webhook".

  • events - Array (at least 1 expected) - The SkyBell events that will call this Trigger. Defaults to all events if not provided. Array may only contain these strings: "lstream", "doorbell", "motion", "telemetry", "availability", "ota", and "vready"
    What each event is:

    • "doorbell" and "motion" - Actual doorbell button press and motion events.

    • "lstream" - When a user completes a live stream request from the mobile app

    • "telemetry" - SkyBell devices checkin with the SkyBell platform every hour.

    • "availability" - This event will trigger the webhook anytime the device goes offline or comes online to the internal SkyBell MQTT network.

    • "ota" - This event will trigger a webhook upon the device doing any firmware Over The Air update events.

    • "vready" - After an activity completes uploading to the SkyBell servers, this trigger event is fired indicating to any listeners that an activity video is ready for download

    • "devicedelete" - This event will fire right before the device is deleted from the SkyBell platform. After this event you can expect that the provided device (by ID) and all data associated with that device are not longer available. This event starts when a user manually chooses to delete their device. It will not fire if the device is manually factory reset via a hold-down button push without being deleted first.

  • url - String - The URL of the webhook for this SkyBell Trigger to call

  • method - String enum (get, post) - The HTTP method to use when calling the URL. Must be one of: "get" or "post"

  • header_name - String (optional) - If provided SkyBell will call this webhook with a custom HTTP header. This is the name for that header.

  • header_value - String (optional) - If provided SkyBell will call this webhook with a custom HTTP header. This is the value for that header.

For example a to create a webhook that is called on motion events:

{
    "type": "webhook",
    "url": "https://api.example.com/api/v2/skybelltest",
    "method": "post",
    "header_name": "x-test-header",
    "header_value": "special header information",
    "events": ["motion"]
}

Example Response

{
    "error": false,
    "message": "Webhook trigger created.",
    "data": {
        "trigger_id": "fd6b5a3c-d674-4e89-a93e-f7b8e3c6788e",
        "client_id": "7bc989e6-9459-4582-a518-1174dc5fee71",
        "enabled": true,
        "fail_count": 0,
        "device_id": "b14b2fa8-2969-4cf0-aba7-17d38b64882b",
        "type": "webhook",
        "meta_config": {
            "url": "https://api.example.com/api/v2/skybelltest",
            "method": "get",
            "header_name": "x-test-header",
            "header_value": "special header information"
        },
        "on_events": [
            "lstream",
            "motion",
            "doorbell"
        ],
        "updated_at": "2022-04-12T17:31:12.491Z",
        "created_at": "2022-04-12T17:31:12.491Z"
    }
}
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "type": "webhook",
  • "url": "https://webhook.site/SkyBellWHTest",
  • "method": "post",
  • "header_name": "x-hyper-awesome",
  • "header_value": "enabled hyper awesome mode",
  • "events": [
    ]
}

List Triggers

List Triggers

List any triggers this user has enabled: webhooks, Kwikset, Alexa, Google Home, and IFTTT connections will be listed here.

If the trigger was disabled by the SkyBell API (which happens automatically after 25 failures in a row) the disabled trigger witll have "disabled_on" and "disabled_reason" properties. Editing triggers is not yet supported, so a disabled trigger (or any trigger you wish to modify) must be deleted and recreated.

Example Response

{
    "error": false,
    "message": "OK",
    "data": [
        {
            "trigger_id": "47f47f5c-babb-43d8-997c-cfbb98ccc4ce",
            "device_id": "751e37fa-2d43-4c98-9f6e-73db52f7f741",
            "account_id": "33dae2fb-499a-496c-88b5-897da608a04a",
            "client_id": "7bc989e6-9459-4582-a518-1174dc5fee71",
            "type": "webhook",
            "enabled": true,
            "on_events": [
                "lstream",
                "motion",
                "doorbell",
                "ota",
                "availability",
                "telemetry"
            ],
            "fail_count": 0,
            "created_at": "2024-01-08T21:02:45.205Z",
            "updated_at": "2024-01-08T21:02:45.205Z"
        }
    ]
}

Responses

Delete Trigger

Delete Trigger

Deletes the provided trigger so they no longer fire when their event is triggered. This is the API to use if you want to disable IFTTT, Alexa, or Google Home. Or if you want to remove an HTTP(s) webhook.

Requirements

  • Logged in user, JWT token provided in header.
  • Device provisioned, online, and reachable by the internet.

Request Body

(none)

Example Response

{
    "error": false,
    "message": "OK - trigger deleted",
    "data": true
}

Responses

Device > Provisioning

API endpoints within this folder are for provisioning a new SkyBell device.

If you are setting up an older SkyBell device it will come loaded with legacy SkyBell HD firmware and you will need to follow directions for provisioning an older device.

Step 1: Request Provision Invite

Device Provision Tokens

This endpoint does a few things:

  1. Gets a fresh device provisioning token from the cloud that can be passed along to an unprovisoned device to use as the first part of the device provisioning process. This token is used to identify who this device belongs to when the device itself reaches out to the cloud to get set up. This is what the "data.token" property is.

  2. Gets a fresh legacy device provisioning and limited-use access code for use in provisioning CoAP based legacy SkyBell HD devices. Two CoAP commands will have to be sent to the device when provisioning. Please see "Step 3: (SkyBell HD device) Provide WiFi Credentials" for more detail on how to send these over CoAP.

Requirements

  • Logged in user, JWT token provided in header.

  • Device provisioned, online, and reachable by the internet.

Example Response

In this response, the user has a Chime device set up on their account with the serial number "A5DCA00000". You can see this value as a property key in the .data JSON with the PSK as the value.

{
    "error": false,
    "message": "OK",
    "data": {
        "token": "128randomAlphaNumericCharacters",
        "account_id": "UUID_OF_USER",
        "chimes": {
            "A5DCA00000": "63randomAlphaNumericCharacters"
        },
        "legacy": {
            "invite": "64randomAlphaNumericCharacters",
            "access": "256randomHexidecimalCharacters"
        }
    }
}

Responses

Step 2: Get Available WiFi SSIDs

Query Device for Available Wifi

In Access Point (AP) mode (device is blinking RED/GREEN and allows a WiFi connection on an SSID starting with SkyBell_) the device regularly scans for available networks that it can join.

Once connected to the doorbell itself you can make a request to this endpoint. Notice this is a regular HTTP request happening only on the local network.

Requirements

  • Connected to SkyBell device in AP mode (eg: You have an IP address assigned to you starting with 192.168.4.)

Example Response

Provide this list of available networks to your end user for them to choose the network the want to join.

{
  "ssid": [
    {"essid": "wifiname", "mac": "BA:D0:BE:EE:FE", "channel": 7, "signal_level": -80, "security": "wpa"},
    {"essid": "differentwifi", "mac": "44:55:BE:EE:FE", "channel": 5, "signal_level": -66, "security": "wpa2"},
  ]
}

Responses

Step 2: (SkyBell HD/Legacy) Get Available WiFi SSIDs

Query Device for Available Wifi

In Access Point (AP) mode (device is blinking RED/GREEN and allows a WiFi connection on an SSID starting with SkyBellHD_) the device regularly scans for available networks that it can join. However this device is running the old legacy SkyBell HD platform and can only be interacted with via CoAP.

Once connected to the doorbell itself you can make a request to this endpoint. Notice this is a regular CoAP request happening only on your local network.

Requirements

  • Connected to SkyBell device in AP mode (eg: You have an IP address assigned to you starting with 192.168.4.)

Example CoAP Request

{
  "code": 2.15,
  "confirmable": true,
  "payload": "",
  "options": [
    {"name": "Uri-Host", "value": "192.168.1.1"},
    {"name": "Uri-Port", "value": "5683"},
    {"name": "Uri-Path", "value": "apscan"},
    {"name": "Content-Format", "value": "application/json"},
]}

Example Response

Provide this list of available networks to your end user for them to choose the network the want to join.

Note that while they look similar the SkyBell Gen5 endpoint will return "essid" properties, but this endpoint returns "ssid" properties.

{
  "aplist": [
    {"ssid": "wifiname", "mac": "BA:D0:BE:EE:FE", "channel": 7, "signal_level": -80, "security": "wpa"},
    {"ssid": "differentwifi", "mac": "44:55:BE:EE:FE", "channel": 5, "signal_level": -66, "security": "wpa2"},
  ]
}

Example Node.js Code Making CoAP Request

// In this Node.js Promise, we will send a CoAP request and wait for a response
// We will use the library "coap-packet" to generate our request
// We will use Node.js native "dgram" to wait for the CoAP (a UDP protocol) response
// Many other CoAP libraries exist and can offer you much more control over the process
const apScanWithCoAP = () => new Promise((resolve, reject) => {
  // Create the socket we will listen to for the CoAP response
  const socket = dgram.createSocket({
    type: "udp4",
    debug: true, // Optional
  });

  // Here's the data structure that we will convert into a CoAP UDP packet
  const payloadJSON = {
    code: 2.15,
    confirmable: true,
    payload: Buffer.from(""),
    options: [
      {"name": "Uri-Host", "value": "192.168.1.1"},
      {"name": "Uri-Port", "value": "5683"},
      {"name": "Uri-Path", "value": "apscan"},
      {"name": "Content-Format", "value": "application/json"},
  ]};

  // Generate the packet
  const CoAPPacket = packet.generate(payloadJSON);
  
  // Bind the socket we set up to the CoAP port of 5683
  try {
    socket.bind(5683);
  } catch (bindER) {
    console.error(bindER);

    return reject("Could not bined to port 5683 to listen for CoAP response!");
  }
  // Start listening for a CoAP response
  socket.once("listening", function() {
    // Once we're listening, actually send the CoAP data packet to the device
    socket.send(CoAPPacket, 0, CoAPPacket.length, 5683, "192.168.1.1", function(err) {
      if (err) {
        console.error("CoAPClient error: " + err.message);

        return reject("Problem setting up to listen for a provisioning response.");
      }
      console.log("CoAP data sent:", payloadJSON);
    });
  });
  // Handle the socket response incoming message. This will have the devices response.
  socket.on("message", function(msg, rinfo) {
    try {
      // Parse the CoAP packet back into JSON
      let response = packet.parse(msg);
      // The Payload comes in as a buffer but we need it to first be a string, then parse it into JSON too
      response.payload = Buffer.from(response.payload).toString();
      console.log("got coap apscan resp:", response.payload);
      try {
        // Parse string into JSON
        response.payload = JSON.parse(response.payload);
      } catch (er){
        console.log("Failed to parse coap resp, may not be JSON:", response.payload, er);
      }

      // We can expect a uuid on the payload, if it's not there something has gone wrong
      if (response?.payload?.uuid){
        // Close our socket now that we're done
        if (socket.close){
          socket.close();
        }
        // Finally return the response data
        return resolve(response.payload);
      } else {
        console.error("Unexpected response from device after payload: ", response.payload, response);

        // Close our socket now that we've hit an error
        if (socket.close){
          socket.close();
        }

        return reject("Unexpected response from device, try restarting it and trying again.");
      }
       
    } catch (er){
      console.log("Error doing coapstuff:", er);

      return reject("Problems communicating, try restarting it and trying again.");
    }
  });
});

Responses

Step 3: Provide Device WiFi Credentials

Bring SkyBell Device Online

Sending this request to the device will kick off the rest of the provisioning process for a device.

Requirements

  • Connected to SkyBell device in AP mode (eg: You have an IP address assigned to you starting with 192.168.4.)

Request Body

  • invite - String - A valid invite token obtained from the cloud with a registered user (see Step 1 GET /api/v5/devices/provision)

  • backend_num - Number enum(0, 1, 2, 3, 4) - What backend cloud environment to use. Unless otherwise instructed, use SkyBell the production cloud which is 2 - unless you have access to the SkyBell Dev (3), SkyBell Staging (1), or SkyBell Resideo ( 4 ) environments.

  • security - Object (optional) - Allow connection to WiFi networks that require certificates.

  • network - Object

    • wireless_type - String enum("wpa", "wpa2", "wep", "auto") - The network security type of the wifi network
      • essid - String - The name of the wifi network to connect to
    • psk - String, - The password or pre-shared-key of the wifi network to connect to
    • wep_tx_keyidx - Number - Only needed if wireless_type is wep, or auto and encryption type is WEP
    • wep_key - String - Only needed if wireless_type is wep, or auto and encryption type is WEP
    • hidden_essid - Boolean - Is this a hidden network SSID or not?
    • ipconfig_type - String enum("manual" or "dhcp") - Tell device if this wifi network supports DHCP automatic IP assignment
    • static_ip - String - Only needed if ipconfig_type is manual. The static IP for the SkyBell device.
    • netmask - String - Only needed if ipconfig_type is manual. The Wifi network netmask.
    • gateway_ip - String - Only needed if ipconfig_type is manual. The Wifi gateway address.
    • dns1 - String - Only needed if ipconfig_type is manual. The DNS server to use on this wifi network.
    • dns2 - String - Only needed if ipconfig_type is manual. The DNS server to use on this wifi network.
    • country_code - String - Country code this device is installed in
{
  "backend_num": 2,
  "network": {
      "wireless_type": "wpa",
      "essid": "prettyflyforawifi",
      "psk": "dontellanyonemysecretpasswordplz",
      "hidden_essid": false,
      "ipconfig_type": "dhcp"
      "country_code": "us"
  },
  "invite": "avaliddeviceinvitetoken",
}

Response

The device will respond with an HTTP Status 200 before disconnecting you entirely. At this point you need to query the users GET /api/v5/devices to look for the new device. This process can take anywhere from 10 seconds up to 6 minutes.

Watching the LED pattern on the device can be useful to determine where it is in this process:

  • Blinking Orange - Looking for, or trying to connect to, the provided wifi network. If this never changes there's a good chance incorrect wifi network information was passed to the device OR the device is unable to establish a wifi link. No new device will be in GET /api/v5/devices
  • Blinking Blue/Green - The connection to the provided local wifi network has been successfully established and the SkyBell device is now doing the first connection exchange for keys. At this point the new device will appear in GET /api/v5/devices but it will have a null latest connection value. If the device stays in this mode chances are a cloud error has occured or the internet is not available on the wifi network.
  • Solid Green - Connected and ready. GET /api/v5/devices will show the new device AND it's latest connection time.

Responses

Step 3: (SkyBell HD/Legacy) Provide Device WiFi Credentials

Get SkyBell HD Device Online

Some older/legacy SkyBell devices may still come with SkyBell HD firmware installed. This endpoint will detail how to send the CoAP request then monitor the provision and upgrade progress. Sending this request to the device will kick off the rest of the provisioning process as well as an automatic upgrade of the legacy SkyBell HD device.

Unlike every other request in our API, this request must be made with the legacy CoAP protocol that the SkyBell HD system used to communicate with.

Legacy CoAP Provision

Devices that have SSID's that start with SkyBellHD_XXXXXXXXXX may be legacy devices that can only be set up with CoAP. Two CoAP requests will need to be sent to provision it. One setting the invite token, and then another one that sends the actual network info.

There are a variety of libraries available for you to choose from, you will not need a full CoAP implementation, we only need to send the two CoAP endpoints defined here. You can see an example of a CoAP request being made on the "Step 2: (SkyBell HD/Legacy) Get Available WiFi SSIDs" page.

CoAP Provision Invite Request Payload

Inside of the /api/v5/devices/hdprovision response you will get an HD/Legacy access token and invite token.

{
  "code": 2.15,
  "confirmable": true,
  "payload": "{\"token\": \"64AlphaNumericCharactersFromDeviceInviteResponse\"}",
  "options": [
    {"name": "Uri-Host", "value": "192.168.1.1"},
    {"name": "Uri-Port", "value": "5683"},
    {"name": "Uri-Path", "value": "invite_token"},
    {"name": "Content-Format", "value": "application/json"},
  ],
}

CoAP Send Provision Request Payload

  • essid - String - The name of the wifi network to connect to
  • psk - String, - The password or pre-shared-key of the wifi network to connect to
  • hidden_essid - Boolean (optional) - Is this a hidden network SSID or not?
  • static_ip - String (optional) - The static IP for the SkyBell device.
  • netmask - String (optional) - The Wifi network netmask.
  • gateway_ip - String (optional) - The Wifi gateway address.
{
  "code": 2.15,
  "confirmable": true,
  "payload": "{\"essid\": \"prettyflyforawifi\", \"psk\": \"dontellanyonemysecretpasswordplz\"}",
  "options": [
    {"name": "Uri-Host", "value": "192.168.1.1"},
    {"name": "Uri-Port", "value": "5683"},
    {"name": "Uri-Path", "value": "provision"},
    {"name": "Content-Format", "value": "application/json"},
  ],
}

Poll for Provision & Upgrade Status

Once the device responds to the CoAP provision request it will disconnect from your device entirely. From here you need to poll the POST /api/v5/hdprovision endpoint with the invite and access token provided to you from the /api/v5/devices/hdprovision response

{
    "legacy": {
        "invite": "64randomAlphaNumericCharacters",
        "access": "256randomHexidecimalCharacters"
    }
}

Poll for Provision & Upgrade Response

{
    "error": false,
    "message": "OK",
    "data": {
        "state": "requested"
    }
}

The response you get from polling will contain a state property that you can use to see where the provision & upgrade process is at.

You will get one of the following states:

  • "waiting" - The device is not yet available on any backend. Chances are that it is still connecting to the local WiFi network.

  • "legacyOnline" - The device has come online for the first time and will be sent the request to upgrade next

  • "requested" - The device has successfully requested the upgrade firmware

  • "migrationPending" - The device is being upgraded and should come online within 5 - 10 minutes. This state means the upgrade process has been completed and you may start polling the users GET /api/v5/devices endpoint to see if come online.

  • "problem" - The server has encountered a problem. The "message" property may have additional information. Typically this should never happen, but in the event that it does, simply wait 15 minutes and try to reprovision & upgrade the device again.

Responses

Device > On-Device Rules

Get Rules

Responses

Get Default Rules

Default Rule Engine Rule Sets

Get a list of available default rule sets from SkyBell. Note that this route does not require authentication.

Rules here can be applied using the POST /api/v5/devices/DEVICE_ID/rules route.

Example Response

{
    "error": false,
    "message": "Currently featured rules.",
    "data": {
        "Human Detection": {
            "rules": [
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 1
                        }
                    ],
                    "window": 0,
                    "actions": {
                        "pre_roll": true,
                        "pre_roll_duration": 10
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "HMBMotion",
                            "count": 1
                        }
                    ],
                    "window": 0,
                    "actions": {
                        "pre_roll": true,
                        "pre_roll_duration": 10
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "FDMotion",
                            "count": 1
                        }
                    ],
                    "window": 0,
                    "actions": {
                        "pre_roll": true,
                        "pre_roll_duration": 10
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 1
                        },
                        {
                            "event": "HMBMotion",
                            "count": 1
                        }
                    ],
                    "window": 10,
                    "actions": {
                        "notify": true,
                        "record": true,
                        "record_duration": 0
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 1
                        },
                        {
                            "event": "FDMotion",
                            "count": 1
                        }
                    ],
                    "window": 10,
                    "actions": {
                        "notify": true,
                        "record": true,
                        "record_duration": 0
                    }
                }
            ]
        },
        "Human Detection Debounce": {
            "rules": [
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 1
                        }
                    ],
                    "window": 0,
                    "actions": {
                        "pre_roll": true,
                        "pre_roll_duration": 10
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "HMBMotion",
                            "count": 1
                        }
                    ],
                    "window": 0,
                    "actions": {
                        "pre_roll": true,
                        "pre_roll_duration": 10
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "FDMotion",
                            "count": 1
                        }
                    ],
                    "window": 0,
                    "actions": {
                        "pre_roll": true,
                        "pre_roll_duration": 10
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 1
                        },
                        {
                            "event": "HMBMotion",
                            "count": 2
                        }
                    ],
                    "window": 10,
                    "actions": {
                        "notify": true,
                        "record": true,
                        "record_duration": 0
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 1
                        },
                        {
                            "event": "FDMotion",
                            "count": 2
                        }
                    ],
                    "window": 10,
                    "actions": {
                        "notify": true,
                        "record": true,
                        "record_duration": 0
                    }
                }
            ]
        },
        "Motion Only": {
            "rules": [
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 1
                        }
                    ],
                    "window": 0,
                    "actions": {
                        "notify": true,
                        "record": true,
                        "record_duration": 0
                    }
                }
            ]
        },
        "Human Detection Night Motion": {
            "rules": [
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 1
                        }
                    ],
                    "window": 0,
                    "actions": {
                        "pre_roll": true,
                        "pre_roll_duration": 10
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "HMBMotion",
                            "count": 1
                        }
                    ],
                    "window": 0,
                    "actions": {
                        "pre_roll": true,
                        "pre_roll_duration": 10
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "FDMotion",
                            "count": 1
                        }
                    ],
                    "window": 0,
                    "actions": {
                        "pre_roll": true,
                        "pre_roll_duration": 10
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 1
                        },
                        {
                            "event": "HMBMotion",
                            "count": 1
                        }
                    ],
                    "window": 10,
                    "actions": {
                        "notify": true,
                        "record": true,
                        "record_duration": 0
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 1
                        },
                        {
                            "event": "FDMotion",
                            "count": 1
                        }
                    ],
                    "window": 10,
                    "actions": {
                        "notify": true,
                        "record": true,
                        "record_duration": 0
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 3
                        }
                    ],
                    "window": 10,
                    "light_levels": [
                        "NightDark"
                    ],
                    "actions": {
                        "notify": true,
                        "record": true,
                        "record_duration": 0
                    }
                }
            ]
        },
        "Motion Only Alt": {
            "rules": [
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 1
                        }
                    ],
                    "window": 0,
                    "actions": {
                        "pre_roll": true,
                        "pre_roll_duration": 10
                    }
                },
                {
                    "triggers": [
                        {
                            "event": "PIRMotion",
                            "count": 2
                        }
                    ],
                    "window": 10,
                    "actions": {
                        "notify": true,
                        "record": true,
                        "record_duration": 0
                    }
                }
            ]
        }
    }
}

Responses

Device > Tones

Test Tone

Test Play Audio Tone

Plays the provided audio tone on the SkyBell device.

Requirements

  • Logged in user, JWT token provided in header.
  • Device provisioned, online, and reachable by the internet.
  • Near enough to the device to hear it

Request Body

  • file_name - String, enum (One of: (user.wav, 1.wav, 2.wav, 3.wav, 4.wav, 5.wav, 8.wav, 9.wav, cartoon-melodic-bell.wav, home.wav, modern.wav, onemomentplease.wav, single-press.wav, wifi_ring.wav )) - The test tone to play.

Example Response

{
    "error": false,
    "message": "Tested tone",
    "data": false
}
Request Body schema: */*
string

Responses

List Doorbell Tones

Get a list of available doorbell chime tones from SkyBell. Note that this route does not require authentication.

Example Response

{
    "error": false,
    "message": "Currently featured tones",
    "data": [
        {
            "url": "https://dlc.skybell.wtf/featured/skybell-cartoon-door-melodic-bell.wav",
            "size": 439718,
            "modified": "2022-06-13T23:34:55.000Z"
        },
        {
            "url": "https://dlc.skybell.wtf/featured/skybell-doorbell-single-press.wav",
            "size": 279260,
            "modified": "2022-06-13T23:34:56.000Z"
        },
        {
            "url": "https://dlc.skybell.wtf/featured/skybell-home-standard-ding-dong.wav",
            "size": 716462,
            "modified": "2022-06-13T23:34:57.000Z"
        },
        {
            "url": "https://dlc.skybell.wtf/featured/skybell-melodic-classic-door-bell.wav",
            "size": 1270952,
            "modified": "2022-06-13T23:34:56.000Z"
        },
        {
            "url": "https://dlc.skybell.wtf/featured/skybell-modern-classic-door-bell-sound.wav",
            "size": 522366,
            "modified": "2022-06-13T23:34:56.000Z"
        },
        {
            "url": "https://dlc.skybell.wtf/featured/theoffice_nooooo.wav",
            "size": 253598,
            "modified": "2022-06-13T23:40:50.000Z"
        },
        {
            "url": "https://dlc.skybell.wtf/featured/too_many_rings.wav",
            "size": 124310,
            "modified": "2022-06-13T23:40:51.000Z"
        }
    ]
}

Responses

List Chime Tones

Get Chime Tones

Get a list of available doorbell chime tones from SkyBell. Note that this route does not require authentication.

Example Response

{
    "error": false,
    "message": "Current tones for chime",
    "data":
    [
        {
            "url": "https://dlc.skybell.wtf/tones/chime/1950s_mechanical_doorbell.mp3",
            "size": 150913,
            "modified": "2023-05-22T18:13:09.000Z",
            "file": "1950s_mechanical_doorbell.mp3",
            "name": "1950s mechanical doorbell",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/357_unholster.mp3",
            "size": 35309,
            "modified": "2023-05-22T18:13:10.000Z",
            "file": "357_unholster.mp3",
            "name": "357 unholster",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/80s_synth.mp3",
            "size": 71612,
            "modified": "2023-05-22T18:13:10.000Z",
            "file": "80s_synth.mp3",
            "name": "80s synth",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/child_saying_i'm_here.mp3",
            "size": 27710,
            "modified": "2023-05-22T18:13:10.000Z",
            "file": "child_saying_i'm_here.mp3",
            "name": "child saying I'm here",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/choir_notification_e_major.mp3",
            "size": 63480,
            "modified": "2023-05-22T18:13:11.000Z",
            "file": "choir_notification_e_major.mp3",
            "name": "choir notification e major",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic-e.mp3",
            "size": 34567,
            "modified": "2023-05-22T18:12:58.000Z",
            "file": "classic_ding_dongs/classic-e.mp3",
            "name": "classic-e",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic.mp3",
            "size": 47467,
            "modified": "2023-05-22T18:12:50.000Z",
            "file": "classic_ding_dongs/classic.mp3",
            "name": "classic",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic_a.mp3",
            "size": 36468,
            "modified": "2023-05-22T18:12:56.000Z",
            "file": "classic_ding_dongs/classic_a.mp3",
            "name": "classic a",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic_a_sharp.mp3",
            "size": 37354,
            "modified": "2023-05-22T18:12:56.000Z",
            "file": "classic_ding_dongs/classic_a_sharp.mp3",
            "name": "classic a sharp",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic_b.mp3",
            "size": 37772,
            "modified": "2023-05-22T18:12:56.000Z",
            "file": "classic_ding_dongs/classic_b.mp3",
            "name": "classic b",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic_c.mp3",
            "size": 34599,
            "modified": "2023-05-22T18:12:57.000Z",
            "file": "classic_ding_dongs/classic_c.mp3",
            "name": "classic c",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic_c_sharp.mp3",
            "size": 34308,
            "modified": "2023-05-22T18:12:57.000Z",
            "file": "classic_ding_dongs/classic_c_sharp.mp3",
            "name": "classic c sharp",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic_d.mp3",
            "size": 33813,
            "modified": "2023-05-22T18:12:58.000Z",
            "file": "classic_ding_dongs/classic_d.mp3",
            "name": "classic d",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic_d_sharp.mp3",
            "size": 34283,
            "modified": "2023-05-22T18:12:57.000Z",
            "file": "classic_ding_dongs/classic_d_sharp.mp3",
            "name": "classic d sharp",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic_f.mp3",
            "size": 35708,
            "modified": "2023-05-22T18:12:58.000Z",
            "file": "classic_ding_dongs/classic_f.mp3",
            "name": "classic f",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic_f_sharp.mp3",
            "size": 36569,
            "modified": "2023-05-22T18:12:58.000Z",
            "file": "classic_ding_dongs/classic_f_sharp.mp3",
            "name": "classic f sharp",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic_g.mp3",
            "size": 38288,
            "modified": "2023-05-22T18:12:59.000Z",
            "file": "classic_ding_dongs/classic_g.mp3",
            "name": "classic g",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/classic_g_sharp.mp3",
            "size": 38185,
            "modified": "2023-05-22T18:12:59.000Z",
            "file": "classic_ding_dongs/classic_g_sharp.mp3",
            "name": "classic g sharp",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/electronics.mp3",
            "size": 44257,
            "modified": "2023-05-22T18:12:51.000Z",
            "file": "classic_ding_dongs/electronics.mp3",
            "name": "electronics",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/modern_classic.mp3",
            "size": 28138,
            "modified": "2023-05-22T18:12:51.000Z",
            "file": "classic_ding_dongs/modern_classic.mp3",
            "name": "modern classic",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/old_electronics.mp3",
            "size": 75040,
            "modified": "2023-05-22T18:12:51.000Z",
            "file": "classic_ding_dongs/old_electronics.mp3",
            "name": "old electronics",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/classic_ding_dongs/spooky.mp3",
            "size": 46536,
            "modified": "2023-05-22T18:12:52.000Z",
            "file": "classic_ding_dongs/spooky.mp3",
            "name": "spooky",
            "classicDingDong": true
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/clean_chimes.mp3",
            "size": 58185,
            "modified": "2023-05-22T18:13:11.000Z",
            "file": "clean_chimes.mp3",
            "name": "clean chimes",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/frequency_sweep.mp3",
            "size": 16576,
            "modified": "2023-05-22T18:13:11.000Z",
            "file": "frequency_sweep.mp3",
            "name": "frequency sweep",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/harp_riff.mp3",
            "size": 53993,
            "modified": "2023-05-22T18:13:12.000Z",
            "file": "harp_riff.mp3",
            "name": "harp riff",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/hidden_treasure.mp3",
            "size": 74687,
            "modified": "2023-05-22T18:13:12.000Z",
            "file": "hidden_treasure.mp3",
            "name": "hidden treasure",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/large_doorbell.mp3",
            "size": 134704,
            "modified": "2023-05-22T18:13:12.000Z",
            "file": "large_doorbell.mp3",
            "name": "large doorbell",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/over_excited.mp3",
            "size": 43133,
            "modified": "2023-05-22T18:13:12.000Z",
            "file": "over_excited.mp3",
            "name": "over excited",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/piano_riff.mp3",
            "size": 95188,
            "modified": "2023-05-22T18:13:13.000Z",
            "file": "piano_riff.mp3",
            "name": "piano riff",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/police_radio_chatter.mp3",
            "size": 59470,
            "modified": "2023-05-22T18:13:13.000Z",
            "file": "police_radio_chatter.mp3",
            "name": "police radio chatter",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/police_siren.mp3",
            "size": 77289,
            "modified": "2023-05-22T18:13:13.000Z",
            "file": "police_siren.mp3",
            "name": "police siren",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/police_siren_chirps.mp3",
            "size": 105283,
            "modified": "2023-05-22T18:13:13.000Z",
            "file": "police_siren_chirps.mp3",
            "name": "police siren chirps",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/radio_static_countdown.mp3",
            "size": 80477,
            "modified": "2023-05-22T18:13:14.000Z",
            "file": "radio_static_countdown.mp3",
            "name": "radio static countdown",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/ring_stars.mp3",
            "size": 290374,
            "modified": "2023-05-22T18:13:14.000Z",
            "file": "ring_stars.mp3",
            "name": "ring stars",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/shave_and_a_haircut_two_bits.mp3",
            "size": 43723,
            "modified": "2023-05-22T18:13:15.000Z",
            "file": "shave_and_a_haircut_two_bits.mp3",
            "name": "shave and a haircut two bits",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/shave_and_a_haircut_two_bits_transposed_to_g_minor.mp3",
            "size": 43881,
            "modified": "2023-05-22T18:13:15.000Z",
            "file": "shave_and_a_haircut_two_bits_transposed_to_g_minor.mp3",
            "name": "shave and a haircut two bits transposed to g minor",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/shave_and_a_haircut_two_bits_triplet.mp3",
            "size": 43619,
            "modified": "2023-05-22T18:13:15.000Z",
            "file": "shave_and_a_haircut_two_bits_triplet.mp3",
            "name": "shave and a haircut two bits triplet",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/silly_'you_have_a_visitor'_tone.mp3",
            "size": 101663,
            "modified": "2023-05-22T18:13:15.000Z",
            "file": "silly_'you_have_a_visitor'_tone.mp3",
            "name": "silly 'you have a visitor' tone",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/soft_3_note_chime.mp3",
            "size": 115972,
            "modified": "2023-05-22T18:13:16.000Z",
            "file": "soft_3_note_chime.mp3",
            "name": "soft 3 note chime",
            "classicDingDong": false
        },
        {
            "url": "https://dlc.skybell.wtf/tones/chime/the_skybells.mp3",
            "size": 240326,
            "modified": "2023-05-22T18:13:16.000Z",
            "file": "the_skybells.mp3",
            "name": "the skybells",
            "classicDingDong": false
        }
    ]
}

Responses

Set Tone

Set Audio Tone

Set the tone to one of the tones provided by SkyBell in the List Doorbell Tones or List Chime Tones end points.

This operation kicks off several operations. Since the doorbells themselves have very little space, every tone (except the default onboard one) needs to be downloaded to the doorbell first. What this means to you as an API consumer is that you can expect this endpoint to take longer (perhaps significantly) than a normal API call since you are waiting for the device to download the tone and then confirm. On fast connections this is still well under a second. On slower connections this could take several seconds.

  • tone_type - One of: "test", "button", "doorbell", or "motion". This is the type of tone the provided file will be for.
  • tone_file - The file property from the list tones API endpoint. These files reference actual files in the S3 DLC bucket.
Request Body schema: */*
string

Responses

Upload Tone

Upload Custom Tone

Allows a logged in user to upload a tone to their SkyBell to use when the button is pushed.

MP3, OGG, WAV formats supported. Maximum file size of 5MB. On SkyBell camera devices only the first 10 seconds will be used. On SkyBell Chime devices, only the first 30 seconds.

Requirements

  • Logged in user, JWT token provided in header.
  • Device provisioned, online, and reachable by the internet.

Request Body

  • user_tone - Mutli-part form file upload - The audio file to upload and use as a tone. MP3, OGG, WAV formats supported. Maximum file size of 5MB. Only the first 10 seconds will be used.
  • tone_type - One of: "test", "button", "doorbell", or "motion". This is the type of tone the uploaded file will used be for.

Example Response

{
    "error": false,
    "message": "Custom tone set",
    "data": false
}
Request Body schema: text/plain
Schema not provided

Responses

Locations

Locations provide a way to group multiple SkyBell devices together under one location. This entirely optional API can be useful for accounts with many devices running at many different physical locations.

Whether a SkyBell device is or is not in a group does not impact any device functionality.

Currently locations are limited to 5 locations per user and 50 devices per location.

List Locations

This endpoint makes an HTTP GET request to retrieve a list of locations from the API. The request does not include a request body as it is a GET request. The response body will contain an array of location objects, each representing a specific location. Each location object may include properties such as ID, name, address, and other relevant details.

List all the locations for the currently logged in user.

Requirements

  • Logged in user, JWT token provided in header.

Example Response

{
    "error": false,
    "message": "OK",
    "data": {
        "count": 1,
        "rows": [
            {
                "id": "3d6acbaa-3b12-4923-8f41-aabd6913296b",
                "owner_account_id": "f48654f2-991b-499a-8366-e4172fd31fb3",
                "detail": {
                    "location": {
                        "latitude": "40.6762291",
                        "longitude": "-73.9585769",
                        "uncertainty": "-1"
                    },
                    "contact1_note": "Owner",
                    "contact2_note": "Some fake guy",
                    "contact1_full_name": "John Smith",
                    "contact2_full_name": "Faker Fakeguy",
                    "building_information": {
                        "city": "Brooklyn",
                        "name": "My loft",
                        "state": "NY",
                        "zipcode": "11238",
                        "street_1": "910 Bergen St",
                        "street_2": "",
                        "description": "My cool NYC house"
                    },
                    "contact1_phone_number": "+15555551212",
                    "contact2_phone_number": "+15555555555"
                },
                "device_ids": [ "48c135b6-3680-4230-92af-6dcebda51170" ],
                "created_at": "2025-03-19T20:21:55.006Z",
                "updated_at": "2025-03-19T20:36:09.625Z"
            }
        ]
    }
}
Authorizations:
bearerAuth

Responses

Create new Location

Add Location Information

This endpoint allows you to add location information along with building details and contact information.

Request Body

  • location (object, required): Contains latitude, longitude, and uncertainty of the location.

    • latitude (string, required): The latitude of the location.

    • longitude (string, required): The longitude of the location.

    • uncertainty (string, required): The uncertainty of the location.

  • building_information (object, required): Contains details about the building.

    • name (string, required): The name of the building.

    • street_1 (string, required): The first line of the building's address.

    • street_2 (string, required): The second line of the building's address.

    • city (string, required): The city where the building is located.

    • state (string, required): The state where the building is located.

    • zipcode (string, required): The zipcode of the building's location.

    • description (string, required): A description of the building.

  • contact1_full_name (string, required): The full name of the primary contact person.

  • contact1_phone_number (string, required): The phone number of the primary contact person.

  • contact1_note (string, required): Additional note about the primary contact person.

  • contact2_full_name (string, required): The full name of the secondary contact person.

  • contact2_phone_number (string, required): The phone number of the secondary contact person.

  • contact2_note (string, required): Additional note about the secondary contact person.

Response

The response will contain the status of the request along with any relevant information or error messages.

Create a location for currently logged in user.

building_information.name is the only required field. All others can be left as empty strings ("")

Requirements

  • Logged in user, JWT token provided in header.

Example Request Body

{
    "location": {
        "latitude": "40.6762291",
        "longitude": "-73.9585769",
        "uncertainty": "-1"
    },
    "contact1_note": "Owner",
    "contact2_note": "Some fake guy",
    "contact1_full_name": "John Smith",
    "contact2_full_name": "Faker Fakeguy",
    "building_information": {
        "city": "Brooklyn",
        "name": "My loft",
        "state": "NY",
        "zipcode": "11238",
        "street_1": "910 Bergen St",
        "street_2": "",
        "description": "My cool NYC house"
    },
    "contact1_phone_number": "+15555551212",
    "contact2_phone_number": "+15555555555"
}

Example Response

{
    "error": false,
    "message": "Location created.",
    "data": {
        "id": "d0e766dc-1700-4810-8602-1972bd161b1c",
        "owner_account_id": "33dae2fb-499a-496c-88b5-897da608a04a",
        "detail": {
            "location": {
                "latitude": "40.6762291",
                "longitude": "-73.9585769",
                "uncertainty": "-1"
            },
            "contact1_note": "Owner",
            "contact2_note": "Some fake guy",
            "contact1_full_name": "John Smith",
            "contact2_full_name": "Faker Fakeguy",
            "building_information": {
                "city": "Brooklyn",
                "name": "My loft",
                "state": "NY",
                "zipcode": "11238",
                "street_1": "910 Bergen St",
                "street_2": "",
                "description": "My cool NYC house"
            },
            "contact1_phone_number": "+15555551212",
            "contact2_phone_number": "+15555555555"
        }
    }
}
Authorizations:
bearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "location": {
    },
  • "contact1_note": "Owner",
  • "contact2_note": "Some fake guy",
  • "contact1_full_name": "John Smith",
  • "contact2_full_name": "Faker Fakeguy",
  • "building_information": {
    },
  • "contact1_phone_number": "+15555551212",
  • "contact2_phone_number": "+15555555555"
}

Update Location

Update Location

Update a location for currently logged in user. Allows for change of location details and the additional/removal

building_information.name is the only required field. All others can be left as empty strings ("").

The "device_ids" array is special in that it must always contain BOTH the already existing device_ids (if any) & then device_ids you wish to add or remove.
For example if you have a location with the device_ids of ["e38c5a72-df84-4dd3-92fa-0c85985280f7"] and you wish to add a new device_id of "cab7a651-8155-433e-a834-244c929cf931", you will need to send the full new array of ["e38c5a72-df84-4dd3-92fa-0c85985280f7", "cab7a651-8155-433e-a834-244c929cf931"].

Sending JUST["cab7a651-8155-433e-a834-244c929cf931"] would remove the "e38c5a72-df84-4dd3-92fa-0c85985280f7" device_id from the location.

Requirements

  • Logged in user, JWT token provided in header.

Example Request Body

Updating a handful of the details for a location:

{
    "building_information": {
        "name": "Big Red Building"
    },
    "contact1_note": "Owner"
}

Adding a device to the location:

{
    "device_ids": ["e38c5a72-df84-4dd3-92fa-0c85985280f7"]
}

Removing all devices from the location:

{
    "device_ids": []
}
Authorizations:
bearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "device_ids": [
    ]
}

Delete Location

Delete Location

Delete a location from the current users account. All devices associated with this location will be automatically removed from the location as well.
These devices will still be registered to the account but exist under no specified location.

Requirements

  • Logged in user, JWT token provided in header.

Example Response Body

{
    "error": false,
    "message": "Location deleted.",
    "data": false
}
Authorizations:
bearerAuth

Responses

Other Routes

Current User

Current User Info

Use this endpoint to get information about the current SkyBell user.

Example Response

A SkyBell Free user:

{
    "error": false,
    "message": "OK",
    "data": {
        "email": "skybelluser@example.com",
        "account_id": "33dae2fb-499a-496c-88b5-897da608a04a",
        "premium_status": "free",
        "premium": {
            "renewing": null,
            "term": null,
            "started_at": null,
            "ended_at": null
        }
    }
}

A SkyBell Premium user:

{
    "error": false,
    "message": "OK",
    "data": {
        "email": "skybelluser@example.com",
        "account_id": "33dae2fb-499a-496c-88b5-897da608a04a",
        "premium_status": "premium",
        "premium": {
            "renewing": true,
            "term": 1,
            "started_at": "2022-10-27T20:20:47.506Z",
            "ended_at": null
        }
    }
}
Authorizations:
noauthAuth

Responses

Register Mobile App Notification Token

Register Mobile Device for Notifications

Use this endpoint to register a device to recieve mobile notifications about doorbell events.

  • fcm_token - The Firebase Messaging token generated by the mobile app to be used for sending notifications to that device.
  • mobile_device_id - The unique identifier of the mobile device. Format of these will vary between iOS and Android.
  • account_id - The account ID to register the mobile app to. Obviously this must match with the logged in user making this request
Request Body schema: */*
string

Responses

Remove Mobile App Notification Token

Stop Mobile App Notifications

Use this endpoint to stop notifications from happening for a specific mobile device ID.

  • mobile_device_id - The unique identifier of the mobile device. Format of these will vary between iOS and Android.

Responses

API Health

API Health

This endpoint simply returns the status of the SkyBell API Server. No authorization is required and this endpoint can be used to determine if the API is up and responsive.

This endpoint will also respond with the current versions for all parts of the SkyBell platform including: the mobile apps, firmwares, and of course API version itself.

While SkyBell is moving from HD to Gen5, the property "MOBILE_BETA" will also be available on this end point. If the property for this value is false, it means the SkyBell Gen5 platform is not accepting new users at the moment (this was used more during the BETA period but could also be used if there is a migration issue).

Request Body

(None)

Example Response

{
    "error": false,
    "message": "OK",
    "data": {
        "STARTED": "2023-11-16T19:00:18.949Z",
        "UPTIME": 3994,
        "ENV": "dev",
        "VERSION": "v20.8.0",
        "SKYBELL_API_VER": "1.4.0",
        "CURRENT_FIRMWARE": {
            "trim3": "",
            "trim2": "SB_TRIM2_0001_1_0_0",
            "hd2": "SB_HD2_0001_1_0_0",
            "skyguard": "SKYBELL_SKYGUARD_1000014_1_0_0",
            "slim2": "SB_SLIM2_0001_1_0_0",
            "chime": "SB_CHIME_0001_0_2_18",
            "trim": "SKYBELL_TRIMPLUS_1000030_1_0_0",
            "slim": "SKYBELL_MICRO_1000020_1_0_0",
            "hd40": "SKYBELL_HD_4_0_1000010_1_0_0"
        },
        "BE1_MIGRATION_FIRMWARE": {
            "hd2": "64599891b1e930996b190a48",
            "hd40": "645998a09859749ed334f574",
            "skyguard": "645998afe5b8eea4a81a53d6",
            "slim": "645998beea386ba977fe3842",
            "slim2": "645998cda9943faee0e37e10",
            "trim": "645998dcd0fe92b38a336d0e",
            "trim2": "645998ebb8d272b8532832e8"
        },
        "MOBILE_BETA": true
    }
}
Authorizations:
noauthAuth

Responses