API Documentation

All API requests require authentication using an API key. You can create and manage API keys in your account settings.

Authentication Method

Include your API key in the request header:

X-API-Key: your_api_key_here

Permission Scopes

API keys can have different permission scopes:

• Read-only - Can only retrieve data
• Read & Write - Can retrieve data and send commands
• Administrative - Full access to the API

Rate Limits

API requests are rate-limited by default on an account-wide basis:

• 60 requests per minute - Short-term rate limit
• 10,000 requests per day - Daily rate limit

When a rate limit is exceeded, the API will return a 429 Too Many Requests response with information about when you can retry.

Send Command to Device

Send an MQTT command to a specific device

Path Parameters

Parameter	Description
device_id	The unique identifier of the device

Request Body

JSON object with a payload field containing the command data:

{
  "payload": {
  "Output": "Relay",
  "Relays": [
    {
      "relay": "SecurityAlarm", // Optional as long as id is present
      "state": 1,
      "id": "255.1" // Overrides relay name, remove if you want to control via name.
    }
  ]
}
  }
}

Response

Success (200 OK):

{
  "status": "Command sent successfully"
}

Error Responses

Status Code	Description
400 Bad Request	Invalid payload format
401 Unauthorized	Missing or invalid API key
403 Forbidden	Insufficient permissions or API key scope
404 Not Found	Device not found
500 Internal Server Error	Failed to send command to device

Example Request (cURL)

curl -X POST \
  https://cloud.uhavecontrol.com/api/devices/dev123/command/ \
  -H 'X-API-Key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
  "payload": {
    "Output": "Relay",
    "Relays": [
      {
        "relay": "Relay 1",
        "state": 1
      }
    ]
  }
}'

Get Device Data

Retrieve data from a specific device

Path Parameters

Parameter	Description
device_id	The unique identifier of the device

Query Parameters

Parameter	Description
type	(Optional) The type of component data to retrieve: all - All device data (default) relay - Relay state data relay_c - Relay configuration data gpio - GPIO state data gpio_c - GPIO configuration data adc - ADC state data adc_c - ADC configuration data

Response

Success (200 OK):

// Example response for type=all
{
  "s_time": "2023-01-25T08:30:45",
  "status": "online",
  "Relays": [
    {
      "mode": "On/Off Switch",
      "color": "Red",
      "stateTime": "2025-07-14T15:24:23Z",
      "name": "USW-Rel1",
      "id": "255.0",
      "state": "0",
      "text": "Off"
    },
    {
      "mode": "On/Off Switch",
      "color": "Red",
      "stateTime": "2025-07-13T04:03:05Z",
      "name": "USW-Rel2",
      "id": "255.1",
      "state": "0",
      "text": "Off"
    }
  ],
  "GPIOs": [...],
  "ADCs": [...],
  "Relay_Cs": [...],
  "GPIO_Cs": [...],
  "ADC_Cs": [...]
}

Error Responses

Status Code	Description
400 Bad Request	Invalid component type
401 Unauthorized	Missing or invalid API key
403 Forbidden	Insufficient permissions or API key scope
404 Not Found	Device not found or data not available

Example Request (cURL)

curl -X GET \
  "https://cloud.uhavecontrol.com/api/devices/dev123/data/?type=relay" \
  -H "X-API-Key: your_api_key_here"

Status Code	Description
400 Bad Request	The request was invalid or malformed
401 Unauthorized	Authentication failed or was not provided
403 Forbidden	The authenticated user doesn't have permission
404 Not Found	The requested resource doesn't exist
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Something went wrong on the server