Device Management

Complete guide to managing IoT devices in WAYSCloud IoT Platform.

List Devices

Retrieve all your registered IoT devices with filtering and pagination.

Endpoint

GET /v1/iot/devices

Query Parameters

Parameter	Type	Description	Default
`limit`	integer	Max results per page (1-100)	50
`offset`	integer	Pagination offset	0
`status`	string	Filter by status: `active`, `inactive`, `error`	all
`type`	string	Filter by device type	all
`search`	string	Search in name and description	-

Request Example

curl -X GET "https://api.wayscloud.services/v1/iot/devices?limit=20&status=active" \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY"

Response

{
  "devices": [
    {
      "device_id": "iot_dev_abc123",
      "name": "Temperature Sensor 01",
      "description": "Living room sensor",
      "type": "sensor",
      "status": "active",
      "metadata": {
        "location": "living_room",
        "model": "DHT22"
      },
      "created_at": "2025-11-01T10:00:00Z",
      "last_seen": "2025-11-05T10:30:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Register Device

Create a new IoT device and receive MQTT credentials.

Endpoint

POST /v1/iot/devices

Request Body

Field	Type	Required	Description
`name`	string	Yes	Device name (3-100 chars)
`description`	string	No	Device description
`type`	string	Yes	Device type: `sensor`, `actuator`, `gateway`, `other`
`metadata`	object	No	Custom key-value metadata

Request Example

curl -X POST https://api.wayscloud.services/v1/iot/devices \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smart Thermostat",
    "description": "Bedroom climate control",
    "type": "actuator",
    "metadata": {
      "room": "bedroom",
      "firmware_version": "2.1.0",
      "manufacturer": "WaysIoT"
    }
  }'

Response

{
  "device_id": "iot_dev_xyz789",
  "name": "Smart Thermostat",
  "description": "Bedroom climate control",
  "type": "actuator",
  "status": "active",
  "metadata": {
    "room": "bedroom",
    "firmware_version": "2.1.0",
    "manufacturer": "WaysIoT"
  },
  "mqtt_credentials": {
    "broker": "mqtt.wayscloud.services",
    "port": 8883,
    "username": "iot_dev_xyz789",
    "password": "mqtt_secure_Xy9ZaBc12345",
    "client_id": "iot_dev_xyz789",
    "tls": true
  },
  "created_at": "2025-11-05T10:45:00Z"
}

tip

Save the MQTT credentials immediately! The password is only shown once during device creation.

Python Example

import requests
import os

API_KEY = os.getenv('WAYSCLOUD_API_KEY')
API_URL = 'https://api.wayscloud.services/v1/iot'

def register_device(name, device_type, description=None, metadata=None):
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }

    payload = {
        'name': name,
        'type': device_type
    }

    if description:
        payload['description'] = description
    if metadata:
        payload['metadata'] = metadata

    response = requests.post(
        f'{API_URL}/devices',
        headers=headers,
        json=payload
    )

    return response.json()

# Register device
device = register_device(
    name='Humidity Sensor 03',
    device_type='sensor',
    description='Greenhouse humidity monitor',
    metadata={'location': 'greenhouse', 'zone': 'A'}
)

print(f"Device ID: {device['device_id']}")
print(f"MQTT Username: {device['mqtt_credentials']['username']}")
print(f"MQTT Password: {device['mqtt_credentials']['password']}")

Get Device Details

Retrieve detailed information about a specific device.

Endpoint

GET /v1/iot/devices/{device_id}

Request Example

curl -X GET https://api.wayscloud.services/v1/iot/devices/iot_dev_abc123 \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY"

Response

{
  "device_id": "iot_dev_abc123",
  "name": "Temperature Sensor 01",
  "description": "Living room sensor",
  "type": "sensor",
  "status": "active",
  "metadata": {
    "location": "living_room",
    "model": "DHT22",
    "firmware": "1.2.3"
  },
  "statistics": {
    "total_messages": 15234,
    "last_message_at": "2025-11-05T10:30:00Z",
    "bandwidth_used_mb": 45.2
  },
  "created_at": "2025-11-01T10:00:00Z",
  "updated_at": "2025-11-05T10:30:00Z",
  "last_seen": "2025-11-05T10:30:00Z"
}

Update Device

Modify device properties such as name, description, type, or metadata.

Endpoint

PATCH /v1/iot/devices/{device_id}

Request Body

All fields are optional. Only include fields you want to update.

Field	Type	Description
`name`	string	New device name
`description`	string	New description
`type`	string	New device type
`metadata`	object	Merge with existing metadata

Request Example

curl -X PATCH https://api.wayscloud.services/v1/iot/devices/iot_dev_abc123 \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temperature Sensor 01 (Updated)",
    "metadata": {
      "firmware": "1.3.0",
      "last_maintenance": "2025-11-05"
    }
  }'

Response

{
  "device_id": "iot_dev_abc123",
  "name": "Temperature Sensor 01 (Updated)",
  "description": "Living room sensor",
  "type": "sensor",
  "status": "active",
  "metadata": {
    "location": "living_room",
    "model": "DHT22",
    "firmware": "1.3.0",
    "last_maintenance": "2025-11-05"
  },
  "updated_at": "2025-11-05T11:00:00Z"
}

info

Metadata updates are merged with existing data. To remove a metadata field, set it to null.

Delete Device

Permanently remove a device and revoke its MQTT credentials.

Endpoint

DELETE /v1/iot/devices/{device_id}

Request Example

curl -X DELETE https://api.wayscloud.services/v1/iot/devices/iot_dev_abc123 \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Device iot_dev_abc123 deleted successfully",
  "device_id": "iot_dev_abc123"
}

Warning

Deleting a device is permanent and cannot be undone. The device will immediately lose MQTT access.

Python Example

import requests

def delete_device(device_id):
    headers = {'Authorization': f'Bearer {API_KEY}'}

    response = requests.delete(
        f'{API_URL}/devices/{device_id}',
        headers=headers
    )

    if response.status_code == 200:
        print(f"Device {device_id} deleted successfully")
    else:
        print(f"Error: {response.json()}")

# Delete device
delete_device('iot_dev_old123')

Device Status

Devices can have the following statuses:

active - Device is registered and can connect to MQTT
inactive - Device exists but connections are disabled
error - Device has connectivity or configuration issues

Device Types

Choose the appropriate type when registering:

sensor - Devices that collect and send data (temperature, humidity, etc.)
actuator - Devices that perform actions (switches, motors, etc.)
gateway - Devices that aggregate data from other devices
other - Custom device types

Next Steps

MQTT Credentials - Get connection information
Usage & Stats - Monitor device activity
Code Examples - Complete working examples

List Devices​

Endpoint​

Query Parameters​

Request Example​

Response​

Register Device​

Endpoint​

Request Body​

Request Example​

Response​

Python Example​

Get Device Details​

Endpoint​

Request Example​

Response​

Update Device​

Endpoint​

Request Body​

Request Example​

Response​

Delete Device​

Endpoint​

Request Example​

Response​

Python Example​

Device Status​

Device Types​

Next Steps​

List Devices

Endpoint

Query Parameters

Request Example

Response

Register Device

Endpoint

Request Body

Request Example

Response

Python Example

Get Device Details

Endpoint

Request Example

Response

Update Device

Endpoint

Request Body

Request Example

Response

Delete Device

Endpoint

Request Example

Response

Python Example

Device Status

Device Types

Next Steps