API Endpoints

All endpoints are served from https://developer.qube.eco and require authentication.

Authentication

Include your API key in the X-Qube-API-Key header for every request:

X-Qube-API-Key: your_api_key_here

Response Format

All API responses follow this standard format:

{
  "success": boolean,
  "data": object | array,
  "error": {
    "code": "string",
    "detail": "string"
  },
  "message": "string",
  "timestamp": "2025-01-01T12:00:00.000Z"
}

Spaces

List All Spaces

GET /api/v2/spaces/

Returns all spaces you have access to, including their devices.

curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" https://developer.qube.eco/api/v2/spaces/

Response:

{
  "success": true,
  "data": [
    {
      "name": "My Building",
      "description": "Main property",
      "space_id": 123,
      "devices": [
        {
          "device_id": "QUBE-ONE-<some-id>",
          "name": "Room 101",
          "active_mode": "prepaid",
          "udf1": "Building-A.Floor-1.Room-101",
          "udf2": "cluster-6",
          "udf3": null,
          "udf4": null,
          "udf5": null
        }
      ],
      "tags": [],
      "udf1": "Property-Main",
      "udf2": null,
      "udf3": null,
      "udf4": null,
      "udf5": null
    }
  ]
}

Get Specific Space

GET /api/v2/spaces/{space_id}/

Returns details for a specific space.

curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" https://developer.qube.eco/api/v2/spaces/123/

Response: Same format as list, but returns single space object in data.

Update Space

PUT /api/v2/spaces/{space_id}/

Update space metadata.

curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Building Name",
    "description": "Updated description",
    "udf1": "Custom field 1"
  }' https://developer.qube.eco/api/v2/spaces/123/

Response:

{
  "success": true,
  "data": {
    "name": "Updated Building Name",
    "description": "Updated description",
    "space_id": 123,
    "devices": [...],
    "udf1": "Custom field 1"
  },
  "message": "Space updated"
}

Devices

Get Device Details

GET /api/v2/devices/{device_id}/

Returns complete device information including current readings.

curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/

Response:

{
  "success": true,
  "data": {
    "name": "Room 101",
    "description": "Main meter for room 101",
    "device_id": "QUBE-ONE-<some-id>",
    "space": {
      "id": 123,
      "name": "My Building",
      "description": "Main property"
    },
    "public_access": false,
    "public_hash": null,
    "active_mode": "prepaid",
    "balance": 25000,
    "has_relay": true,
    "is_online": true,
    "is_shared": false,
    "readings": [
      {
        "property_id": "energy",
        "context_type": "cumulative",
        "value": 1234.56,
        "unit": "kWh"
      },
      {
        "property_id": "active_power",
        "context_type": "instantaneous",
        "value": 850.0,
        "unit": "W"
      },
      {
        "property_id": "voltage",
        "context_type": "instantaneous",
        "value": 230.5,
        "unit": "V"
      }
    ],
    "tags": [],
    "udf1": "BlockA.3F.302",
    "udf2": "cluster-6",
    "udf3": null,
    "udf4": null,
    "udf5": null
  }
}

Get Device Metrics

GET /api/v2/devices/{device_id}/metrics

Returns flattened device metrics for quick access.

curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/metrics

Response:

{
  "success": true,
  "data": {
    "device_id": "QUBE-ONE-<some-id>",
    "eb_tariff": 500,
    "dg_tariff": 800,
    "active_tariff": 1,
    "energy": 1234.56,
    "active_power": 850.0,
    "voltage": 230.5,
    "balance": 25000,
    "relay_state": true,
    "mode": "PREPAID",
    "pg_enabled": true
  }
}

Update Device Metadata

PUT /api/v2/devices/{device_id}/

Update device name, description, and custom fields.

curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Room 101 - Updated",
    "description": "Updated description",
    "udf1": "BlockA.3F.302"
  }' https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/

Response:

{
  "success": true,
  "data": true,
  "message": "Device updated"
}

Device Control

Control Relay (Power On/Off)

PUT /api/v2/devices/{device_id}/relay

Turn device relay on or off.

curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{"state": true}' https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/relay

Request Body:

{
  "state": true  // true = relay ON, false = relay OFF
}

Response:

{
  "success": true,
  "data": true,
  "message": "Relay state updated"
}

Set Device Mode

PUT /api/v2/devices/{device_id}/mode

Change the device's operating mode.

curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "prepaid"}' https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/mode

Request Body:

{
  "mode": "prepaid"  // "prepaid" | "postpaid" | "measurement" | "relay_off"
}

Supported Modes:

prepaid: Relay disconnects if balance is below zero
postpaid: Relay stays connected, allowing negative balance
measurement: Measures usage without billing; balance unaffected
relay_off: Forcibly disconnects relay, overriding other states

Response:

{
  "success": true,
  "data": true,
  "message": "Mode updated"
}

Tariff Management

Set EB Tariff

PUT /api/v2/devices/{device_id}/tariffs/eb

Set Electricity Board tariff in paise.

curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{"tariff": 500}' https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/tariffs/eb

Request Body:

{
  "tariff": 500  // Tariff in paise (500 paise = ₹5.00 per unit)
}

Set DG Tariff

PUT /api/v2/devices/{device_id}/tariffs/dg

Set Diesel Generator tariff in paise.

curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{"tariff": 800}' https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/tariffs/dg

Set Active Tariff

PUT /api/v2/devices/{device_id}/tariffs/active

Activate EB (1) or DG (2) tariff for billing.

curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{"active_tariff": 1}' https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/tariffs/active

Request Body:

{
  "active_tariff": 1  // 1 = EB tariff, 2 = DG tariff
}

Historical Data

Get Historical Metrics

GET /api/v2/devices/{device_id}/metrics/history

Fetch historical values for a device metric in the given date range.

curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" \
  "https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/metrics/history?property_id=energy&from_date=2025-01-01&to_date=2025-01-31&interval=1d"

Query Parameters:

property_id: The property to get history for (energy, active_power, voltage, etc.)
from_date: Start date (YYYY-MM-DD)
to_date: End date (YYYY-MM-DD)
interval: Data interval (15m, 30m, 60m, 1d)

Response:

{
  "success": true,
  "data": {
    "device_id": "QUBE-ONE-<some-id>",
    "from_date": "2025-01-01",
    "to_date": "2025-01-31",
    "readings": [
      {
        "property_id": "energy",
        "value": 1000.0,
        "unit": "kWh",
        "timestamp": "2025-01-01T23:59:59+05:30"
      },
      {
        "property_id": "energy",
        "value": 1025.5,
        "unit": "kWh",
        "timestamp": "2025-01-02T23:59:59+05:30"
      }
    ]
  }
}

Note: Timestamps are in Asia/Kolkata timezone. To calculate consumption, subtract the first reading from the last reading in your date range.

WiFi Management

Get WiFi Settings

GET /api/v2/devices/{device_id}/wifi

Get current WiFi SSID/password and signal strength.

curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/wifi

Response:

{
  "success": true,
  "data": {
    "ssid": "MyWiFiNetwork",
    "password": "mypassword123",
    "rssi": -45,
    "type": "Primary"
  }
}

Set WiFi Settings

POST /api/v2/devices/{device_id}/wifi

Set primary WiFi SSID and password on device.

curl -s -X POST -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "ssid": "NewWiFiNetwork",
    "password": "newpassword123"
  }' https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/wifi

Request Body:

{
  "ssid": "NewWiFiNetwork",    // Max 32 characters
  "password": "newpassword123" // Max 64 characters
}

Payment Gateway

Enable/Disable Payment Gateway

PUT /api/v2/devices/{device_id}/payments/gateway

Enable or disable the payment gateway for the device.

curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{"state": false}' https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/payments/gateway

Request Body:

{
  "state": false  // true = enable, false = disable
}

Response:

{
  "success": true,
  "data": true,
  "message": "Payment gateway state updated"
}

Error Responses

When an error occurs, you'll receive a response with success: false:

{
  "success": false,
  "error": {
    "code": "device_not_found",
    "detail": "You are not allowed to access the specified device. Or the specified device does not exist."
  },
  "timestamp": "2025-01-01T12:00:00.000Z"
}

Common Error Codes:

device_not_found: Device doesn't exist or you don't have access
validation_error: Request body validation failed
device_offline: Device is not online for control operations
not_your_space: Space doesn't belong to your account
authentication_error: Invalid or missing API key

Endpoints

On this page