Developer resources
Your devices. One API.
Connect your application to devices through IoT Devices. Start with a read request, then add the permissions your workflow needs.
HTTPS · API v1
Start with your installation.
Ask for an installation API key. Each key is linked to one device space and a defined set of permissions. Keep it on your application server.
https://iotdevices.org/api/iot/v1curl 'https://iotdevices.org/api/iot/v1/device/list?page_index=1&page_size=10' \
-H 'Authorization: Bearer YOUR_API_KEY'Use the Authorization: Bearer header. Read operations accept GET or JSON POST; changes require JSON POST. Allow one second between requests for the same installation.
Examples use illustrative IDs and commands. Check the product capabilities and replace them with values for your installation.
Request API accessMatching endpoints: 29 / 29
Devices
GETList devices/device/list
Required permission: read
| Name | Required | Description |
|---|---|---|
q | No | Search by device ID or name; ignored when tag is supplied. |
product | No | Filter by one or more IDs. |
tag | No | Filter by one or more IDs. |
group | No | Filter by one or more IDs. |
page_index | No | Page number, starting at 1. |
page_size | No | Results per page: 10, 20, 30 or 50.10 · 20 · 30 · 50 |
curl 'https://iotdevices.org/api/iot/v1/device/list?page_index=1&page_size=10' \
-H 'Authorization: Bearer YOUR_API_KEY'GETDevice details/device/info
Required permission: read
| Name | Required | Description |
|---|---|---|
device | Yes | Device IDs, separated by commas or pipes; up to 100. |
curl 'https://iotdevices.org/api/iot/v1/device/info?device=1001' \
-H 'Authorization: Bearer YOUR_API_KEY'POSTUpdate device tags/device/tag
Required permission: manage
Supply add, del, or both. Existing associations are left unchanged.
| Name | Required | Description |
|---|---|---|
device | Yes | Device IDs, separated by commas or pipes; up to 100. |
add | No | Tag IDs to attach. |
del | No | Tag IDs to detach. |
curl -X POST 'https://iotdevices.org/api/iot/v1/device/tag' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{"device":"1001","add":"10"}'POSTMove devices to a group/device/group
Required permission: manage
| Name | Required | Description |
|---|---|---|
device | Yes | Device IDs, separated by commas or pipes; up to 100. |
group | Yes | Destination group ID; 0 removes the group assignment. |
curl -X POST 'https://iotdevices.org/api/iot/v1/device/group' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{"device":"1001","group":10}'GETDevice logs/device/log
Required permission: read
| Name | Required | Description |
|---|---|---|
device | Yes | One device ID. |
date | No | One date in YYYY-MM-DD format; defaults to today. |
type | No | Comma-separated log types: connect, disconnect, subscribe, unsubscribe, register, ota, control, event. |
page_index | No | Page number, starting at 1. |
page_size | No | Results per page: 10, 20, 30 or 50.10 · 20 · 30 · 50 |
curl 'https://iotdevices.org/api/iot/v1/device/log?device=1001&page_size=10' \
-H 'Authorization: Bearer YOUR_API_KEY'Commands
POSTSend a device command/device/order
Required permission: control
Acceptance confirms dispatch, not execution. Check device state or events before reporting success.
| Name | Required | Description |
|---|---|---|
device | Yes | Device IDs, separated by commas or pipes; up to 100. |
order | Yes | A JSON object with commands supported by the device model. |
gateway | No | Gateway IDs when forwarding is needed; up to 5. |
curl -X POST 'https://iotdevices.org/api/iot/v1/device/order' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{"device":"1001","order":{"power":1}}'Configuration
GETRead device configuration/config/info
Required permission: read
| Name | Required | Description |
|---|---|---|
device | Yes | One device ID. |
type | Yes | Configuration section.basic · device · network · mode |
curl 'https://iotdevices.org/api/iot/v1/config/info?device=1001&type=basic' \
-H 'Authorization: Bearer YOUR_API_KEY'POSTWrite device configuration/config
Required permission: manage
Acceptance confirms dispatch, not execution. Check device state or events before reporting success.
| Name | Required | Description |
|---|---|---|
device | Yes | Device IDs, separated by commas or pipes; up to 100. |
config | Yes | Configuration properties supported by the device. |
curl -X POST 'https://iotdevices.org/api/iot/v1/config' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{"device":"1001","config":{"relay1":"1"}}'Firmware
GETList available firmware/ota/firmware
Required permission: read
| Name | Required | Description |
|---|---|---|
device | Yes | One device ID. |
curl 'https://iotdevices.org/api/iot/v1/ota/firmware?device=1001' \
-H 'Authorization: Bearer YOUR_API_KEY'POSTUpgrade firmware/ota
Required permission: firmware
Acceptance confirms dispatch, not execution. Check device state or events before reporting success.
| Name | Required | Description |
|---|---|---|
device | Yes | Device IDs, separated by commas or pipes; up to 100. |
firmware | No | For one device, supply name and size from the firmware list. Multiple devices use the latest version. |
curl -X POST 'https://iotdevices.org/api/iot/v1/ota' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{"device":"1001","firmware":{"name":"VERSION_FROM_FIRMWARE_LIST","size":"300.68"}}'Products
GETSearch products/product/list
Required permission: read
| Name | Required | Description |
|---|---|---|
q | Yes | Search by product ID, title or model. |
page_index | No | Page number, starting at 1. |
page_size | No | Results per page: 10, 20, 30 or 50.10 · 20 · 30 · 50 |
curl 'https://iotdevices.org/api/iot/v1/product/list?q=switch&page_size=10' \
-H 'Authorization: Bearer YOUR_API_KEY'GETProduct capabilities/product/detail
Required permission: read
| Name | Required | Description |
|---|---|---|
id | Yes | Product ID from the product list. |
curl 'https://iotdevices.org/api/iot/v1/product/detail?id=100' \
-H 'Authorization: Bearer YOUR_API_KEY'GETProducts in your installation/product/list/stock
Required permission: read
No parameters required.
curl 'https://iotdevices.org/api/iot/v1/product/list/stock' \
-H 'Authorization: Bearer YOUR_API_KEY'Groups
GETList groups/group/list
Required permission: read
| Name | Required | Description |
|---|---|---|
format | No | Flat list or nested tree.list · tree |
page_index | No | Page number, starting at 1. |
page_size | No | Results per page: 10, 20, 30 or 50.10 · 20 · 30 · 50 |
curl 'https://iotdevices.org/api/iot/v1/group/list?format=tree' \
-H 'Authorization: Bearer YOUR_API_KEY'PendingCreate a group
This endpoint is awaiting parameter verification and is not enabled. Contact us if your integration needs it.
PendingUpdate a group
This endpoint is awaiting parameter verification and is not enabled. Contact us if your integration needs it.
POSTDelete groups/group/delete
Required permission: manage
| Name | Required | Description |
|---|---|---|
group | Yes | Group IDs to remove; up to 100. Devices are retained. |
curl -X POST 'https://iotdevices.org/api/iot/v1/group/delete' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{"group":"10"}'POSTControl a group/group/control
Required permission: control
Acceptance confirms dispatch, not execution. Check device state or events before reporting success.
| Name | Required | Description |
|---|---|---|
group | Yes | One group ID. |
order | No | A JSON object with commands supported by the device model. |
action | No | An existing action ID. |
curl -X POST 'https://iotdevices.org/api/iot/v1/group/control' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{"group":"10","order":{"power":1}}'Tags
PendingList tags
This endpoint is awaiting parameter verification and is not enabled. Contact us if your integration needs it.
POSTCreate a tag/tag/create
Required permission: manage
| Name | Required | Description |
|---|---|---|
title | Yes | Up to 32 Chinese or English letters, digits or underscores. |
remark | No | Optional note. |
curl -X POST 'https://iotdevices.org/api/iot/v1/tag/create' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{"title":"room_100"}'PendingUpdate a tag
This endpoint is awaiting parameter verification and is not enabled. Contact us if your integration needs it.
PendingDelete tags
This endpoint is awaiting parameter verification and is not enabled. Contact us if your integration needs it.
PendingControl tagged devices
This endpoint is awaiting parameter verification and is not enabled. Contact us if your integration needs it.
Tasks
GETList tasks/task/list
Required permission: read
| Name | Required | Description |
|---|---|---|
device | No | Filter by one or more device IDs. |
stage | No | Schedule types, separated by commas or pipes. |
page_index | No | Page number, starting at 1. |
page_size | No | Results per page: 10, 20, 30 or 50.10 · 20 · 30 · 50 |
curl 'https://iotdevices.org/api/iot/v1/task/list?page_size=10' \
-H 'Authorization: Bearer YOUR_API_KEY'POSTCreate a task/task/create
Required permission: control
Supply commands or action, plus the fields for the selected schedule. Examples create paused tasks.
Schedule fields: datetime → datetime; minute → second; hour → minute + second; day → time; week → week + time; month → day + time; loop → interval. Confirm the installation timezone before scheduling.
| Name | Required | Description |
|---|---|---|
devices | Yes | Device IDs; use d_, g_ or t_ prefixes when mixing devices, groups and tags. |
type | Yes | Schedule type.datetime · minute · hour · day · week · month · loop |
times | No | Execution count; 0 means no count limit. |
datetime | No | Execution date and time, or a Unix timestamp. |
second | No | Second within a minute, from 0 to 59. |
minute | No | Minute within an hour, from 0 to 59. |
time | No | Time of day in HH:mm:ss format. |
week | No | Weekdays as comma-separated numbers, from 1 to 7. |
day | No | Day of the month, from 1 to 31. |
interval | No | Interval in seconds; at least 3. |
commands | No | A JSON object containing the commands to schedule. |
action | No | An existing action ID. |
enable | No | 1 enables the task; 0 keeps it paused.0 · 1 |
curl -X POST 'https://iotdevices.org/api/iot/v1/task/create' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{"devices":"1001","type":"loop","interval":60,"commands":{"power":1},"enable":0}'GETTask details/task/detail
Required permission: read
| Name | Required | Description |
|---|---|---|
task | Yes | One or more task IDs. |
curl 'https://iotdevices.org/api/iot/v1/task/detail?task=10' \
-H 'Authorization: Bearer YOUR_API_KEY'POSTUpdate a task/task/modify
Required permission: control
Only supplied fields change. Sending times resets the execution counter.
Schedule fields: datetime → datetime; minute → second; hour → minute + second; day → time; week → week + time; month → day + time; loop → interval. Confirm the installation timezone before scheduling.
| Name | Required | Description |
|---|---|---|
task | Yes | One task ID. |
devices | No | Device IDs; use d_, g_ or t_ prefixes when mixing devices, groups and tags. |
type | No | Schedule type.datetime · minute · hour · day · week · month · loop |
times | No | Execution count; 0 means no count limit. |
datetime | No | Execution date and time, or a Unix timestamp. |
second | No | Second within a minute, from 0 to 59. |
minute | No | Minute within an hour, from 0 to 59. |
time | No | Time of day in HH:mm:ss format. |
week | No | Weekdays as comma-separated numbers, from 1 to 7. |
day | No | Day of the month, from 1 to 31. |
interval | No | Interval in seconds; at least 3. |
commands | No | A JSON object containing the commands to schedule. |
action | No | An existing action ID. |
enable | No | 1 enables the task; 0 keeps it paused.0 · 1 |
curl -X POST 'https://iotdevices.org/api/iot/v1/task/modify' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{"task":"10","enable":0}'POSTDelete tasks/task/delete
Required permission: control
| Name | Required | Description |
|---|---|---|
task | Yes | Task IDs to delete; up to 100. |
curl -X POST 'https://iotdevices.org/api/iot/v1/task/delete' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{"task":"10"}'PendingStart or pause tasks
This endpoint is awaiting parameter verification and is not enabled. Contact us if your integration needs it.
Responses and errors
Responses include code and msg, with data when available. Lists can include page_index, page_count, is_more and total. Read the returned shape: single-object and array responses vary by endpoint.
Acceptance confirms dispatch, not execution. Check device state or events before reporting success.
A timed-out write may already have been accepted. Check the device or task before repeating it; writes are never retried automatically. Event callbacks and an MQTT endpoint are not provided by this API version.
400 / 415- Check parameter names, required fields and JSON content type.
401 / 403- Check your API key and its permissions.
429- Wait at least one second, then retry a read request.
501- This endpoint is awaiting contract verification.
502 / 504- The device service is unavailable or the result is unknown.
503- The integration still needs server configuration.