Smart Home Device Control API (v1.1.

0)
Download OpenAPI specification: Download

SmartHome Inc. Support: [email protected] | 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"
}