Open API Documentation

The Open API provides RESTful interfaces for devices, factors, and data management, enabling you to quickly build IoT applications.

You can also access the Device Management Platform to manage your devices, factors, and more.

API Basics

• Base URL: https://ums.holdingbyte.com
• API Version: v2
• Base Path: /api/v2/

For example, the complete device list endpoint is: https://ums.holdingbyte.com/api/v2/devices/

Documentation Structure

• Base Data: System configuration options and device type information
• Organization Management: Organization information and token management
• Device Groups: Device group management
• Device Management: Device CRUD operations
• Device Factors: Device factor configuration and management
• Device Data: Real-time device data queries

Request Format

All requests must be in JSON format. Set the following header:

Content-Type: application/json

Token Authentication

The API supports token authentication for third-party applications and automated scripts. Include the token in your request header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Requirements:

• Token must be valid and not expired
• Token must be active (is_active=true)
• Token's associated organization must be valid
• If token has an expiration time (expires_at), it must be within the valid period

You can manage tokens in the Device Management Platform.

Response Format

All responses are in JSON format with a consistent structure:

Success Response

For successful requests (HTTP status 200):

{
    "success": true,
    "data": {
        // Response data
    },
    "error": null
}

For paginated data:

{
    "success": true,
    "data": {
        "count": 100,
        "next": "https://ums.holdingbyte.com/api/v2/devices/?page=2",
        "previous": null,
        "results": [
            // Data list
        ]
    },
    "error": null
}

Error Response

For failed requests (non-200 HTTP status):

{
    "success": false,
    "data": null,
    "error": {
        "code": "ERROR_CODE",
        "message": "Error message"
    }
}

Common Status Codes:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 500: Internal Server Error

Pagination

List endpoints support pagination with the following parameters:

• page: Page number (default: 1)
• page_size: Items per page (default: 20)

Filtering and Sorting

Most list endpoints support filtering and sorting:

• Filtering: Use appropriate query parameters
• Sorting: Use the ordering parameter, e.g., ?ordering=-created_at

Rate Limits

• The API implements rate limiting. Please control request frequency appropriately
• Maximum request body size: 10MB
• Maximum file upload size: 50MB