Skip to content

IoT Platform API

Manage IoT devices, fleet operations, alarm rules, telemetry, and notifications.

Base URL: https://api.wayscloud.services

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

MethodPathDescription
GET/v1/iot/devicesList devices
POST/v1/iot/devicesRegister 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}/healthGet device health
GET/v1/iot/devices/{device_id}/tagsList device tags
POST/v1/iot/devices/{device_id}/tagsAdd tags to device
DELETE/v1/iot/devices/{device_id}/tags/{tag}Remove tag from device
GET/v1/iot/groupsList device groups
POST/v1/iot/groupsCreate 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}/devicesAdd devices to group
DELETE/v1/iot/groups/{group_id}/devices/{device_id}Remove device from group
GET/v1/iot/profilesList device profiles
POST/v1/iot/profilesCreate 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/rulesList alarm rules
POST/v1/iot/rulesCreate 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}/enableEnable alarm rule
POST/v1/iot/rules/{rule_id}/disableDisable alarm rule
GET/v1/iot/alarmsList alarms
GET/v1/iot/alarms/summaryGet alarm summary
GET/v1/iot/alarms/{alarm_id}Get alarm details
GET/v1/iot/alarms/{alarm_id}/timelineGet alarm event timeline
POST/v1/iot/alarms/{alarm_id}/acknowledgeAcknowledge alarm
POST/v1/iot/alarms/{alarm_id}/resolveResolve alarm
POST/v1/iot/alarms/{alarm_id}/reopenReopen a resolved alarm
GET/v1/iot/datapointsList datapoint definitions
POST/v1/iot/datapointsCreate 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}/telemetryGet device telemetry
GET/v1/iot/devices/{device_id}/telemetry/latestGet latest telemetry values
GET/v1/iot/notifications/channelsList notification channels
POST/v1/iot/notifications/channelsCreate 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}/testSend test notification
GET/v1/iot/notifications/policiesList notification policies
POST/v1/iot/notifications/policiesCreate 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/deliveriesList notification deliveries
GET/v1/iot/credentialsGet MQTT connection info
GET/v1/iot/subscriptionGet IoT subscription
GET/v1/iot/usageGet usage statistics
GET/v1/iot/statsGet platform statistics

GET /v1/iot/devices

List devices

Retrieve a paginated list of registered IoT devices.

Response:

FieldTypeDescription
devicesarrayRequired. List of device objects
totalintegerRequired. Total number of devices matching filter
pageintegerRequired. Current page number
page_sizeintegerRequired. Items per page

Example:

bash
curl https://api.wayscloud.services/v1/iot/devices \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "devices": [
    {
      "device_id": "sensor-001",
      "name": "Temperature Sensor A",
      "is_active": true,
      "is_online": true,
      "last_seen": "2026-03-30T09:55:00Z"
    },
    {
      "device_id": "sensor-002",
      "name": "Humidity Sensor B",
      "is_active": true,
      "is_online": true
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20,
  "has_more": true
}

POST /v1/iot/devices

Register device

Register a new IoT device and generate MQTT credentials. Subject to plan device limits.

Request Body:

FieldTypeDescription
device_idobjectUnique device identifier. Auto-generated UUID if omitted.
namestringRequired. Human-readable device name
descriptionobjectDevice description
device_typeobjectDevice type or model
metadataobjectCustom key-value metadata

Example:

bash
curl -X POST https://api.wayscloud.services/v1/iot/devices \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Office floor 3",
  "device_type": "ESP32",
  "metadata": {
    "firmware": "2.1.0",
    "location": "oslo"
  },
  "name": "Temperature Sensor A"
}'

Response:

json
{
  "device_id": "sensor-001",
  "name": "Temperature Sensor A",
  "device_type": "ESP32",
  "is_active": true,
  "is_online": true,
  "last_seen": "2026-03-30T09:55:00Z",
  "connection_status": "connected",
  "stability_score": 95,
  "firmware_version": "2.1.0",
  "tags": [
    "production",
    "floor-3"
  ],
  "metadata": {
    "location": "Building A"
  },
  "messages_24h": 1440,
  "battery_level": 87,
  "signal_strength": -65,
  "created_at": "2026-01-15T10:00:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "device_id": "sensor-001",
  "name": "Temperature Sensor A",
  "device_type": "ESP32",
  "is_active": true,
  "is_online": true,
  "last_seen": "2026-03-30T09:55:00Z",
  "connection_status": "connected",
  "stability_score": 95,
  "firmware_version": "2.1.0",
  "tags": [
    "production",
    "floor-3"
  ],
  "metadata": {
    "location": "Building A"
  },
  "messages_24h": 1440,
  "battery_level": 87,
  "signal_strength": -65,
  "created_at": "2026-01-15T10:00:00Z"
}

PATCH /v1/iot/devices/

Update device

Update device name, description, type, metadata, or active status.

Request Body:

FieldTypeDescription
nameobjectNew device name
descriptionobjectNew description
device_typeobjectNew device type
metadataobjectReplace custom metadata
is_activeobjectActivate or deactivate device

Example:

bash
curl -X PATCH https://api.wayscloud.services/v1/iot/devices/{device_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "is_active": false,
  "name": "Temperature Sensor A (updated)"
}'

Response:

json
{
  "device_id": "sensor-001",
  "name": "Temperature Sensor A",
  "device_type": "ESP32",
  "is_active": true,
  "is_online": true,
  "last_seen": "2026-03-30T09:55:00Z",
  "connection_status": "connected",
  "stability_score": 95,
  "firmware_version": "2.1.0",
  "tags": [
    "production",
    "floor-3"
  ],
  "metadata": {
    "location": "Building A"
  },
  "messages_24h": 1440,
  "battery_level": 87,
  "signal_strength": -65,
  "created_at": "2026-01-15T10:00:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "device_id": "sensor-001",
  "health_score": 92,
  "health_status": "healthy",
  "components": {
    "uptime": 100,
    "alarm_burden": 95,
    "connection_stability": 90,
    "telemetry_freshness": 85
  },
  "checked_at": "2026-03-30T10:00:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "tags": [
    "production",
    "floor-3",
    "critical"
  ]
}

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: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '[
  "production",
  "floor-3"
]'

Response:

json
{
  "added": [
    "new-tag-1",
    "new-tag-2"
  ]
}

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: wayscloud_iot_abc12_YOUR_SECRET"

GET /v1/iot/groups

List device groups

Example:

bash
curl https://api.wayscloud.services/v1/iot/groups \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "groups": [
    {
      "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
      "name": "Floor 3 Sensors",
      "description": "All sensors on floor 3",
      "color": "#FF5733"
    }
  ]
}

POST /v1/iot/groups

Create device group

Request Body:

FieldTypeDescription
namestringRequired. Group name
descriptionobjectGroup description

Example:

bash
curl -X POST https://api.wayscloud.services/v1/iot/groups \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "All sensors on floor 3",
  "name": "Floor 3 Sensors"
}'

Response:

json
{
  "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "name": "Floor 3 Sensors",
  "description": "All sensors on floor 3",
  "color": "#FF5733",
  "created_at": "2026-01-20T14:00:00Z",
  "updated_at": "2026-03-20T14:22:00Z"
}

GET /v1/iot/groups/

Get device group

Example:

bash
curl https://api.wayscloud.services/v1/iot/groups/{group_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "name": "Floor 3 Sensors",
  "description": "All sensors on floor 3",
  "color": "#FF5733",
  "created_at": "2026-01-20T14:00:00Z",
  "updated_at": "2026-03-20T14:22:00Z"
}

PUT /v1/iot/groups/

Update device group

Request Body:

FieldTypeDescription
nameobjectNew group name
descriptionobjectNew description

Example:

bash
curl -X PUT https://api.wayscloud.services/v1/iot/groups/{group_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Floor 3 Sensors (renamed)"
}'

Response:

json
{
  "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "name": "Floor 3 Sensors",
  "description": "All sensors on floor 3",
  "color": "#FF5733",
  "created_at": "2026-01-20T14:00:00Z",
  "updated_at": "2026-03-20T14:22:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

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: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"device_ids": ["sensor-001", "sensor-002"]}'

Response:

json
{
  "count": 3,
  "added": [
    "sensor-001",
    "sensor-002",
    "sensor-003"
  ]
}

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: wayscloud_iot_abc12_YOUR_SECRET"

GET /v1/iot/profiles

List device profiles

Example:

bash
curl https://api.wayscloud.services/v1/iot/profiles \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "profiles": [
    {
      "id": "b2c3d4e5-6789-0abc-def1-234567890bcd",
      "name": "Temperature Sensor Profile",
      "reporting_interval_seconds": 60
    }
  ]
}

POST /v1/iot/profiles

Create device profile

Request Body:

FieldTypeDescription
namestringRequired. Profile name
descriptionobjectProfile description
expected_topicsobjectMQTT topics the device should publish to
reporting_interval_secondsobjectExpected reporting interval in seconds
metadataobjectProfile metadata

Example:

bash
curl -X POST https://api.wayscloud.services/v1/iot/profiles \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_topics": [
    "devices/+/sensors/temperature"
  ],
  "name": "Standard Sensor",
  "reporting_interval_seconds": 60
}'

Response:

json
{
  "id": "b2c3d4e5-6789-0abc-def1-234567890bcd",
  "name": "Temperature Sensor Profile",
  "description": "Standard temperature/humidity sensors",
  "expected_topics": [
    "devices/+/sensors/temperature",
    "devices/+/sensors/humidity"
  ],
  "reporting_interval_seconds": 60,
  "metadata": {
    "sensor_type": "DHT22"
  },
  "created_at": "2026-01-10T12:00:00Z",
  "updated_at": "2026-03-20T14:22:00Z"
}

GET /v1/iot/profiles/

Get device profile

Example:

bash
curl https://api.wayscloud.services/v1/iot/profiles/{profile_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "id": "b2c3d4e5-6789-0abc-def1-234567890bcd",
  "name": "Temperature Sensor Profile",
  "description": "Standard temperature/humidity sensors",
  "expected_topics": [
    "devices/+/sensors/temperature",
    "devices/+/sensors/humidity"
  ],
  "reporting_interval_seconds": 60,
  "metadata": {
    "sensor_type": "DHT22"
  },
  "created_at": "2026-01-10T12:00:00Z",
  "updated_at": "2026-03-20T14:22:00Z"
}

PUT /v1/iot/profiles/

Update device profile

Request Body:

FieldTypeDescription
nameobject
descriptionobject
expected_topicsobject
reporting_interval_secondsobject
metadataobject

Example:

bash
curl -X PUT https://api.wayscloud.services/v1/iot/profiles/{profile_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "reporting_interval_seconds": 120
}'

Response:

json
{
  "id": "b2c3d4e5-6789-0abc-def1-234567890bcd",
  "name": "Temperature Sensor Profile",
  "description": "Standard temperature/humidity sensors",
  "expected_topics": [
    "devices/+/sensors/temperature",
    "devices/+/sensors/humidity"
  ],
  "reporting_interval_seconds": 60,
  "metadata": {
    "sensor_type": "DHT22"
  },
  "created_at": "2026-01-10T12:00:00Z",
  "updated_at": "2026-03-20T14:22:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "profile_id": "prof-abc123",
  "device_id": "sensor-001",
  "applied": true
}

GET /v1/iot/rules

List alarm rules

Example:

bash
curl https://api.wayscloud.services/v1/iot/rules \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "rules": [
    {
      "id": "c3d4e5f6-7890-1abc-def2-345678901cde",
      "name": "High temperature alert",
      "rule_type": "threshold",
      "severity": "warning",
      "is_enabled": true
    }
  ]
}

POST /v1/iot/rules

Create alarm rule

Request Body:

FieldTypeDescription
namestringRequired. Rule name
descriptionobjectRule description
rule_typestringRequired. Rule type: missing_data, offline, threshold, message_rate, reconnect_rate
scope_typestringScope: fleet, group, profile, device
scope_device_idobjectDevice ID when scope_type=device
scope_group_idobjectGroup ID when scope_type=group
scope_profile_idobjectProfile ID when scope_type=profile
configobjectRequired. Rule-type-specific configuration
severitystringAlarm severity: critical, warning, info
actionsarrayActions on trigger: create_alarm, send_webhook, mark_unhealthy
cooldown_secondsintegerMinimum seconds between alarm triggers
is_enabledbooleanWhether rule is active
auto_resolvebooleanAuto-resolve alarm when condition clears

Example:

bash
curl -X POST https://api.wayscloud.services/v1/iot/rules \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "actions": [
    "create_alarm"
  ],
  "config": {
    "datapoint_id": "dp-abc123",
    "duration_seconds": 300,
    "operator": "gt",
    "value": 35
  },
  "name": "High temperature alert",
  "rule_type": "threshold",
  "severity": "warning"
}'

Response:

json
{
  "id": "c3d4e5f6-7890-1abc-def2-345678901cde",
  "name": "High temperature alert",
  "rule_type": "threshold",
  "scope_type": "fleet",
  "config": {
    "datapoint_id": "dp-abc123",
    "operator": "gt",
    "value": 35,
    "duration_seconds": 300
  },
  "severity": "warning",
  "actions": [
    "create_alarm"
  ],
  "cooldown_seconds": 300,
  "is_enabled": true,
  "auto_resolve": false,
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-03-20T14:22:00Z"
}

GET /v1/iot/rules/

Get alarm rule

Example:

bash
curl https://api.wayscloud.services/v1/iot/rules/{rule_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "id": "c3d4e5f6-7890-1abc-def2-345678901cde",
  "name": "High temperature alert",
  "rule_type": "threshold",
  "scope_type": "fleet",
  "config": {
    "datapoint_id": "dp-abc123",
    "operator": "gt",
    "value": 35,
    "duration_seconds": 300
  },
  "severity": "warning",
  "actions": [
    "create_alarm"
  ],
  "cooldown_seconds": 300,
  "is_enabled": true,
  "auto_resolve": false,
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-03-20T14:22:00Z"
}

PUT /v1/iot/rules/

Update alarm rule

Request Body:

FieldTypeDescription
nameobject
descriptionobject
configobject
severityobject
actionsobject
cooldown_secondsobject
is_enabledobject
auto_resolveobject

Example:

bash
curl -X PUT https://api.wayscloud.services/v1/iot/rules/{rule_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "config": {
    "value": 40
  },
  "severity": "critical"
}'

Response:

json
{
  "id": "c3d4e5f6-7890-1abc-def2-345678901cde",
  "name": "High temperature alert",
  "rule_type": "threshold",
  "scope_type": "fleet",
  "config": {
    "datapoint_id": "dp-abc123",
    "operator": "gt",
    "value": 35,
    "duration_seconds": 300
  },
  "severity": "warning",
  "actions": [
    "create_alarm"
  ],
  "cooldown_seconds": 300,
  "is_enabled": true,
  "auto_resolve": false,
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-03-20T14:22:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "id": "c3d4e5f6-7890-1abc-def2-345678901cde",
  "name": "High temperature alert",
  "rule_type": "threshold",
  "scope_type": "fleet",
  "config": {
    "datapoint_id": "dp-abc123",
    "operator": "gt",
    "value": 35,
    "duration_seconds": 300
  },
  "severity": "warning",
  "actions": [
    "create_alarm"
  ],
  "cooldown_seconds": 300,
  "is_enabled": true,
  "auto_resolve": false,
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-03-20T14:22:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "id": "c3d4e5f6-7890-1abc-def2-345678901cde",
  "name": "High temperature alert",
  "rule_type": "threshold",
  "scope_type": "fleet",
  "config": {
    "datapoint_id": "dp-abc123",
    "operator": "gt",
    "value": 35,
    "duration_seconds": 300
  },
  "severity": "warning",
  "actions": [
    "create_alarm"
  ],
  "cooldown_seconds": 300,
  "is_enabled": true,
  "auto_resolve": false,
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-03-20T14:22:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "alarms": [
    {
      "id": "d4e5f6a7-8901-2bcd-ef34-567890123def",
      "device_id": "sensor-001",
      "severity": "warning",
      "title": "Device offline: sensor-001",
      "status": "active",
      "triggered_at": "2026-03-30T14:00:00Z",
      "occurrence_count": 3
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 50
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "by_status": {
    "active": 8,
    "acknowledged": 3,
    "resolved": 45
  },
  "by_severity": {
    "critical": 2,
    "warning": 7,
    "info": 3
  },
  "active_total": 11
}

GET /v1/iot/alarms/

Get alarm details

Example:

bash
curl https://api.wayscloud.services/v1/iot/alarms/{alarm_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "id": "d4e5f6a7-8901-2bcd-ef34-567890123def",
  "device_id": "sensor-001",
  "rule_id": "c3d4e5f6-7890-1abc-def2-345678901cde",
  "rule_name": "High temperature alert",
  "severity": "warning",
  "title": "Device offline: sensor-001",
  "message": "Device has been offline for 5 minutes",
  "status": "active",
  "triggered_at": "2026-03-30T14:00:00Z",
  "occurrence_count": 3,
  "acknowledged_at": null,
  "resolved_at": null,
  "created_at": "2026-03-30T14:00:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
[
  {
    "id": 1,
    "event_type": "triggered",
    "actor": "rule_engine",
    "note": null,
    "metadata": {
      "severity": "warning"
    },
    "created_at": "2026-03-30T14:00:00Z"
  },
  {
    "id": 2,
    "event_type": "acknowledged",
    "actor": "operator@example.com",
    "note": "Investigating",
    "metadata": null,
    "created_at": "2026-03-30T14:15:00Z"
  }
]

POST /v1/iot/alarms/{alarm_id}/acknowledge

Acknowledge alarm

Request Body:

FieldTypeDescription
noteobjectOptional note

Example:

bash
curl -X POST https://api.wayscloud.services/v1/iot/alarms/{alarm_id}/acknowledge \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Investigating — sensor may need recalibration"
}'

Response:

json
{
  "id": "d4e5f6a7-8901-2bcd-ef34-567890123def",
  "device_id": "sensor-001",
  "rule_id": "c3d4e5f6-7890-1abc-def2-345678901cde",
  "rule_name": "High temperature alert",
  "severity": "warning",
  "title": "Device offline: sensor-001",
  "message": "Device has been offline for 5 minutes",
  "status": "active",
  "triggered_at": "2026-03-30T14:00:00Z",
  "occurrence_count": 3,
  "acknowledged_at": null,
  "resolved_at": null,
  "created_at": "2026-03-30T14:00:00Z"
}

POST /v1/iot/alarms/{alarm_id}/resolve

Resolve alarm

Request Body:

FieldTypeDescription
noteobjectOptional note

Example:

bash
curl -X POST https://api.wayscloud.services/v1/iot/alarms/{alarm_id}/resolve \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Investigating — sensor may need recalibration"
}'

Response:

json
{
  "id": "d4e5f6a7-8901-2bcd-ef34-567890123def",
  "device_id": "sensor-001",
  "rule_id": "c3d4e5f6-7890-1abc-def2-345678901cde",
  "rule_name": "High temperature alert",
  "severity": "warning",
  "title": "Device offline: sensor-001",
  "message": "Device has been offline for 5 minutes",
  "status": "active",
  "triggered_at": "2026-03-30T14:00:00Z",
  "occurrence_count": 3,
  "acknowledged_at": null,
  "resolved_at": null,
  "created_at": "2026-03-30T14:00:00Z"
}

POST /v1/iot/alarms/{alarm_id}/reopen

Reopen a resolved alarm

Request Body:

FieldTypeDescription
noteobjectOptional note

Example:

bash
curl -X POST https://api.wayscloud.services/v1/iot/alarms/{alarm_id}/reopen \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Investigating — sensor may need recalibration"
}'

Response:

json
{
  "id": "d4e5f6a7-8901-2bcd-ef34-567890123def",
  "device_id": "sensor-001",
  "rule_id": "c3d4e5f6-7890-1abc-def2-345678901cde",
  "rule_name": "High temperature alert",
  "severity": "warning",
  "title": "Device offline: sensor-001",
  "message": "Device has been offline for 5 minutes",
  "status": "active",
  "triggered_at": "2026-03-30T14:00:00Z",
  "occurrence_count": 3,
  "acknowledged_at": null,
  "resolved_at": null,
  "created_at": "2026-03-30T14:00:00Z"
}

GET /v1/iot/datapoints

List datapoint definitions

Example:

bash
curl https://api.wayscloud.services/v1/iot/datapoints \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "datapoints": [
    {
      "id": "e5f6a7b8-9012-3cde-f456-7890123456ef",
      "name": "temperature",
      "label": "Temperature",
      "unit": "°C",
      "data_type": "number"
    }
  ]
}

POST /v1/iot/datapoints

Create datapoint definition

Request Body:

FieldTypeDescription
keystringRequired. Datapoint key (unique per customer)
labelobjectHuman-readable label
unitobjectMeasurement unit
data_typestringData type: number, string, boolean

Example:

bash
curl -X POST https://api.wayscloud.services/v1/iot/datapoints \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "data_type": "number",
  "key": "temperature",
  "label": "Temperature",
  "unit": "°C"
}'

Response:

json
{
  "id": "e5f6a7b8-9012-3cde-f456-7890123456ef",
  "name": "temperature",
  "label": "Temperature",
  "unit": "°C",
  "data_type": "number",
  "aggregation_method": "avg",
  "is_chartable": true,
  "is_alertable": true,
  "created_at": "2026-01-10T12:00:00Z"
}

GET /v1/iot/datapoints/

Get datapoint definition

Example:

bash
curl https://api.wayscloud.services/v1/iot/datapoints/{datapoint_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "id": "e5f6a7b8-9012-3cde-f456-7890123456ef",
  "name": "temperature",
  "label": "Temperature",
  "unit": "°C",
  "data_type": "number",
  "aggregation_method": "avg",
  "is_chartable": true,
  "is_alertable": true,
  "created_at": "2026-01-10T12:00:00Z"
}

PUT /v1/iot/datapoints/

Update datapoint definition

Request Body:

FieldTypeDescription
labelobject
unitobject

Example:

bash
curl -X PUT https://api.wayscloud.services/v1/iot/datapoints/{datapoint_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Ambient Temperature",
  "unit": "°C"
}'

Response:

json
{
  "id": "e5f6a7b8-9012-3cde-f456-7890123456ef",
  "name": "temperature",
  "label": "Temperature",
  "unit": "°C",
  "data_type": "number",
  "aggregation_method": "avg",
  "is_chartable": true,
  "is_alertable": true,
  "created_at": "2026-01-10T12:00:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
[
  {
    "datapoint_id": "dp-abc123",
    "name": "temperature",
    "label": "Temperature",
    "unit": "°C",
    "data_type": "number",
    "measured_at": "2026-03-30T09:55:00Z",
    "value": 22.5
  },
  {
    "datapoint_id": "dp-def456",
    "name": "humidity",
    "label": "Humidity",
    "unit": "%",
    "data_type": "number",
    "measured_at": "2026-03-30T09:55:00Z",
    "value": 45.2
  }
]

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
[
  {
    "datapoint_id": "dp-abc123",
    "name": "temperature",
    "label": "Temperature",
    "unit": "°C",
    "data_type": "number",
    "measured_at": "2026-03-30T09:55:00Z",
    "value": 22.5
  },
  {
    "datapoint_id": "dp-def456",
    "name": "humidity",
    "label": "Humidity",
    "unit": "%",
    "data_type": "number",
    "measured_at": "2026-03-30T09:55:00Z",
    "value": 45.2
  }
]

GET /v1/iot/notifications/channels

List notification channels

Example:

bash
curl https://api.wayscloud.services/v1/iot/notifications/channels \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "channels": [
    {
      "id": "f6a7b8c9-0123-4def-5678-901234567890",
      "name": "Ops Webhook",
      "channel_type": "webhook",
      "is_enabled": true
    }
  ]
}

POST /v1/iot/notifications/channels

Create notification channel

Request Body:

FieldTypeDescription
namestringRequired. Channel name
channel_typestringRequired. Channel type: email, webhook, slack, teams, sms
configobjectRequired. Channel-type-specific configuration
is_enabledbooleanWhether channel is active

Example:

bash
curl -X POST https://api.wayscloud.services/v1/iot/notifications/channels \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "channel_type": "webhook",
  "config": {
    "url": "https://example.com/webhooks/iot"
  },
  "name": "Ops Webhook"
}'

Response:

json
{
  "id": "f6a7b8c9-0123-4def-5678-901234567890",
  "name": "Ops Webhook",
  "channel_type": "webhook",
  "config": {
    "url": "https://example.com/webhooks/iot"
  },
  "is_enabled": true,
  "created_at": "2026-02-01T10:00:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "id": "f6a7b8c9-0123-4def-5678-901234567890",
  "name": "Ops Webhook",
  "channel_type": "webhook",
  "config": {
    "url": "https://example.com/webhooks/iot"
  },
  "is_enabled": true,
  "created_at": "2026-02-01T10:00:00Z"
}

PUT /v1/iot/notifications/channels/

Update notification channel

Request Body:

FieldTypeDescription
nameobject
configobject
is_enabledobject

Example:

bash
curl -X PUT https://api.wayscloud.services/v1/iot/notifications/channels/{channel_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "config": {
    "url": "https://example.com/webhooks/iot-v2"
  }
}'

Response:

json
{
  "id": "f6a7b8c9-0123-4def-5678-901234567890",
  "name": "Ops Webhook",
  "channel_type": "webhook",
  "config": {
    "url": "https://example.com/webhooks/iot"
  },
  "is_enabled": true,
  "created_at": "2026-02-01T10:00:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "success": true,
  "message": "Test notification sent successfully",
  "channel_id": "ch-abc123"
}

GET /v1/iot/notifications/policies

List notification policies

Example:

bash
curl https://api.wayscloud.services/v1/iot/notifications/policies \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "policies": [
    {
      "id": "a7b8c9d0-1234-5ef6-7890-123456789012",
      "name": "Critical alerts to Slack",
      "severity_filter": [
        "critical"
      ],
      "is_enabled": true
    }
  ]
}

POST /v1/iot/notifications/policies

Create notification policy

Request Body:

FieldTypeDescription
namestringRequired. Policy name
descriptionobject
severity_filterarrayWhich alarm severities to match
rule_idsobjectSpecific rule IDs to match (null = all rules)
scope_typestringScope: fleet, device, group, profile
scope_idsobjectIDs within scope (null for fleet)
event_typesarrayAlarm events: triggered, acknowledged, resolved
channel_idsarrayRequired. Channel IDs to deliver to
cooldown_secondsintegerMinimum seconds between notifications for same alarm
is_enabledbooleanWhether policy is active

Example:

bash
curl -X POST https://api.wayscloud.services/v1/iot/notifications/policies \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "channel_ids": [
    "ch-abc123"
  ],
  "event_types": [
    "triggered"
  ],
  "name": "Critical alerts to Slack",
  "severity_filter": [
    "critical"
  ]
}'

Response:

json
{
  "id": "a7b8c9d0-1234-5ef6-7890-123456789012",
  "name": "Critical alerts to Slack",
  "severity_filter": [
    "critical"
  ],
  "event_types": [
    "triggered"
  ],
  "channel_ids": [
    "ch-abc123"
  ],
  "cooldown_seconds": 300,
  "is_enabled": true,
  "created_at": "2026-02-01T10:00:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "id": "a7b8c9d0-1234-5ef6-7890-123456789012",
  "name": "Critical alerts to Slack",
  "severity_filter": [
    "critical"
  ],
  "event_types": [
    "triggered"
  ],
  "channel_ids": [
    "ch-abc123"
  ],
  "cooldown_seconds": 300,
  "is_enabled": true,
  "created_at": "2026-02-01T10:00:00Z"
}

PUT /v1/iot/notifications/policies/

Update notification policy

Request Body:

FieldTypeDescription
nameobject
descriptionobject
severity_filterobject
event_typesobject
channel_idsobject
cooldown_secondsobject
is_enabledobject

Example:

bash
curl -X PUT https://api.wayscloud.services/v1/iot/notifications/policies/{policy_id} \
  -H "X-API-Key: wayscloud_iot_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "cooldown_seconds": 600,
  "severity_filter": [
    "critical",
    "warning"
  ]
}'

Response:

json
{
  "id": "a7b8c9d0-1234-5ef6-7890-123456789012",
  "name": "Critical alerts to Slack",
  "severity_filter": [
    "critical"
  ],
  "event_types": [
    "triggered"
  ],
  "channel_ids": [
    "ch-abc123"
  ],
  "cooldown_seconds": 300,
  "is_enabled": true,
  "created_at": "2026-02-01T10:00:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "deliveries": [
    {
      "id": "b8c9d0e1-2345-6f78-9012-345678901234",
      "channel_type": "webhook",
      "status": "delivered",
      "sent_at": "2026-03-30T14:05:00Z"
    }
  ],
  "total": 25,
  "limit": 50,
  "offset": 0
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "mqtt_broker": {
    "host": "mqtt.wayscloud.services",
    "port": 1883,
    "tls_port": 8883,
    "websocket_port": 8083,
    "protocol": "mqtt"
  }
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "plan": "iot-50",
  "status": "active",
  "device_limit": 50,
  "device_count": 12,
  "created_at": "2026-01-01T00:00:00Z"
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "messages_today": 4521,
  "messages_this_month": 142000,
  "data_points_today": 18000,
  "data_points_this_month": 560000
}

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: wayscloud_iot_abc12_YOUR_SECRET"

Response:

json
{
  "total_devices": 42,
  "active_devices": 39,
  "connected_now": 38,
  "messages_24h": 62000,
  "data_points_24h": 248000,
  "active_alarms": 3
}


WAYSCloud AS