OpenAPI Specification
openapi: 3.1.0
info:
title: Tuya Device Management Device Control Devices API
description: The Tuya Device Management API provides endpoints for querying, controlling, and managing IoT devices registered to a Tuya cloud project. Capabilities include device information retrieval, device control, factory reset, device renaming, sub-device listing, operation log queries, and user-device association management.
version: '1.0'
contact:
name: Tuya Developer Support
url: https://developer.tuya.com/en/
email: developer@tuya.com
termsOfService: https://developer.tuya.com/en/docs/iot/compliance?id=Ka9t0qa3qihn3
servers:
- url: https://openapi.tuyaus.com
description: Tuya US Data Center
- url: https://openapi.tuyaeu.com
description: Tuya EU Data Center
- url: https://openapi.tuyain.com
description: Tuya India Data Center
security:
- tuyaApiKey: []
tags:
- name: Devices
description: Query and manage IoT device information
paths:
/v1.0/devices/{device_id}:
get:
operationId: getDevice
summary: Get Device Details
description: Retrieve detailed information about a specific device including its attributes, status, online state, and product information.
tags:
- Devices
parameters:
- $ref: '#/components/parameters/DeviceId'
responses:
'200':
description: Device details
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceResponse'
'401':
description: Unauthorized
'404':
description: Device not found
put:
operationId: updateDevice
summary: Update Device Name
description: Modify the friendly name of a specified device.
tags:
- Devices
parameters:
- $ref: '#/components/parameters/DeviceId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: New friendly name for the device
required:
- name
responses:
'200':
description: Device updated
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'401':
description: Unauthorized
'404':
description: Device not found
delete:
operationId: removeDevice
summary: Remove Device
description: Remove a device from the cloud account and deregister it.
tags:
- Devices
parameters:
- $ref: '#/components/parameters/DeviceId'
responses:
'200':
description: Device removed
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'401':
description: Unauthorized
'404':
description: Device not found
/v1.0/devices:
get:
operationId: listDevices
summary: List Devices
description: Query devices associated with a cloud project by application, product, or a set of device IDs.
tags:
- Devices
parameters:
- name: device_ids
in: query
description: Comma-separated list of device IDs to query
schema:
type: string
- name: schema
in: query
description: Include device schema information
schema:
type: boolean
- name: last_row_key
in: query
description: Pagination cursor key
schema:
type: string
- name: page_size
in: query
description: Number of results per page (max 100)
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
'200':
description: List of devices
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceListResponse'
'401':
description: Unauthorized
/v1.0/users/{uid}/devices:
get:
operationId: listUserDevices
summary: List User Devices
description: Retrieve all devices associated with a specific user account.
tags:
- Devices
parameters:
- name: uid
in: path
required: true
description: Unique user identifier
schema:
type: string
- name: last_row_key
in: query
description: Pagination cursor key
schema:
type: string
- name: page_size
in: query
description: Number of results per page
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
'200':
description: List of user devices
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceListResponse'
'401':
description: Unauthorized
'404':
description: User not found
/v1.0/devices/factory-infos:
get:
operationId: getDeviceFactoryInfos
summary: Get Device Factory Information
description: Retrieve manufacturing and factory information for one or more devices.
tags:
- Devices
parameters:
- name: device_ids
in: query
required: true
description: Comma-separated list of device IDs
schema:
type: string
responses:
'200':
description: Device factory information
content:
application/json:
schema:
$ref: '#/components/schemas/FactoryInfoResponse'
'401':
description: Unauthorized
components:
schemas:
DeviceListResponse:
type: object
properties:
result:
type: object
properties:
devices:
type: array
items:
$ref: '#/components/schemas/Device'
last_row_key:
type: string
description: Pagination cursor for next page
has_more:
type: boolean
description: Whether more results are available
success:
type: boolean
t:
type: integer
format: int64
DeviceResponse:
type: object
properties:
result:
$ref: '#/components/schemas/Device'
success:
type: boolean
t:
type: integer
format: int64
FactoryInfoResponse:
type: object
properties:
result:
type: array
items:
type: object
properties:
id:
type: string
description: Device ID
uuid:
type: string
description: Device UUID
sn:
type: string
description: Serial number
mac:
type: string
description: MAC address
success:
type: boolean
t:
type: integer
format: int64
SuccessResponse:
type: object
properties:
result:
type: boolean
description: Whether the operation succeeded
success:
type: boolean
description: Request success flag
t:
type: integer
format: int64
description: Response timestamp in milliseconds
Device:
type: object
properties:
id:
type: string
description: Unique device identifier
name:
type: string
description: Device friendly name
uid:
type: string
description: Owner user ID
local_key:
type: string
description: Local encryption key for LAN communication
category:
type: string
description: Product category code
product_id:
type: string
description: Product identifier
product_name:
type: string
description: Product name
sub:
type: boolean
description: Whether device is a sub-device (connected via gateway)
uuid:
type: string
description: Device UUID
owner_id:
type: string
description: Home or asset owner identifier
online:
type: boolean
description: Whether device is currently online
status:
type: array
description: Current data point statuses
items:
$ref: '#/components/schemas/DataPoint'
active_time:
type: integer
format: int64
description: Activation timestamp in seconds
create_time:
type: integer
format: int64
description: Creation timestamp in seconds
update_time:
type: integer
format: int64
description: Last update timestamp in seconds
time_zone:
type: string
description: Device time zone
ip:
type: string
description: Device IP address
DataPoint:
type: object
properties:
code:
type: string
description: Data point code identifier
value:
description: Current value of the data point
parameters:
DeviceId:
name: device_id
in: path
required: true
description: Unique device identifier
schema:
type: string
securitySchemes:
tuyaApiKey:
type: apiKey
in: header
name: client_id
description: Tuya API uses HMAC-SHA256 signed requests. Include your Access ID as the client_id header and provide a sign header computed from your Access ID, Access Secret, and timestamp.