Skip to main content

IoT Platform API Overview

WAYSCloud IoT Platform provides a full-scale IoT device management solution with MQTT connectivity, real-time monitoring, and comprehensive usage tracking.

Key Features​

  • 🔌 MQTT Protocol - Industry-standard IoT messaging with auto-generated credentials
  • 📱 Device Management - Register, configure, and monitor IoT devices at scale
  • 📊 Real-time Tracking - Monitor device activity, messages, and bandwidth usage
  • 🔐 Secure Communication - TLS-encrypted MQTT connections with per-device credentials
  • ⚡ High Performance - Low-latency message delivery with quota management
  • 🌍 Scalable - From prototype to production with automatic scaling

Base URL​

https://api.wayscloud.services/v1/iot

Authentication​

All requests require a valid API key in the Authorization header:

Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY

Get Your API Key​

  1. Log in to WAYSCloud Console
  2. Navigate to API Keys
  3. Click Create New Key
  4. Select IoT Platform service
  5. Copy your API key (starts with wayscloud_iot_prod_)
warning

Store your API key securely! It provides full access to your IoT devices and credentials.

Quick Start​

Register Your First Device​

# Register a new IoT device
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": "Temperature Sensor 01",
    "description": "Living room temperature sensor",
    "type": "sensor",
    "metadata": {
      "location": "living_room",
      "model": "DHT22"
    }
  }'

Response:

{
  "device_id": "iot_dev_abc123xyz",
  "name": "Temperature Sensor 01",
  "type": "sensor",
  "status": "active",
  "mqtt_credentials": {
    "username": "iot_dev_abc123xyz",
    "password": "mqtt_secure_password_xyz",
    "client_id": "iot_dev_abc123xyz"
  },
  "created_at": "2025-11-05T10:30:00Z"
}

Connect Device to MQTT Broker​

Python (paho-mqtt)​

import paho.mqtt.client as mqtt
import json

# MQTT Configuration
MQTT_BROKER = "mqtt.wayscloud.services"
MQTT_PORT = 8883  # TLS encrypted
DEVICE_ID = "iot_dev_abc123xyz"
USERNAME = "iot_dev_abc123xyz"
PASSWORD = "mqtt_secure_password_xyz"

def on_connect(client, userdata, flags, rc):
    print(f"Connected with result code {rc}")
    # Subscribe to command topic
    client.subscribe(f"devices/{DEVICE_ID}/commands")

def on_message(client, userdata, msg):
    print(f"Received: {msg.topic} {msg.payload.decode()}")

# Create MQTT client
client = mqtt.Client(client_id=DEVICE_ID)
client.username_pw_set(USERNAME, PASSWORD)
client.tls_set()  # Enable TLS

client.on_connect = on_connect
client.on_message = on_message

# Connect to broker
client.connect(MQTT_BROKER, MQTT_PORT, 60)

# Publish sensor data
temperature_data = {
    "temperature": 22.5,
    "humidity": 65,
    "timestamp": "2025-11-05T10:35:00Z"
}

client.publish(
    f"devices/{DEVICE_ID}/telemetry",
    json.dumps(temperature_data),
    qos=1
)

client.loop_forever()

Node.js (mqtt)​

const mqtt = require('mqtt');

const options = {
  host: 'mqtt.wayscloud.services',
  port: 8883,
  protocol: 'mqtts',
  username: 'iot_dev_abc123xyz',
  password: 'mqtt_secure_password_xyz',
  clientId: 'iot_dev_abc123xyz'
};

const client = mqtt.connect(options);

client.on('connect', () => {
  console.log('Connected to MQTT broker');

  // Subscribe to commands
  client.subscribe(`devices/${options.clientId}/commands`);

  // Publish telemetry
  const data = {
    temperature: 22.5,
    humidity: 65,
    timestamp: new Date().toISOString()
  };

  client.publish(
    `devices/${options.clientId}/telemetry`,
    JSON.stringify(data),
    { qos: 1 }
  );
});

client.on('message', (topic, message) => {
  console.log(`Received: ${topic} ${message.toString()}`);
});

List Your Devices​

# List all devices with pagination
curl -X GET "https://api.wayscloud.services/v1/iot/devices?limit=50&offset=0" \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY"

Get Device Details​

# Get specific device information
curl -X GET https://api.wayscloud.services/v1/iot/devices/iot_dev_abc123xyz \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY"

Monitor Usage​

# Get usage statistics for the last 7 days
curl -X GET "https://api.wayscloud.services/v1/iot/usage?start_date=2025-10-29&end_date=2025-11-05" \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY"

MQTT Topics​

Your devices can publish and subscribe to the following topics:

Device → Cloud (Publish)​

  • devices/{device_id}/telemetry - Send sensor data and metrics
  • devices/{device_id}/events - Send device events and alerts
  • devices/{device_id}/status - Report device health and status

Cloud → Device (Subscribe)​

  • devices/{device_id}/commands - Receive control commands
  • devices/{device_id}/config - Receive configuration updates
  • devices/{device_id}/firmware - Receive firmware update notifications

Rate Limits​

  • 1000 requests/minute per API key (HTTP API)
  • 100 messages/second per device (MQTT)
  • 1 MB max message size
  • Burst: Up to 200 additional requests in short bursts

Quota Management​

Check your IoT platform limits:

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

Response:

{
  "max_devices": 1000,
  "current_devices": 42,
  "max_messages_per_month": 10000000,
  "current_messages": 1523456,
  "max_bandwidth_gb": 100,
  "current_bandwidth_gb": 12.5
}

API Endpoints Overview​

Device Management​

  • GET /v1/iot/devices - List all devices
  • POST /v1/iot/devices - Register new device
  • GET /v1/iot/devices/{device_id} - Get device details
  • PATCH /v1/iot/devices/{device_id} - Update device
  • DELETE /v1/iot/devices/{device_id} - Remove device

Credentials & Configuration​

  • GET /v1/iot/credentials - Get MQTT connection info
  • GET /v1/iot/quota - Check quota limits
  • GET /v1/iot/usage - Get usage statistics
  • GET /v1/iot/stats - Get platform statistics

Next Steps​

Support​

Need help?