Open API Reference

The YenGear IoT Cloud Open API lets external systems read device data, manage projects, devices, and points, send point commands, and export history over HTTPS. The YenGear IoT Cloud console uses the same API.

Base URL

https://dl.yengear.com/api/v2

Every path in this reference is relative to https://dl.yengear.com.

Quick start

1. Ask an organization Owner to create an API token with the role and project scope you need. See Authentication.
2. Send the token as a bearer token:

curl 'https://dl.yengear.com/api/v2/projects/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

3. Read the result from data:

{
  "success": true,
  "data": [
    {
      "project_id": "proj_AbCdEfGhIj",
      "name": "Greenhouse Alpha",
      "device_count": 42,
      "offline_device_count": 3
    }
  ],
  "error": null
}

Data model

Organization                (slug: yengear)
  └── Project               (project_id: proj_AbCdEfGhIj)
        └── Device          (id: 42, serial_number, agri_id: d-1000-abcd)
              └── Point     (id: 12, agri_id: d-1000-abcd-1-00)

A point agri_id extends its device agri_id: {device_agri_id}-{slave_id}-{address}{data_index}. Telemetry and history use point agri_id values; management routes use numeric id values. See Field Reference.

Response format

Successful 200 and 201 responses wrap the result in an envelope:

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

data holds an object, an array, or null. 204 No Content responses have an empty body, and file downloads return the raw file. Failed requests return success: false with an error object; see Errors.

Pagination

List endpoints return the complete array without pagination, except:

Endpoint	Parameters	Defaults
GET /api/v2/data/{point_agri_id}/	page, page_size	page_size 50
GET /api/v2/data-download-tasks/	page, page_size	page_size 50, max 100

Paginated responses put count, next, previous, and results inside data.

Timestamps

• Date-time fields such as created_at, bind_time, and expires_at are ISO 8601 strings.
• Telemetry time t, history filters, and export ranges are Unix seconds (UTC). Millisecond values are rejected.

Caching

The organization, token, project, device, and point lists are cached for up to 60 seconds. A change made through the API clears the affected list. Device connection fields (is_online, connect_time) can lag by up to 60 seconds.

Rate limits

The API does not publish a per-token quota. Send readings from one sampling cycle in one request, poll live values no faster than the device reporting interval, and retry 503 responses with exponential backoff.

Versioning

All endpoints live under /api/v2/. Responses may gain new fields without a version change, so clients should ignore fields they do not recognize.

Endpoints

Organizations

Method	Endpoint	Description
GET	/api/v2/organizations/	List organizations of the signed-in user
GET	/api/v2/organizations/{slug}/	Retrieve an organization
GET	/api/v2/organizations/{slug}/membership/	Retrieve membership status
PATCH	/api/v2/organizations/{slug}/	Update an organization

Tokens

Method	Endpoint	Description
GET	/api/v2/tokens/	List API tokens
GET	/api/v2/tokens/{id}/	Retrieve a token
POST	/api/v2/tokens/	Create a token
PATCH	/api/v2/tokens/{id}/	Update a token
DELETE	/api/v2/tokens/{id}/	Delete a token

Projects

Method	Endpoint	Description
GET	/api/v2/projects/	List projects
GET	/api/v2/projects/{project_id}/	Retrieve a project
POST	/api/v2/projects/	Create a project
PATCH	/api/v2/projects/{project_id}/	Update a project
DELETE	/api/v2/projects/{project_id}/	Delete a project
POST	/api/v2/projects/{project_id}/transfer/	Transfer a project to another organization

Devices

Method	Endpoint	Description
GET	/api/v2/devices/	List devices in the organization
GET	/api/v2/devices/unassigned/	List unassigned devices
POST	/api/v2/devices/{id}/assign-project/	Assign a device to a project
GET	/api/v2/projects/{project_id}/devices/	List devices in a project
GET	/api/v2/projects/{project_id}/devices/{device}/	Retrieve a device
PATCH	/api/v2/projects/{project_id}/devices/{device}/	Update a device
POST	/api/v2/projects/{project_id}/devices/bind/	Bind a device
POST	/api/v2/projects/{project_id}/devices/{device}/unbind/	Unbind a device
POST	/api/v2/projects/{project_id}/devices/{device}/set-project/	Move a device to another project
POST	/api/v2/projects/{project_id}/devices/{device}/transfer-to-org/	Transfer a device to another organization
POST	/api/v2/projects/{project_id}/devices/{device}/set-serial/	Set serial parameters
POST	/api/v2/projects/{project_id}/devices/{device}/set-tcp/	Set the TCP server
POST	/api/v2/projects/{project_id}/devices/{device}/set-heartbeat/	Set heartbeat parameters
POST	/api/v2/projects/{project_id}/devices/{device}/export-points/	Export point configuration
POST	/api/v2/projects/{project_id}/devices/{device}/import-points/	Import point configuration
POST	/api/v2/projects/{project_id}/devices/{device}/add-module/	Add points from a module template

Device data

Method	Endpoint	Description
GET	/api/v2/projects/{project_id}/devices/{device}/data/	Retrieve the latest value of each point
POST	/api/v2/projects/{project_id}/devices/{device}/data/	Report device data (gateway tokens)

Points

Method	Endpoint	Description
GET	/api/v2/projects/{project_id}/devices/{device_id}/points/	List points
GET	/api/v2/projects/{project_id}/devices/{device_id}/points/{id}/	Retrieve a point
POST	/api/v2/projects/{project_id}/devices/{device_id}/points/	Create a point
PATCH	/api/v2/projects/{project_id}/devices/{device_id}/points/{id}/	Update a point
DELETE	/api/v2/projects/{project_id}/devices/{device_id}/points/{id}/	Delete a point
POST	/api/v2/projects/{project_id}/devices/{device_id}/points/{id}/duplicate/	Duplicate a point
POST	/api/v2/projects/{project_id}/devices/{device_id}/points/{id}/{command}/	Send on, off, forward, antiport, or stop
POST	/api/v2/projects/{project_id}/devices/{device_id}/points/{id}/set-content/	Set display content
POST	/api/v2/projects/{project_id}/devices/{device_id}/points/{id}/set-alarm-level/	Set an alarm level
GET	/api/v2/projects/{project_id}/devices/{device_id}/points/{id}/current-data/	Retrieve the latest point value
POST	/api/v2/projects/{project_id}/devices/{device_id}/points/{id}/set-threshold/	Set thresholds
GET	/api/v2/projects/{project_id}/devices/{device_id}/points/threshold-points/	List points with thresholds
GET	/api/v2/projects/{project_id}/devices/{device_id}/points/options/	List configuration options
GET	/api/v2/data/{point_agri_id}/	List point history

Export tasks

Method	Endpoint	Description
GET	/api/v2/data-download-tasks/	List export tasks in the organization
GET	/api/v2/projects/{project_id}/data-download-tasks/	List export tasks in a project
GET	/api/v2/projects/{project_id}/data-download-tasks/options/	Retrieve export limits
POST	/api/v2/projects/{project_id}/data-download-tasks/	Create an export task
GET	/api/v2/projects/{project_id}/data-download-tasks/{id}/	Retrieve an export task
POST	/api/v2/projects/{project_id}/data-download-tasks/{id}/cancel/	Cancel an export task
POST	/api/v2/projects/{project_id}/data-download-tasks/{id}/retry/	Retry an export task
GET	/api/v2/projects/{project_id}/data-download-tasks/{id}/download/	Get a download URL
DELETE	/api/v2/projects/{project_id}/data-download-tasks/{id}/	Delete an export task

Related

• Authentication
• Errors
• Field Reference
• Use the Open API