Open API Documentation

The Yanji Iot Cloud Open API exposes RESTful endpoints for organization, project, device, factor, and data workflows so integrators can build IoT solutions without leaving their preferred toolchain. This document outlines the shared conventions before diving into each resource-specific guide.

You can always manage the same resources through the Yanji Iot Cloud.

Introduction

• Audience: SaaS integrators, device partners, and internal engineers who need stable APIs for provisioning hardware, collecting telemetry, and issuing control commands.
• Base URL: https://dl.holdingbyte.com
• Versioning: All endpoints described here live under /api/v2/. Version upgrades are announced in the changelog with clear migration notes.
• Environment: Unless otherwise stated, examples target the production cluster. Staging credentials follow the same structure.

Documentation Structure

Each resource group includes an overview, endpoint matrix, detailed request/response specs, error cases, and runnable examples:

1. Base Data
2. Organization Management
3. Organization Tokens
4. Projects
5. Devices
6. Device Factors
7. Device Data
8. Download Tasks

Use the Field Reference for shared terms such as agri_id, project_id, and device type codes.

Request & Response Conventions

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

Request Bodies

• JSON encoded with UTF-8.
• Use snake_case keys to align with the API payload schema.
• Timestamps use integer seconds or ISO 8601 strings depending on the endpoint; refer to resource docs.

Success Envelope

{
    "success": true,
    "data": {
        "...": "..."
    },
    "error": null
}

Paginated responses include DRF pagination metadata:

{
    "success": true,
    "data": {
        "count": 125,
        "next": "https://dl.holdingbyte.com/api/v2/devices/?page=3",
        "previous": null,
        "results": [
            { "id": "device_001", "info": "Cold-room sensor" }
        ]
    },
    "error": null
}

Error Envelope

{
    "success": false,
    "data": null,
    "error": {
        "code": "DEVICE_NOT_FOUND",
        "message": "Device device_001 does not exist or is not bound"
    }
}

Common HTTP codes:

Status	Meaning	Typical Cause
200	Success	Request processed
201	Created	Resource successfully created
204	No Content	Delete or unbind succeeded
400	Bad Request	Validation failure or missing parameter
401	Unauthorized	Missing or invalid credentials
403	Forbidden	Caller lacks access to the requested resource
404	Not Found	Resource not available inside tenant
409	Conflict	Duplicate binding or state conflict
422	Unprocessable	Payload accepted but semantic rules failed
429	Too Many Requests	Rate limit exceeded
500	Server Error	Unexpected failure

Global Conventions

• Pagination: page (default 1) and page_size (default 20, max 200) query params. Some historical data endpoints expose limit/offset; those are documented per resource.
• Filtering: Resource guides document supported query arguments such as search, group, device_type, or min_timestamp.
• Ordering: Use ordering with field names, prefix with - for descending (?ordering=-bind_time). Not all endpoints enable ordering.
• Timestamps: Unless stated otherwise, timestamps are UTC ISO 8601 strings. Factor data exports may use integer seconds to reduce payload size.
• Units & Encoding: Sensor values retain their engineering units (℃, %RH, ppm). Strings are UTF-8; binary payloads are Base64 encoded.
• Caching: Several read endpoints enable short-lived caching (60–300 seconds). When cached, expect slightly stale data. Control commands and POST/PUT/DELETE operations are never cached.
• Data Retention: Historical factor data keeps 90 days by default. Plan exports before retention windows expire.

Rate Limits

• Burst limit: 60 requests per minute per access token.
• Sustained throughput: 10 requests per second averaged over five minutes.
• Maximum JSON body size: 10 MB.
• Maximum file upload size: 50 MB (applies to forwarders and bulk imports).
• When throttled (HTTP 429), honor the Retry-After header before retrying. Use exponential backoff for long-running synchronizers.