Scribd
Upload
23 views14 pages

Smart Home Device Control API

The Smart Home Device Control API (v1.1.0) allows users to manage and control smart home devices such as lights, thermostats, and cameras. It includes functionalities for listing devices, updating settings, controlling device states, and managing scenes. The API is secured with bearer authentication and provides various endpoints for device and scene management.

Uploaded by

aharxict
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
23 views14 pages

Smart Home Device Control API

The Smart Home Device Control API (v1.1.0) allows users to manage and control smart home devices such as lights, thermostats, and cameras. It includes functionalities for listing devices, updating settings, controlling device states, and managing scenes. The API is secured with bearer authentication and provides various endpoints for device and scene management.

Uploaded by

aharxict
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 14

Smart Home Device Control API (v1.1.

0)
Download OpenAPI specification: Download

SmartHome Inc. Support: support@smarthome.example.com | URL: https://smarthome.example.com/support


License: Apache 2.0

API for controlling and managing smart home devices like lights, thermostats, and cameras.

Devices

Manage and view smart home devices.

List all smart home devices


AUTHORIZATIONS: bearerAuth

QUERY PARAMETERS

type string
Enum: "light" "thermostat" "camera" "lock" "sensor" "plug"
Filter devices by type (e.g., light, thermostat, camera)

room string
Filter devices by room name or ID

Responses

200 A list of smart home devices.

default An unexpected error occurred.

GET /devices

Response samples
200 default

Content type
application/json

Copy Expand all Collapse all


[
- {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Living Room Lamp",
"type": "light",
"manufacturer": "Philips",
"model": "Hue White Ambiance",
"room": "Living Room",
"isOnline": true,
+ "capabilities": [ … ],
+ "state": { … },
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]

Get device details


AUTHORIZATIONS: bearerAuth

PATH PARAMETERS

deviceId string <uuid>


required
ID of the device to retrieve

Responses

200 Successfully retrieved device details.

404 The requested resource was not found.

default An unexpected error occurred.


GET /devices/{deviceId}

Response samples

200 404 default

Content type
application/json

Copy Expand all Collapse all


{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Living Room Lamp",
"type": "light",
"manufacturer": "Philips",
"model": "Hue White Ambiance",
"room": "Living Room",
"isOnline": true,
- "capabilities": [
"onoff",
"brightness",
"color_temp"
],
- "state": {
"on": true
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update device settings or name


AUTHORIZATIONS: bearerAuth

PATH PARAMETERS

deviceId string <uuid>


required
ID of the device to update

REQUEST BODY SCHEMA: application/json

Device update payload

name string
room string

Responses

200 Device updated successfully.

400 The request was malformed or contained invalid parameters.

404 The requested resource was not found.

default An unexpected error occurred.

PUT /devices/{deviceId}

Request samples

Payload

Content type
application/json

Copy
{
"name": "Main Bedroom Thermostat",
"room": "Main Bedroom"
}

Response samples

200 400 404 default

Content type
application/json

Copy Expand all Collapse all


{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Living Room Lamp",
"type": "light",
"manufacturer": "Philips",
"model": "Hue White Ambiance",
"room": "Living Room",
"isOnline": true,
- "capabilities": [
"onoff",
"brightness",
"color_temp"
],
- "state": {
"on": true
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

DeviceControl

Control the state of smart home devices.

Get current state of a device


AUTHORIZATIONS: bearerAuth

PATH PARAMETERS

deviceId string <uuid>


required
ID of the device

Responses

200 Current device state.

404 The requested resource was not found.

default An unexpected error occurred.

GET /devices/{deviceId}/state
Response samples

200 404 default

Content type
application/json

Copy
{
"on": true
}

Update the state of a device


AUTHORIZATIONS: bearerAuth

PATH PARAMETERS

deviceId string <uuid>


required
ID of the device

REQUEST BODY SCHEMA: application/json

Desired state object for the device. The schema varies by device type.

on boolean
General on/off state, if applicable.

brightness integer <int32> [ 0 .. 100 ]


Brightness level from 0 to 100.

color string <hex-color>


Color in HEX format (e.g.,

colorTemperature integer <int32> [ 2000 .. 6500 ]


Color temperature in Kelvin.

Responses

200 Device state updated successfully.

400 The request was malformed or contained invalid parameters.

404 The requested resource was not found.


default An unexpected error occurred.

PUT /devices/{deviceId}/state

Request samples

Payload

Content type
application/json

Example
Turn a light on

Copy
{
"deviceType": "light",
"on": true,
"brightness": 80,
"color": "#FFFF00"
}

Response samples

200 400 404 default

Content type
application/json

Copy
{
"on": true
}

Scenes

Manage and activate pre-configured scenes.


List all configured scenes
AUTHORIZATIONS: bearerAuth

Responses

200 A list of scenes.

default An unexpected error occurred.

GET /scenes

Response samples

200 default

Content type
application/json

Copy Expand all Collapse all


[
- {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Movie Night",
"description": "Dims lights, sets thermostat to cozy.",
+ "actions": [ … ],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]

Create a new scene


AUTHORIZATIONS: bearerAuth

REQUEST BODY SCHEMA: application/json


name
string
required

description string

actions
Array of objects (SceneAction)
required

Responses

201 Scene created successfully.

default An unexpected error occurred.

POST /scenes

Request samples

Payload

Content type
application/json

Copy Expand all Collapse all


{
"name": "Good Morning",
"description": "Gradually turns on lights and adjusts thermostat.",
- "actions": [
+ { … }
]
}

Response samples

201 default

Content type
application/json

Copy Expand all Collapse all


{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Movie Night",
"description": "Dims lights, sets thermostat to cozy.",
- "actions": [
+ { … }
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Get scene details


AUTHORIZATIONS: bearerAuth

PATH PARAMETERS

sceneId string <uuid>


required
ID of the scene

Responses

200 Scene details.

404 The requested resource was not found.

default An unexpected error occurred.

GET /scenes/{sceneId}

Response samples

200 404 default

Content type
application/json

Copy Expand all Collapse all


{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Movie Night",
"description": "Dims lights, sets thermostat to cozy.",
- "actions": [
+ { … }
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update an existing scene


AUTHORIZATIONS: bearerAuth

PATH PARAMETERS

sceneId string <uuid>


required
ID of the scene to update

REQUEST BODY SCHEMA: application/json

name string

description string

actions Array of objects (SceneAction)

Responses

200 Scene updated successfully.

404 The requested resource was not found.

default An unexpected error occurred.

PUT /scenes/{sceneId}

Request samples

Payload

Content type
application/json
Copy Expand all Collapse all
{
"name": "string",
"description": "string",
- "actions": [
+ { … }
]
}

Response samples

200 404 default

Content type
application/json

Copy Expand all Collapse all


{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Movie Night",
"description": "Dims lights, sets thermostat to cozy.",
- "actions": [
+ { … }
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Delete a scene
AUTHORIZATIONS: bearerAuth

PATH PARAMETERS

sceneId string <uuid>


required
ID of the scene to delete

Responses

— 204 Scene deleted successfully.

404 The requested resource was not found.


default An unexpected error occurred.

DELETE /scenes/{sceneId}

Response samples

404 default

Content type
application/json

Copy
{
"code": 0,
"message": "string",
"details": "string"
}

Activate a scene
AUTHORIZATIONS: bearerAuth

PATH PARAMETERS

sceneId string <uuid>


required
ID of the scene to activate

Responses

— 202 Scene activation request accepted.

404 The requested resource was not found.

default An unexpected error occurred.


POST /scenes/{sceneId}/activate

Response samples

404 default

Content type
application/json

Copy
{
"code": 0,
"message": "string",
"details": "string"
}

You might also like