Device data

Device data endpoints return the latest value of each point on a device and accept telemetry from device gateways. Values live in a real-time store that keeps one latest value per point agri_id. For past readings, use List point history or export tasks.

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

{device} accepts the numeric device id or the serial_number.

The data item object

{
  "agri_id": "d-1000-abcd-1-00",
  "value": 23.5,
  "the_type": 1,
  "unit": "℃",
  "t": 1708070400,
  "project_id": "proj_AbCdEfGhIj",
  "org_slug": "yengear"
}

Field	Type	Description
agri_id	string	Point agri_id
value	number	Latest value
the_type	integer	Point type ID
unit	string	Unit recorded with the value
t	integer	Observation time in Unix seconds (UTC)
project_id	string | null	Project the value was reported under
org_slug	string | null	Organization the value was reported under

Extra keys sent by the gateway appear in the object as well.

Retrieve latest device data

GET /api/v2/projects/{project_id}/devices/{device}/data/

Returns the latest value of each point whose agri_id starts with the device agri_id. Points that have never reported are absent.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Project identifier
device	string	Yes	Device id or serial_number

Example request

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

Example response

{
  "success": true,
  "data": [
    { "agri_id": "d-1000-abcd-1-00", "value": 23.5, "the_type": 1, "unit": "℃", "t": 1708070400, "project_id": "proj_AbCdEfGhIj", "org_slug": "yengear" },
    { "agri_id": "d-1000-abcd-1-10", "value": 1, "the_type": 200, "unit": "", "t": 1708070340, "project_id": "proj_AbCdEfGhIj", "org_slug": "yengear" }
  ],
  "error": null
}

Responses

• 200: Array of data items; empty when the device has no data.
• 404: The device is not in the project.
• 503: The real-time store is unavailable.

Report device data

POST /api/v2/projects/{project_id}/devices/{device}/data/

Accepts readings for the device's points, sends them to the processing queue (rules, history, alerts, data forwarding), and updates the real-time store.

Authentication

Gateway token only. The platform issues gateway tokens for device gateways; API tokens and users receive 403.

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Project identifier
device	string	Yes	Device id or serial_number

Request body

A non-empty JSON array of objects:

Name	Type	Required	Description
agri_id	string	Yes	Point agri_id. Must start with {device_agri_id}-; other rows are skipped.
value	number	Yes	Reading. The server does not check it.
t	integer	No	Observation time in Unix seconds. The server receive time is used when omitted.
the_type	integer	No	Filled from the point configuration when omitted. Rows for points that do not exist are skipped.

Other keys are stored with the reading and returned by Retrieve latest device data.

t is checked across the batch. One row with a non-integer, negative, future, or millisecond t rejects the whole request.

Server-side processing

For each accepted row, the server:

1. Fills the_type and t when missing.
2. Drops client-supplied project_id, org_id, and org_slug.
3. Adds project_id and org_id (the organization slug) from the device's project.

Example request

curl -X POST 'https://dl.yengear.com/api/v2/projects/proj_AbCdEfGhIj/devices/42/data/' \
  -H 'Authorization: Bearer YOUR_GATEWAY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
    {"agri_id": "d-1000-abcd-1-00", "value": 24.3, "t": 1708070400},
    {"agri_id": "d-1000-abcd-1-10", "value": 68.2}
  ]'

Example response

{
  "success": true,
  "data": [
    { "agri_id": "d-1000-abcd-1-00", "value": 24.3, "t": 1708070400, "the_type": 1, "project_id": "proj_AbCdEfGhIj", "org_id": "yengear" },
    { "agri_id": "d-1000-abcd-1-10", "value": 68.2, "t": 1708070455, "the_type": 2, "project_id": "proj_AbCdEfGhIj", "org_id": "yengear" }
  ],
  "error": null
}

The response lists accepted rows only. Compare it with the request to find skipped rows.

Responses

• 200: Accepted rows.
• 400: The body is not a non-empty array of objects, a t value is invalid, or no row was accepted (No valid data to report.).
• 403: The request did not use a gateway token.
• 404: The device is not in the project.
• 500: Writing to the queue or the real-time store failed. Retry the batch with the same t values.

Reporting tips

• Send t with every row. The API does not deduplicate, and downstream services use t to spot repeats.
• Send all readings of one sampling cycle in one request.

Related

• Points
• Data viewing in the console
• Data forwarding