Quickstart Guide

Overview

The UltronSMART Cloud API - Personal provides comprehensive IoT device management capabilities for personal use. This API allows you to manage locations, devices, and sensor data through a unified interface.

Data Model & Relationships

The UltronSMART Cloud API follows a hierarchical data model that reflects real-world IoT deployments:

User (Account)
├── Location 1 (Group/Home)
│   ├── Device A (Smart Light)
│   ├── Device B (Smart Plug)
│   └── Device C (Sensor)
├── Location 2 (Group/Office)
│   ├── Device D (Thermostat)
│   └── Device E (Security Camera)
└── Location 3 (Group/Vacation Home)
    └── Device F (Smart Lock)

Key Relationships

User → Locations: A user account can have multiple locations (called "Groups" in the API)
Location → Devices: Each location contains multiple IoT devices
Device → States(including Sensor Data when applicable): Each device generates state and/or sensor data.

API Terminology

Concept	API Term	Description
Location	Group	A physical space (home, office, building)
Location ID	Singular: `groupId` Plural: `groupIds`	Global unique ID for Group
User ID	`uid`	Global unique ID for User
Device Collection	Group Devices	All devices within a specific location
Device Status	Device States	Current operational status of devices
Product Serial Number	Singular: `sn` Plural: `snList`	Global unique ID for the device
Device Configuration	Singular: `config` Plural: `configs`	Advanced settings that are persistent after power cycles. See How TO SetDeviceConfigs

Navigation Flow

Get User's Locations: POST /usr/v5/GetGroups
Get Location's Device List: POST /usr/v5/GetGroupDeviceList
Get Location's Devices Capability: POST /usr/v5/GetGroupDevices
Monitor Device States: POST /usr/v5/GetGroupDeviceStates
Control Devices: POST /usr/v5/SendCommand

This hierarchical structure ensures organized device management and enables location-based operations such as "turn off all lights in the living room" or "get energy consumption for the entire office."

Prerequisites

Before starting, ensure you have:

Device Provisioning: Using Ultron Utility App to provision your devices
Account Access: Sign in at https://account.ultroncloud.com/ using the same credentials as your Ultron Utility App.
API Setup: Obtain your appId and API KEY from the account portal. (requires active subscription from: Ultron APP Market )

Authentication

All API requests require the following headers:

X-Api-Key: YOUR_API_KEY
Ultron-Cloud-Appid: YOUR_APP_ID

Base URLs

Production: https://api.ultroncloud.com

Getting Started

Step 1: Create Your First Location

A location represents a physical space where your IoT devices are deployed (e.g., home, office).

curl -X POST "https://api.ultroncloud.com/usr/v5/CreateGroup" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Home"
  }'

Step 2: Get Your Locations

Retrieve all locations you have access to:

curl -X POST "https://api.ultroncloud.com/usr/v5/GetGroups" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

Step 3: List Devices in a Location

Get all devices within a specific location:

curl -X POST "https://api.ultroncloud.com/usr/v5/GetGroupDeviceList" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "YOUR_LOCATION_ID"
  }'

Step 4: Get Devices Capability

Get detailed devices within a specific location, and can be filtered with snList:

curl -X POST "https://api.ultroncloud.com/usr/v5/GetGroupDevices" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "YOUR_LOCATION_ID",
    "snList":["SN1", "SN2"]
  }'

Step 5: Check Device States

Monitor the current status of all devices in a location, and can be filtered with snList:

curl -X POST "https://api.ultroncloud.com/usr/v5/GetGroupDeviceStates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "YOUR_LOCATION_ID",
    "snList":["SN1", "SN2"]
  }'

Step 6: Control a Device

Send commands to control your devices:

curl -X POST "https://api.ultroncloud.com/usr/v5/SendCommand" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sn": "UT3702-ES12345",
    "iotDevs": [
        "OUTLET"
    ],
    "iotCmds": [
        {
            "command": "OnOff",
            "params": {
                "on": false
            }
        }
    ]
}'

Core API Categories

1. Location Management

Create Location: POST /usr/v5/CreateGroup
Configure Location: POST /usr/v5/SetGroupName
Delete Location: POST /usr/v5/DeleteGroup
Get User Locations: POST /usr/v5/GetGroups
Manage Members: POST /usr/v5/GetGroupMembers

2. Device Management

List Devices: POST /usr/v5/GetGroupDeviceList
Device Capability: POST /usr/v5/GetGroupDevices
Device States: POST /usr/v5/GetGroupDeviceStates
Send Commands: POST /usr/v5/SendCommand
Configure Device: POST /usr/v5/SetDeviceConfigs
Move Device: POST /usr/v5/MoveDevice
Delete Device: POST /usr/v5/DeleteDevice
BLE device topology and online state: POST /usr/v5/GetBleTopology

3. Sensor Data & Analytics

Real-time Power: POST /usr/v5/GetDeviceRealTimeKWh
Sensor Data: POST /usr/v5/GetSensorDataOfDevices
Hourly Data: POST /usr/v5/GetHourlySensorDataOfDevices
Daily Data: POST /usr/v5/GetDailySensorDataOfDevices
Export to CSV: POST /usr/v5/ExportSensorDataHistoryToCSV

Error Handling

The API uses standard HTTP status codes:

200 OK: Request successful
400 Bad Request: Invalid request parameters
401 Unauthorized: Invalid or missing API credentials
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

Application-Layer Result Codes (SkuResult & CmdResult)

When the HTTP status is 200 OK, the response body may still contain application-layer result codes (e.g., result or error fields) indicating specific operation outcomes or errors (e.g., DeviceOffline, InvalidSN).

A 0 value indicates success, while non-zero values represent specific error conditions. See the complete reference here:

Result Codes Documentation

Best Practices

Cache Location and Device IDs(sn in the docs): Store frequently used IDs to reduce API calls
Use Bulk Operations: Prefer batch APIs for multiple devices when available
Handle Rate Limits: Implement exponential backoff for rate limit responses
Monitor Device States: Use cached endpoints for real-time monitoring
Secure Credentials: Never expose API keys in client-side code