Device Management

Device Management API provides device query, update, delete, and group management functions. Note that devices can only be added to organizations through the bind endpoint, direct creation is not supported.

List Devices

Retrieve all devices for the current organization.

Request

GET /api/v2/devices/

Query Parameters

Parameter	Type	Required	Description
search	string	No	Search by device ID or description
group	string	No	Filter by group ID, use 'none' for ungrouped devices

Response

[
    {
        "id": "device_id",
        "device_id": "Device ID",
        "info": "Device description",
        "group": {
            "id": "group_id",
            "name": "Group name"
        },
        "allow": true,
        "bind_time": "2024-01-08T10:00:00Z",
        "create_time": "2024-01-08T10:00:00Z"
    }
]

Examples

Python

import requests

# Configuration
API_BASE = "https://ums.holdingbyte.com/api/v2"
ACCESS_TOKEN = "your_access_token"

def list_devices(search=None, group=None):
    """List devices
    
    Args:
        search: Search keyword
        group: Group ID, 'none' for ungrouped devices
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    params = {}
    if search:
        params['search'] = search
    if group:
        params['group'] = group
    
    url = f"{API_BASE}/devices/"
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Usage examples
# Get all devices
devices = list_devices()
print("All devices:", devices)

# Search devices
devices = list_devices(search="temperature")
print("Search results:", devices)

# Get devices from specific group
devices = list_devices(group="group_1")
print("Group devices:", devices)

cURL

# Get all devices
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/" \
     -H "Authorization: Bearer your_access_token"

# Search devices
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/?search=temperature" \
     -H "Authorization: Bearer your_access_token"

# Get devices from specific group
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/?group=group_1" \
     -H "Authorization: Bearer your_access_token"

Get Device Details

Retrieve detailed information for a single device.

Request

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

Response

Returns single device information, same format as list items.

Examples

Python

def get_device(device_id):
    """Get device details
    
    Args:
        device_id: Device ID
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    url = f"{API_BASE}/devices/{device_id}/"
    response = requests.get(url, headers=headers)
    return response.json()

# Usage example
device_id = "device_1"
device = get_device(device_id)
print(f"Device details: {device}")

cURL

curl -X GET "https://ums.holdingbyte.com/api/v2/devices/device_1/" \
     -H "Authorization: Bearer your_access_token"

Update Device Information

Update basic device information.

Request

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

Request Parameters

Field	Type	Required	Description
info	string	No	Device description
group	string	No	Device group ID
allow	boolean	No	Whether to allow access

Request Example

{
    "info": "New device description",
    "group": "group_id",
    "allow": true
}

Response

Returns updated device information, same format as list items.

Examples

Python

def update_device(device_id, info=None, group=None, allow=None):
    """Update device information
    
    Args:
        device_id: Device ID
        info: Device description
        group: Group ID
        allow: Whether to allow access
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {}
    if info is not None:
        data['info'] = info
    if group is not None:
        data['group'] = group
    if allow is not None:
        data['allow'] = allow
    
    url = f"{API_BASE}/devices/{device_id}/"
    response = requests.put(url, headers=headers, json=data)
    return response.json()

# Usage example
device_id = "device_1"
result = update_device(
    device_id,
    info="Temperature Sensor #1",
    group="group_1",
    allow=True
)
print(f"Update result: {result}")

cURL

curl -X PUT "https://ums.holdingbyte.com/api/v2/devices/device_1/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"info": "Temperature Sensor #1", "group": "group_1", "allow": true}'

Bind Device

Bind a device to the current organization.

Request

POST /api/v2/devices/bind/

Request Parameters

Field	Type	Required	Description
device_id	string	Yes	Device ID
safe_code	string	Yes	Device safety code

Request Example

{
    "device_id": "device_id",
    "safe_code": "safe_code"
}

Response

Returns device information after successful binding, same format as list items.

Examples

Python

def bind_device(device_id, safe_code):
    """Bind device
    
    Args:
        device_id: Device ID
        safe_code: Device safety code
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {
        "device_id": device_id,
        "safe_code": safe_code
    }
    
    url = f"{API_BASE}/devices/bind/"
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Usage example
device_id = "device_1"
safe_code = "1234567890"
result = bind_device(device_id, safe_code)
print(f"Binding result: {result}")

cURL

curl -X POST "https://ums.holdingbyte.com/api/v2/devices/bind/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"device_id": "device_1", "safe_code": "1234567890"}'

Unbind Device

Remove the binding relationship between device and current organization.

Request

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

Response

Successful unbinding returns 204 status code with no response content.

Examples

Python

def unbind_device(device_id):
    """Unbind device
    
    Args:
        device_id: Device ID
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    url = f"{API_BASE}/devices/{device_id}/unbind/"
    response = requests.post(url, headers=headers)
    return response.status_code == 204

# Usage example
device_id = "device_1"
success = unbind_device(device_id)
print(f"Unbinding {'successful' if success else 'failed'}")

cURL

curl -X POST "https://ums.holdingbyte.com/api/v2/devices/device_1/unbind/" \
     -H "Authorization: Bearer your_access_token"