Devices

A device is a gateway or controller that connects to YenGear IoT Cloud. Devices join an organization only through Bind a device; the API does not create or delete 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

Live values and telemetry reporting are in Device data.

In project routes, {device} accepts the numeric device id or the serial_number.

The device object

{
  "id": 42,
  "device_name": "Cold-room node #1",
  "serial_number": "868686000123456",
  "agri_id": "d-1000-abcd",
  "project": { "name": "Cold Chain East", "project_id": "cold-chain-east" },
  "base_device": {
    "id": 3,
    "name": "Y301 Gateway",
    "model": "Y301-220",
    "image": null,
    "property": 48,
    "device_type": { "id": 1, "name": "Gateway", "name_en": "Gateway", "name_zh_hans": "网关" },
    "device_type_id": 1
  },
  "image": null,
  "status": 1,
  "bind_time": "2026-01-08T10:00:00Z",
  "info": "Walk-in freezer",
  "is_debug": false,
  "is_online": true,
  "has_thresholds": true,
  "device_config": {},
  "connect_time": "2026-02-16T09:58:12Z",
  "create_time": "2025-12-01T03:00:00Z"
}

Field	Type	Description
id	integer	Device ID, used as {device} and {device_id} in nested routes
device_name	string	Display name
serial_number	string	Hardware serial number (IMEI or SN)
agri_id	string	Platform device ID and the prefix of its point agri_id values
project	object | null	name and project_id of the owning project
base_device	object	Hardware model. property is a capability bitmask; bit 0x20 means points are editable.
image	string | null	Device image URL
status	integer	0 offline, 1 online, 2 error
is_online	boolean	true when connect_time is within the platform offline threshold
has_thresholds	boolean	true when a point of the device has min_value or max_value
info	string | null	Note, up to 128 characters
is_debug	boolean	Debug flag
device_config	object	Configuration reported by the platform (read-only)
bind_time, connect_time, create_time	string | null	Bind, last connection, and creation times

Non-members viewing an open project do not receive serial_number, info, device_config, or is_debug.

List organization devices

GET /api/v2/devices/

Returns devices in the organization, most recently bound first. Owner users also see unassigned devices; other callers see devices in the projects within their scope.

Authentication

Bearer token. Minimum role: Read-only.

Query parameters

Name	Type	Required	Description
search	string	No	Case-insensitive match on serial_number, device_name, or info
project_id	string	No	Return devices of one project

Example request

curl 'https://dl.yengear.com/api/v2/devices/?project_id=cold-chain-east&search=freezer' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Responses

• 200: Array of device objects, not paginated. Cached for up to 60 seconds.
• 403: Authentication failed.

List unassigned devices

GET /api/v2/devices/unassigned/

Returns devices that belong to the organization but not to a project, for example after a project is deleted or a device is transferred in.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user).

Query parameters

Name	Type	Required	Description
search	string	No	Case-insensitive match on serial_number, device_name, or info

Responses

• 200: Array of device objects.
• 403: The caller is not an Owner, or the request used an API token.

Assign a device to a project

POST /api/v2/devices/{id}/assign-project/

Places an unassigned device in a project.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user).

Path parameters

Name	Type	Required	Description
id	integer	Yes	Device ID

Request body

Name	Type	Required	Description
project_id	string	Yes	Target project

Responses

• 200: The updated device object.
• 400: project_id is missing.
• 404: The device is not in the unassigned pool, or the project does not exist.

List project devices

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

Returns the devices of one project, most recently bound first. This endpoint has no search parameter; use List organization devices with project_id and search to filter.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Project identifier

Example request

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

Responses

• 200: Array of device objects, not paginated. Cached for up to 60 seconds.
• 403: The project is outside the token's scope.

Retrieve a device

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

Returns one device.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Project identifier
device	string	Yes	Device id (for example 42) or serial_number

Example request

curl 'https://dl.yengear.com/api/v2/projects/cold-chain-east/devices/868686000123456/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Responses

• 200: The device object.
• 404: The device is not in the project.

Update a device

PATCH /api/v2/projects/{project_id}/devices/{device}/

Updates a device's name, note, or debug flag. PUT behaves the same as PATCH.

Authentication

Bearer token. Minimum role: Manager.

Path parameters

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

Request body

Name	Type	Required	Description
device_name	string	No	Display name
info	string	No	Note, up to 128 characters
is_debug	boolean	No	Debug flag

project is read-only; use Move a device to another project.

Example request

curl -X PATCH 'https://dl.yengear.com/api/v2/projects/cold-chain-east/devices/42/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"device_name": "Greenhouse #3 gateway", "info": "North wall"}'

Responses

• 200: The updated device object.
• 400: Validation error.
• 403: Role below Manager.

Bind a device

POST /api/v2/projects/{project_id}/devices/bind/

Adds a device to the organization and the project, using the serial number and safe code on the device label.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user).

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Project to bind into

Request body

Name	Type	Required	Description
serial_number	string	Yes	Serial number on the label
safe_code	string	Yes	Safe code on the label

Example request

curl -X POST 'https://dl.yengear.com/api/v2/projects/cold-chain-east/devices/bind/' \
  -H 'Authorization: Bearer YOUR_USER_JWT' \
  -H 'X-Organization-Slug: yengear' \
  -H 'Content-Type: application/json' \
  -d '{"serial_number": "868686000123456", "safe_code": "8K2P"}'

Responses

• 200: The bound device object.
• 400 device_already_assigned: The device is already in a project.
• 400 device_owned_by_other_org: The device belongs to another organization.
• 403 membership_quota_exceeded: The plan's device quota is reached.
• 404 invalid_device_credentials: Wrong serial number or safe code.
• 404: The project does not exist.

Unbind a device

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

Removes a device from its project and from the organization. Screens, automations, and other configuration that referenced the device lose that reference. Binding the device again requires its serial number and safe code.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user).

Path parameters

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

Responses

• 204: Device unbound.
• 403: The caller is not an Owner, or the request used an API token.
• 404: The device is not in the project.

Move a device to another project

POST /api/v2/projects/{project_id}/devices/{device}/set-project/

Moves a device to another project in the same organization. Configuration in the old project that referenced the device loses that reference.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user).

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Current project
device	string	Yes	Device id or serial_number

Request body

Name	Type	Required	Description
project_id	string	Yes	Target project in the same organization

Responses

• 200: The updated device object.
• 400: project_id is missing, or the target project is not in the organization.

Transfer a device to another organization

POST /api/v2/projects/{project_id}/devices/{device}/transfer-to-org/

Moves a device and its points into another organization's unassigned pool. The target plan must be active and have device and point quota.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user).

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Current project
device	string	Yes	Device id or serial_number

Request body

Name	Type	Required	Description
target_org_slug	string	Yes	Slug of the receiving organization

Responses

• 200: The device object in its new organization.
• 400: The device already belongs to the target organization.
• 403: The target plan is read-only or over quota.
• 404: The target organization does not exist.

Set serial parameters

POST /api/v2/projects/{project_id}/devices/{device}/set-serial/

Sends new serial settings to the device. The connection drops briefly while the device applies them, then reconnects. A 200 response means the platform dispatched the command.

Authentication

Bearer token. Minimum role: Manager.

Path parameters

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

Request body

Name	Type	Required	Description
baud_rate	integer	No	1200, 2400, 4800, 9600, 19200, 38400, 57600, or 115200. Default 9600.
data_bits	integer	No	7 or 8. Default 8.
stop_bits	integer	No	1, 15 (1.5 stop bits), or 2. Default 1.
parity	string	No	NONE, EVEN, ODD, MARK, or SPACE. Default NONE.
flow	string	No	485 or NONE. Default 485.

Example request

curl -X POST 'https://dl.yengear.com/api/v2/projects/cold-chain-east/devices/42/set-serial/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"baud_rate": 9600, "data_bits": 8, "stop_bits": 1, "parity": "NONE", "flow": "485"}'

Responses

• 200: Command dispatched; data contains message and serial_info (for example 9600,8,1,NONE,485).
• 400: Invalid value, or the device model does not support serial settings.
• 503: The gateway is unavailable or rejected the command.

Set the TCP server

POST /api/v2/projects/{project_id}/devices/{device}/set-tcp/

Points the device at a different TCP server. The device reconnects to the new address, so a wrong host or port takes it offline from YenGear IoT Cloud.

Authentication

Bearer token. Minimum role: Manager.

Path parameters

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

Request body

Name	Type	Required	Description
host	string	Yes	Server IP address or domain
port	integer	Yes	1–65535, sent as a JSON number

Example request

curl -X POST 'https://dl.yengear.com/api/v2/projects/cold-chain-east/devices/42/set-tcp/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"host": "dl-01.yengear.com", "port": 8080}'

Responses

• 200: Command dispatched; data contains message and tcp_info (host:port).
• 400: host is missing or port is out of range.
• 503: The gateway is unavailable or rejected the command.

Set heartbeat parameters

POST /api/v2/projects/{project_id}/devices/{device}/set-heartbeat/

Changes the heartbeat the device sends to keep its connection alive. Omitted fields keep their current values.

Authentication

Bearer token. Minimum role: Manager.

Path parameters

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

Request body

Send at least one field.

Name	Type	Required	Description
mode	string	No	NET (network heartbeat) or NONE (off)
interval	integer	No	Seconds between heartbeats, 1–65535
payload	string	No	Heartbeat content
fmt	string	No	HEX or ASCII

Example request

curl -X POST 'https://dl.yengear.com/api/v2/projects/cold-chain-east/devices/42/set-heartbeat/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"mode": "NET", "interval": 60, "payload": "010203", "fmt": "HEX"}'

Responses

• 200: Command dispatched; data contains message and heartbeat_info with the fields sent.
• 400: No field sent, or an invalid value.
• 503: The gateway is unavailable or rejected the command.

Export point configuration

POST /api/v2/projects/{project_id}/devices/{device}/export-points/

Downloads the device's point configuration as a JSON file named device_<serial_number>_factors.json. The response is the file itself, without the API envelope.

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 -X POST 'https://dl.yengear.com/api/v2/projects/cold-chain-east/devices/42/export-points/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -o points.json

Example response

{
  "v": 2.0,
  "factors": [
    { "name": "Temperature", "slave_id": 1, "address": 0, "the_type": 1, "data_endian": ">", "data_type": "int16", "data_index": 0, "modbus_type": 3, "data_scale": 0.1, "data_delta": 0, "enabled": true }
  ]
}

Responses

• 200: JSON file.
• 400: The device model does not allow viewing points.

Import point configuration

POST /api/v2/projects/{project_id}/devices/{device}/import-points/

Creates points from a JSON file. The API validates every item before writing any of them.

Authentication

Bearer token. Minimum role: Manager.

Path parameters

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

Request body

multipart/form-data:

Name	Type	Required	Description
file	file	Yes	UTF-8 JSON in the form {"v": 2.0, "points": [ ... ]}. Items use the fields shown in Export point configuration.
clear_existing	boolean	No	Delete the device's current points before importing

WARNING

An exported file stores its list under factors, but import reads points. Rename the key before importing an exported file.

Example request

curl -X POST 'https://dl.yengear.com/api/v2/projects/cold-chain-east/devices/42/import-points/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'file=@points.json' \
  -F 'clear_existing=true'

Responses

• 200: data contains detail and imported_count.
• 400: The file is missing, not UTF-8 JSON, has no points array, or an item fails validation (the message names the item number). Also returned when the device model does not allow editing points.

Add a module

POST /api/v2/projects/{project_id}/devices/{device}/add-module/

Creates points from a module template and sets each new point's slave_id to the value sent.

Authentication

Bearer token. Minimum role: Manager.

Path parameters

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

Request body

Name	Type	Required	Description
module_id	integer	Yes	Module template ID
slave_id	integer	Yes	Modbus slave ID for the new points

Responses

• 200: data contains detail and imported_count.
• 400: The module has no point template, or the device model does not allow editing points.
• 404: The module does not exist.

Related

• Device data
• Points
• Device settings in the console