Points

A point is one data channel on a device, usually one Modbus register. Its configuration sets how to read the register, how to scale the value, and which alert thresholds apply. Point endpoints also send commands to switch, motor, display, and alarm points.

Point routes use the numeric device id as {device_id}; serial numbers are not accepted here. {id} is the numeric point ID.

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

The point object

json

{
  "id": 12,
  "agri_id": "d-1000-abcd-1-00",
  "device_id": 5,
  "name": "Inlet Temperature",
  "slave_id": 1,
  "address": 0,
  "the_type": 1,
  "the_type_detail": {
    "the_type": 1,
    "name": "Temperature",
    "name_en": "Temperature",
    "name_zh_hans": "温度",
    "unit": "℃",
    "value_type": 1,
    "icon_url": "https://dl.yengear.com/media/icon/temp.png",
    "is_shared": true
  },
  "data_endian": ">",
  "data_endian_display": "Big-Endian (ABCD)",
  "data_type": "int16",
  "data_type_display": "16-bit Integer",
  "data_index": 0,
  "modbus_type": 3,
  "modbus_type_display": "Holding Register",
  "data_scale": 0.1,
  "data_delta": 0.0,
  "min_value": null,
  "max_value": null,
  "info": null,
  "enabled": true
}

Field	Type	Default	Description
`id`	integer	—	Point ID (read-only)
`agri_id`	string	—	`{device_agri_id}-{slave_id}-{address}{data_index}` (read-only)
`device_id`	integer	—	Parent device ID (read-only)
`name`	string \| null	`null`	Point name, up to 32 characters
`slave_id`	integer	`0`	Modbus slave ID
`address`	integer	`0`	Register address, 0–65535
`data_index`	integer	`0`	Offset for multi-register reads, 0–9
`the_type`	integer	`0`	Point type ID; see List configuration options
`the_type_detail`	object	—	Point type name, unit, value type, and icon (read-only)
`modbus_type`	integer	`3`	`0` unknown, `1` coil, `2` discrete input, `3` holding register, `4` input register
`data_type`	string	`int16`	`int8`, `uint16`, `int16`, `uint32`, `int32`, `float32`, or `f32_2_i16`
`data_endian`	string	`>`	`@` auto, `>` ABCD, `<` DCBA, `<_SB` BADC, `<_SW` CDAB
`data_scale`	number	`1`	Value = raw × `data_scale` + `data_delta`
`data_delta`	number	`0`	Offset added after scaling
`min_value`	number \| null	`null`	Lower alert threshold
`max_value`	number \| null	`null`	Upper alert threshold
`enabled`	boolean	`true`	Whether the device reads the point
`info`	string \| null	`null`	Note, up to 64 characters

modbus_type_display, data_type_display, and data_endian_display carry the labels for the coded fields.

Device models with capability bit 0x20 allow full point configuration. On other models, only name and info can change, and create, delete, duplicate, and threshold requests return 400.

List points

http

GET /api/v2/projects/{project_id}/devices/{device_id}/points/

Returns the device's points ordered by slave_id, address, and data_index.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID

Example request

bash

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

Responses

200: Array of point objects, not paginated. Cached until a point changes.
403: The project is outside the token's scope.
404: The device is not in the organization.

Retrieve a point

http

GET /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/

Returns one point.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID
`id`	integer	Yes	Point ID

Responses

200: The point object.
404: The point or device does not exist in the organization.

Create a point

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/

Adds a point to a device.

Authentication

Bearer token. Minimum role: Manager.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID

Request body

Any writable field of the point object. Omitted fields take their defaults. Send slave_id, address, and data_index explicitly: together they identify the point and form its agri_id.

Example request

bash

curl -X POST 'https://dl.yengear.com/api/v2/projects/proj_AbCdEfGhIj/devices/5/points/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Inlet Temperature",
    "slave_id": 1,
    "address": 0,
    "data_index": 0,
    "the_type": 1,
    "modbus_type": 3,
    "data_type": "int16",
    "data_endian": ">",
    "data_scale": 0.1
  }'

Responses

201: The created point object.
400: A point with the same slave_id, address, and data_index exists; the device model does not allow editing points; or a threshold is invalid.
403: Role below Manager, or the plan's point quota is reached (membership_quota_exceeded).

Update a point

http

PATCH /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/

Updates point fields. PUT behaves the same as PATCH: send only the fields to change.

Authentication

Bearer token. Minimum role: Manager.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID
`id`	integer	Yes	Point ID

Example request

bash

curl -X PATCH 'https://dl.yengear.com/api/v2/projects/proj_AbCdEfGhIj/devices/5/points/12/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"data_scale": 0.01, "info": "Scaled to volts"}'

Responses

200: The updated point object.
400: Validation error, or a field other than name and info on a device model that does not allow editing points.

Delete a point

http

DELETE /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/

Deletes a point.

Authentication

Bearer token. Minimum role: Manager.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID
`id`	integer	Yes	Point ID

Responses

204: Point deleted.
400: The device model does not allow editing points.
409 point_in_use: Automations or other configuration still reference the point. Remove the references first.

Duplicate a point

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/duplicate/

Copies a point. The copy gets the next free data_index for the same slave_id and address, and its name gains the suffix _<data_index + 1>.

Authentication

Bearer token. Minimum role: Manager.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID
`id`	integer	Yes	Point ID to copy

Responses

201: The new point object.
400: The device model does not allow editing points.

Send a switch or motor command

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/{command}/

Sends a command to a switch or motor point through the platform gateway. A 200 response means the gateway accepted the command; check the point value or the operation log for the field result.

Authentication

Bearer token. Minimum role: Operator. When the plan is read-only, off and stop stay available for safety shutdowns.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID
`id`	integer	Yes	Point ID
`command`	string	Yes	`on`, `off`, `forward` (motor forward), `antiport` (motor reverse), or `stop`

Request body

Name	Type	Required	Description
`r_token`	string	No	Your request token, 1–32 characters without surrounding spaces. Also accepted as the `r_token` query parameter; if you send both, they must match. The server generates a 12-character token when omitted.

Example request

bash

curl -X POST 'https://dl.yengear.com/api/v2/projects/proj_AbCdEfGhIj/devices/5/points/18/on/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"r_token": "pump-on-0001"}'

Example response

json

{
  "success": true,
  "data": {
    "success": true,
    "data": {},
    "message": "Operation succeeded",
    "token": "pump-on-0001"
  },
  "error": null
}

data.message is display text from the gateway. data.token is the request token. Store it to match the command with device acknowledgements and the project's point operation log.

Responses

200: The gateway accepted the command.
400: Invalid r_token, or the gateway rejected the command (error.message holds the reason).
403: Role below Operator, or the plan is read-only and the command is not off or stop.

Set display content

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/set-content/

Sends text to an LED or digit display point.

Authentication

Bearer token. Minimum role: Operator.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID
`id`	integer	Yes	Point ID

Request body

Name	Type	Required	Description
`content`	string	Yes	Text to display
`r_token`	string	No	Request token, as in Send a switch or motor command

Example request

bash

curl -X POST 'https://dl.yengear.com/api/v2/projects/proj_AbCdEfGhIj/devices/5/points/21/set-content/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"content": "Gate 3 open"}'

Responses

200: Same body as Send a switch or motor command.
400: content is missing or not a string, or the gateway rejected the command.

Set an alarm level

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/set-alarm-level/

Sets the level of an alarm point.

Authentication

Bearer token. Minimum role: Operator.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID
`id`	integer	Yes	Point ID

Request body

Name	Type	Required	Description
`level`	integer	Yes	Alarm level, 0–5
`r_token`	string	No	Request token

Responses

200: Same body as Send a switch or motor command.
400: level is missing or outside 0–5, or the gateway rejected the command.

Retrieve the latest point value

http

GET /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/current-data/

Returns the point's latest value from the real-time store.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID
`id`	integer	Yes	Point ID

Example response

json

{
  "success": true,
  "data": {
    "agri_id": "d-1000-abcd-1-00",
    "value": 24.5,
    "the_type": 1,
    "unit": "℃",
    "t": 1704758400,
    "project_id": "proj_AbCdEfGhIj",
    "org_slug": "yengear"
  },
  "error": null
}

Responses

200: A data item. For a point that has never reported, data contains only agri_id.
503: The real-time store is unavailable.

Set thresholds

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/set-threshold/

Sets the alert range of a sensor point.

Authentication

Bearer token. Minimum role: Manager.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID
`id`	integer	Yes	Point ID

Request body

Name	Type	Required	Description
`min_value`	number \| null	No	Lower threshold; `null` clears it
`max_value`	number \| null	No	Upper threshold; `null` clears it

Only sensor-type points accept thresholds. Values must be finite. When both thresholds are set, min_value must be lower than max_value, counting the stored value of a field you leave out.

Example request

bash

curl -X POST 'https://dl.yengear.com/api/v2/projects/proj_AbCdEfGhIj/devices/5/points/12/set-threshold/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"min_value": 5.0, "max_value": 35.0}'

Responses

200: data contains min_value and max_value.
400: The point is not a sensor type, a value is invalid, min_value is not lower than max_value, or the device model does not allow editing points.

List points with thresholds

http

GET /api/v2/projects/{project_id}/devices/{device_id}/points/threshold-points/

Returns the device's points that have min_value or max_value set.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID

Responses

200: Array of point objects.

List configuration options

http

GET /api/v2/projects/{project_id}/devices/{device_id}/points/options/

Returns the values accepted by modbus_type, data_type, data_endian, and the_type. Each *_choices entry is a [value, label] pair; send the value. point_types lists shared types first, then the organization's custom types.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project identifier
`device_id`	integer	Yes	Device ID

Example response

json

{
  "success": true,
  "data": {
    "modbus_type_choices": [[0, "Unknown"], [1, "Coil"], [2, "Discrete Input"], [3, "Holding Register"], [4, "Input Register"]],
    "data_type_choices": [["int8", "8-bit Integer"], ["uint16", "16-bit Unsigned Integer"], ["int16", "16-bit Integer"], ["uint32", "32-bit Unsigned Integer"], ["int32", "32-bit Integer"], ["float32", "32-bit Float"], ["f32_2_i16", "32-bit Float from 2x16-bit"]],
    "data_endian_choices": [["@", "Auto"], [">", "Big-Endian (ABCD)"], ["<", "Little-Endian (DCBA)"], ["<_SB", "Little-Endian (BADC)"], ["<_SW", "Little-Endian (CDAB)"]],
    "point_types": [
      { "the_type": 1, "name": "Temperature", "name_en": "Temperature", "name_zh_hans": "温度", "unit": "℃", "value_type": 1, "icon_url": "https://dl.yengear.com/media/icon/temp.png", "is_shared": true }
    ]
  },
  "error": null
}

Responses

200: Configuration options.

List point history

http

GET /api/v2/data/{point_agri_id}/

Returns saved readings of one point, newest first. The API checks that the point's device belongs to the caller's organization and project scope.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
`point_agri_id`	string	Yes	Point `agri_id`, for example `d-1000-abcd-1-00`

Query parameters

Name	Type	Required	Description
`page`	integer	No	Page number. Default `1`.
`page_size`	integer	No	Records per page. Default `50`. Keep it to a few hundred at most.
`min_timestamp`	integer	No	Earliest `t` to return, in Unix seconds. Default: 90 days ago.

Example request

bash

curl 'https://dl.yengear.com/api/v2/data/d-1000-abcd-1-00/?page=1&page_size=50&min_timestamp=1704758400' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Example response

json

{
  "success": true,
  "data": {
    "count": 100,
    "next": "?page=2&page_size=50",
    "previous": null,
    "results": [
      { "agri_id": "d-1000-abcd-1-00", "v": 24.2, "t": 1704758400 }
    ]
  },
  "error": null
}

History records name the value v, while live endpoints use value. next and previous are query strings to append to the same path.

Responses

200: A page of readings.
400: page or page_size is not an integer.
404: The device does not exist or is outside the caller's scope.

Points ​

The point object ​

List points ​

Authentication ​

Path parameters ​

Example request ​

Responses ​

Retrieve a point ​

Authentication ​

Path parameters ​

Responses ​

Create a point ​

Authentication ​

Path parameters ​

Request body ​

Example request ​

Responses ​

Update a point ​

Authentication ​

Path parameters ​

Example request ​

Responses ​

Delete a point ​

Authentication ​

Path parameters ​

Responses ​

Duplicate a point ​

Authentication ​

Path parameters ​

Responses ​

Send a switch or motor command ​

Authentication ​

Path parameters ​

Request body ​

Example request ​

Example response ​

Responses ​

Set display content ​

Authentication ​

Path parameters ​

Request body ​

Example request ​

Responses ​

Set an alarm level ​

Authentication ​

Path parameters ​

Request body ​

Responses ​

Retrieve the latest point value ​

Authentication ​

Path parameters ​

Example response ​

Responses ​

Set thresholds ​

Authentication ​

Path parameters ​

Request body ​

Example request ​

Responses ​

List points with thresholds ​

Authentication ​

Path parameters ​

Responses ​

List configuration options ​

Authentication ​

Path parameters ​

Example response ​

Responses ​

List point history ​

Authentication ​

Path parameters ​

Query parameters ​

Example request ​

Example response ​

Responses ​

Related ​

Points

The point object

List points

Authentication

Path parameters

Example request

Responses

Retrieve a point

Authentication

Path parameters

Responses

Create a point

Authentication

Path parameters

Request body

Example request

Responses

Update a point

Authentication

Path parameters

Example request

Responses

Delete a point

Authentication

Path parameters

Responses

Duplicate a point

Authentication

Path parameters

Responses

Send a switch or motor command

Authentication

Path parameters

Request body

Example request

Example response

Responses

Set display content

Authentication

Path parameters

Request body

Example request

Responses

Set an alarm level

Authentication

Path parameters

Request body

Responses

Retrieve the latest point value

Authentication

Path parameters

Example response

Responses

Set thresholds

Authentication

Path parameters

Request body

Example request

Responses

List points with thresholds

Authentication

Path parameters

Responses

List configuration options

Authentication

Path parameters

Example response

Responses

List point history

Authentication

Path parameters

Query parameters

Example request

Example response

Responses

Related