IoT Platform API
Manage IoT devices, fleet operations, alarm rules, telemetry, and notifications.
Authentication: X-API-Key header with iot service permission.
Quick Start:
bash
# Register a device
curl -X POST https://api.wayscloud.services/v1/iot/devices \
-H "X-API-Key: wayscloud_xxx" \
-H "Content-Type: application/json" \
-d '{"name": "Sensor A", "device_type": "ESP32"}'
# List alarms
curl https://api.wayscloud.services/v1/iot/alarms?status=active \
-H "X-API-Key: wayscloud_xxx"
# Create webhook notification channel
curl -X POST https://api.wayscloud.services/v1/iot/notifications/channels \
-H "X-API-Key: wayscloud_xxx" \
-H "Content-Type: application/json" \
-d '{"name": "Ops Webhook", "channel_type": "webhook", "config": {"url": "https://example.com/hook"}}'Resources: Devices, Groups, Profiles, Rules, Alarms, Telemetry, Notifications
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /v1/iot/devices | List devices |
POST | /v1/iot/devices | Register device |
GET | /v1/iot/devices/{device_id} | Get device |
PATCH | /v1/iot/devices/{device_id} | Update device |
DELETE | /v1/iot/devices/{device_id} | Delete device |
GET | /v1/iot/devices/{device_id}/health | Get device health |
GET | /v1/iot/devices/{device_id}/tags | List device tags |
POST | /v1/iot/devices/{device_id}/tags | Add tags to device |
DELETE | /v1/iot/devices/{device_id}/tags/{tag} | Remove tag from device |
GET | /v1/iot/groups | List device groups |
POST | /v1/iot/groups | Create device group |
GET | /v1/iot/groups/{group_id} | Get device group |
PUT | /v1/iot/groups/{group_id} | Update device group |
DELETE | /v1/iot/groups/{group_id} | Delete device group |
POST | /v1/iot/groups/{group_id}/devices | Add devices to group |
DELETE | /v1/iot/groups/{group_id}/devices/{device_id} | Remove device from group |
GET | /v1/iot/profiles | List device profiles |
POST | /v1/iot/profiles | Create device profile |
GET | /v1/iot/profiles/{profile_id} | Get device profile |
PUT | /v1/iot/profiles/{profile_id} | Update device profile |
DELETE | /v1/iot/profiles/{profile_id} | Delete device profile |
POST | /v1/iot/profiles/{profile_id}/apply/{device_id} | Apply profile to device |
GET | /v1/iot/rules | List alarm rules |
POST | /v1/iot/rules | Create alarm rule |
GET | /v1/iot/rules/{rule_id} | Get alarm rule |
PUT | /v1/iot/rules/{rule_id} | Update alarm rule |
DELETE | /v1/iot/rules/{rule_id} | Delete alarm rule |
POST | /v1/iot/rules/{rule_id}/enable | Enable alarm rule |
POST | /v1/iot/rules/{rule_id}/disable | Disable alarm rule |
GET | /v1/iot/alarms | List alarms |
GET | /v1/iot/alarms/summary | Get alarm summary |
GET | /v1/iot/alarms/{alarm_id} | Get alarm details |
GET | /v1/iot/alarms/{alarm_id}/timeline | Get alarm event timeline |
POST | /v1/iot/alarms/{alarm_id}/acknowledge | Acknowledge alarm |
POST | /v1/iot/alarms/{alarm_id}/resolve | Resolve alarm |
POST | /v1/iot/alarms/{alarm_id}/reopen | Reopen a resolved alarm |
GET | /v1/iot/datapoints | List datapoint definitions |
POST | /v1/iot/datapoints | Create datapoint definition |
GET | /v1/iot/datapoints/{datapoint_id} | Get datapoint definition |
PUT | /v1/iot/datapoints/{datapoint_id} | Update datapoint definition |
DELETE | /v1/iot/datapoints/{datapoint_id} | Delete datapoint definition |
GET | /v1/iot/devices/{device_id}/telemetry | Get device telemetry |
GET | /v1/iot/devices/{device_id}/telemetry/latest | Get latest telemetry values |
GET | /v1/iot/notifications/channels | List notification channels |
POST | /v1/iot/notifications/channels | Create notification channel |
GET | /v1/iot/notifications/channels/{channel_id} | Get notification channel |
PUT | /v1/iot/notifications/channels/{channel_id} | Update notification channel |
DELETE | /v1/iot/notifications/channels/{channel_id} | Delete notification channel |
POST | /v1/iot/notifications/channels/{channel_id}/test | Send test notification |
GET | /v1/iot/notifications/policies | List notification policies |
POST | /v1/iot/notifications/policies | Create notification policy |
GET | /v1/iot/notifications/policies/{policy_id} | Get notification policy |
PUT | /v1/iot/notifications/policies/{policy_id} | Update notification policy |
DELETE | /v1/iot/notifications/policies/{policy_id} | Delete notification policy |
GET | /v1/iot/notifications/deliveries | List notification deliveries |
GET | /v1/iot/credentials | Get MQTT connection info |
GET | /v1/iot/subscription | Get IoT subscription |
GET | /v1/iot/usage | Get usage statistics |
GET | /v1/iot/stats | Get platform statistics |
GET /v1/iot/devices
List devices
Retrieve a paginated list of registered IoT devices.
Response:
| Field | Type | Description |
|---|---|---|
devices | array | Required. List of device objects |
total | integer | Required. Total number of devices matching filter |
page | integer | Required. Current page number |
page_size | integer | Required. Items per page |
Example:
bash
curl https://api.wayscloud.services/v1/iot/devices \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/devices
Register device
Register a new IoT device and generate MQTT credentials. Subject to plan device limits.
Request Body:
| Field | Type | Description |
|---|---|---|
device_id | object | Unique device identifier. Auto-generated UUID if omitted. |
name | string | Required. Human-readable device name |
description | object | Device description |
device_type | object | Device type or model |
metadata | object | Custom key-value metadata |
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/devices \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'GET /v1/iot/devices/
Get device
Retrieve detailed information about a specific device.
Example:
bash
curl https://api.wayscloud.services/v1/iot/devices/{device_id} \
-H "X-API-Key: YOUR_API_KEY"PATCH /v1/iot/devices/
Update device
Update device name, description, type, metadata, or active status.
Request Body:
| Field | Type | Description |
|---|---|---|
name | object | New device name |
description | object | New description |
device_type | object | New device type |
metadata | object | Replace custom metadata |
is_active | object | Activate or deactivate device |
Example:
bash
curl -X PATCH https://api.wayscloud.services/v1/iot/devices/{device_id} \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'DELETE /v1/iot/devices/
Delete device
Delete device and revoke MQTT credentials. Cannot be undone.
Example:
bash
curl -X DELETE https://api.wayscloud.services/v1/iot/devices/{device_id} \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/devices/{device_id}/health
Get device health
Health score (0-100) with component breakdown: uptime, alarms, stability, freshness.
Example:
bash
curl https://api.wayscloud.services/v1/iot/devices/{device_id}/health \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/devices/{device_id}/tags
List device tags
Example:
bash
curl https://api.wayscloud.services/v1/iot/devices/{device_id}/tags \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/devices/{device_id}/tags
Add tags to device
Request Body:
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/devices/{device_id}/tags \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'DELETE /v1/iot/devices/{device_id}/tags/
Remove tag from device
Example:
bash
curl -X DELETE https://api.wayscloud.services/v1/iot/devices/{device_id}/tags/{tag} \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/groups
List device groups
Example:
bash
curl https://api.wayscloud.services/v1/iot/groups \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/groups
Create device group
Request Body:
| Field | Type | Description |
|---|---|---|
name | string | Required. Group name |
description | object | Group description |
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/groups \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'GET /v1/iot/groups/
Get device group
Example:
bash
curl https://api.wayscloud.services/v1/iot/groups/{group_id} \
-H "X-API-Key: YOUR_API_KEY"PUT /v1/iot/groups/
Update device group
Request Body:
| Field | Type | Description |
|---|---|---|
name | object | New group name |
description | object | New description |
Example:
bash
curl -X PUT https://api.wayscloud.services/v1/iot/groups/{group_id} \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'DELETE /v1/iot/groups/
Delete device group
Example:
bash
curl -X DELETE https://api.wayscloud.services/v1/iot/groups/{group_id} \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/groups/{group_id}/devices
Add devices to group
Request Body:
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/groups/{group_id}/devices \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'DELETE /v1/iot/groups/{group_id}/devices/
Remove device from group
Example:
bash
curl -X DELETE https://api.wayscloud.services/v1/iot/groups/{group_id}/devices/{device_id} \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/profiles
List device profiles
Example:
bash
curl https://api.wayscloud.services/v1/iot/profiles \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/profiles
Create device profile
Request Body:
| Field | Type | Description |
|---|---|---|
name | string | Required. Profile name |
description | object | Profile description |
expected_topics | object | MQTT topics the device should publish to |
reporting_interval_seconds | object | Expected reporting interval in seconds |
metadata | object | Profile metadata |
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/profiles \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'GET /v1/iot/profiles/
Get device profile
Example:
bash
curl https://api.wayscloud.services/v1/iot/profiles/{profile_id} \
-H "X-API-Key: YOUR_API_KEY"PUT /v1/iot/profiles/
Update device profile
Request Body:
| Field | Type | Description |
|---|---|---|
name | object | |
description | object | |
expected_topics | object | |
reporting_interval_seconds | object | |
metadata | object |
Example:
bash
curl -X PUT https://api.wayscloud.services/v1/iot/profiles/{profile_id} \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'DELETE /v1/iot/profiles/
Delete device profile
Example:
bash
curl -X DELETE https://api.wayscloud.services/v1/iot/profiles/{profile_id} \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/profiles/{profile_id}/apply/
Apply profile to device
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/profiles/{profile_id}/apply/{device_id} \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/rules
List alarm rules
Example:
bash
curl https://api.wayscloud.services/v1/iot/rules \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/rules
Create alarm rule
Request Body:
| Field | Type | Description |
|---|---|---|
name | string | Required. Rule name |
description | object | Rule description |
rule_type | string | Required. Rule type: missing_data, offline, threshold, message_rate, reconnect_rate |
scope_type | string | Scope: fleet, group, profile, device |
scope_device_id | object | Device ID when scope_type=device |
scope_group_id | object | Group ID when scope_type=group |
scope_profile_id | object | Profile ID when scope_type=profile |
config | object | Required. Rule-type-specific configuration |
severity | string | Alarm severity: critical, warning, info |
actions | array | Actions on trigger: create_alarm, send_webhook, mark_unhealthy |
cooldown_seconds | integer | Minimum seconds between alarm triggers |
is_enabled | boolean | Whether rule is active |
auto_resolve | boolean | Auto-resolve alarm when condition clears |
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/rules \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'GET /v1/iot/rules/
Get alarm rule
Example:
bash
curl https://api.wayscloud.services/v1/iot/rules/{rule_id} \
-H "X-API-Key: YOUR_API_KEY"PUT /v1/iot/rules/
Update alarm rule
Request Body:
| Field | Type | Description |
|---|---|---|
name | object | |
description | object | |
config | object | |
severity | object | |
actions | object | |
cooldown_seconds | object | |
is_enabled | object | |
auto_resolve | object |
Example:
bash
curl -X PUT https://api.wayscloud.services/v1/iot/rules/{rule_id} \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'DELETE /v1/iot/rules/
Delete alarm rule
Example:
bash
curl -X DELETE https://api.wayscloud.services/v1/iot/rules/{rule_id} \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/rules/{rule_id}/enable
Enable alarm rule
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/rules/{rule_id}/enable \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/rules/{rule_id}/disable
Disable alarm rule
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/rules/{rule_id}/disable \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/alarms
List alarms
Retrieve alarms with optional filtering by status, severity, device, or rule.
Example:
bash
curl https://api.wayscloud.services/v1/iot/alarms \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/alarms/summary
Get alarm summary
Alarm counts grouped by status and severity.
Example:
bash
curl https://api.wayscloud.services/v1/iot/alarms/summary \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/alarms/
Get alarm details
Example:
bash
curl https://api.wayscloud.services/v1/iot/alarms/{alarm_id} \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/alarms/{alarm_id}/timeline
Get alarm event timeline
Example:
bash
curl https://api.wayscloud.services/v1/iot/alarms/{alarm_id}/timeline \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/alarms/{alarm_id}/acknowledge
Acknowledge alarm
Request Body:
| Field | Type | Description |
|---|---|---|
note | object | Optional note |
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/alarms/{alarm_id}/acknowledge \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'POST /v1/iot/alarms/{alarm_id}/resolve
Resolve alarm
Request Body:
| Field | Type | Description |
|---|---|---|
note | object | Optional note |
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/alarms/{alarm_id}/resolve \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'POST /v1/iot/alarms/{alarm_id}/reopen
Reopen a resolved alarm
Request Body:
| Field | Type | Description |
|---|---|---|
note | object | Optional note |
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/alarms/{alarm_id}/reopen \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'GET /v1/iot/datapoints
List datapoint definitions
Example:
bash
curl https://api.wayscloud.services/v1/iot/datapoints \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/datapoints
Create datapoint definition
Request Body:
| Field | Type | Description |
|---|---|---|
key | string | Required. Datapoint key (unique per customer) |
label | object | Human-readable label |
unit | object | Measurement unit |
data_type | string | Data type: number, string, boolean |
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/datapoints \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'GET /v1/iot/datapoints/
Get datapoint definition
Example:
bash
curl https://api.wayscloud.services/v1/iot/datapoints/{datapoint_id} \
-H "X-API-Key: YOUR_API_KEY"PUT /v1/iot/datapoints/
Update datapoint definition
Request Body:
| Field | Type | Description |
|---|---|---|
label | object | |
unit | object |
Example:
bash
curl -X PUT https://api.wayscloud.services/v1/iot/datapoints/{datapoint_id} \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'DELETE /v1/iot/datapoints/
Delete datapoint definition
Example:
bash
curl -X DELETE https://api.wayscloud.services/v1/iot/datapoints/{datapoint_id} \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/devices/{device_id}/telemetry
Get device telemetry
Retrieve telemetry data for a device, optionally filtered by datapoint and time range.
Example:
bash
curl https://api.wayscloud.services/v1/iot/devices/{device_id}/telemetry \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/devices/{device_id}/telemetry/latest
Get latest telemetry values
Example:
bash
curl https://api.wayscloud.services/v1/iot/devices/{device_id}/telemetry/latest \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/notifications/channels
List notification channels
Example:
bash
curl https://api.wayscloud.services/v1/iot/notifications/channels \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/notifications/channels
Create notification channel
Request Body:
| Field | Type | Description |
|---|---|---|
name | string | Required. Channel name |
channel_type | string | Required. Channel type: email, webhook, slack, teams, sms |
config | object | Required. Channel-type-specific configuration |
is_enabled | boolean | Whether channel is active |
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/notifications/channels \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'GET /v1/iot/notifications/channels/
Get notification channel
Example:
bash
curl https://api.wayscloud.services/v1/iot/notifications/channels/{channel_id} \
-H "X-API-Key: YOUR_API_KEY"PUT /v1/iot/notifications/channels/
Update notification channel
Request Body:
| Field | Type | Description |
|---|---|---|
name | object | |
config | object | |
is_enabled | object |
Example:
bash
curl -X PUT https://api.wayscloud.services/v1/iot/notifications/channels/{channel_id} \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'DELETE /v1/iot/notifications/channels/
Delete notification channel
Example:
bash
curl -X DELETE https://api.wayscloud.services/v1/iot/notifications/channels/{channel_id} \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/notifications/channels/{channel_id}/test
Send test notification
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/notifications/channels/{channel_id}/test \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/notifications/policies
List notification policies
Example:
bash
curl https://api.wayscloud.services/v1/iot/notifications/policies \
-H "X-API-Key: YOUR_API_KEY"POST /v1/iot/notifications/policies
Create notification policy
Request Body:
| Field | Type | Description |
|---|---|---|
name | string | Required. Policy name |
description | object | |
severity_filter | array | Which alarm severities to match |
rule_ids | object | Specific rule IDs to match (null = all rules) |
scope_type | string | Scope: fleet, device, group, profile |
scope_ids | object | IDs within scope (null for fleet) |
event_types | array | Alarm events: triggered, acknowledged, resolved |
channel_ids | array | Required. Channel IDs to deliver to |
cooldown_seconds | integer | Minimum seconds between notifications for same alarm |
is_enabled | boolean | Whether policy is active |
Example:
bash
curl -X POST https://api.wayscloud.services/v1/iot/notifications/policies \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'GET /v1/iot/notifications/policies/
Get notification policy
Example:
bash
curl https://api.wayscloud.services/v1/iot/notifications/policies/{policy_id} \
-H "X-API-Key: YOUR_API_KEY"PUT /v1/iot/notifications/policies/
Update notification policy
Request Body:
| Field | Type | Description |
|---|---|---|
name | object | |
description | object | |
severity_filter | object | |
event_types | object | |
channel_ids | object | |
cooldown_seconds | object | |
is_enabled | object |
Example:
bash
curl -X PUT https://api.wayscloud.services/v1/iot/notifications/policies/{policy_id} \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'DELETE /v1/iot/notifications/policies/
Delete notification policy
Example:
bash
curl -X DELETE https://api.wayscloud.services/v1/iot/notifications/policies/{policy_id} \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/notifications/deliveries
List notification deliveries
Delivery history with optional filtering by channel type and status.
Example:
bash
curl https://api.wayscloud.services/v1/iot/notifications/deliveries \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/credentials
Get MQTT connection info
Returns MQTT broker connection details. Per-device credentials are provided at registration.
Example:
bash
curl https://api.wayscloud.services/v1/iot/credentials \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/subscription
Get IoT subscription
Returns current plan, device limit, and usage.
Example:
bash
curl https://api.wayscloud.services/v1/iot/subscription \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/usage
Get usage statistics
Returns message counts, data usage, and device activity for the current billing period.
Example:
bash
curl https://api.wayscloud.services/v1/iot/usage \
-H "X-API-Key: YOUR_API_KEY"GET /v1/iot/stats
Get platform statistics
Overview stats: total devices, active, connected, messages, data usage.
Example:
bash
curl https://api.wayscloud.services/v1/iot/stats \
-H "X-API-Key: YOUR_API_KEY"