Field Reference

Overview

This glossary lists recurring identifiers and fields across API v2. Use it when reading endpoint specifications to keep names consistent in your integrations.

Organization & Access

Field	Description	Example
slug	Organization identifier used in URLs and access tokens. Lowercase, unique per tenant.	yanji-lab
org_id	Shorthand for organization slug returned in device data payloads.	yanji-lab
organization_id	Internal numeric primary key referenced in relational models. Usually hidden from API consumers.	42

Projects

Field	Description	Example
project_id	Public identifier for a project. Appears in URLs: /projects/{project_id}/....	greenhouse-alpha
project (object)	Serializer representation of a project with project_id, name, and other metadata.	{ "project_id": "cold-chain-east", "name": "Cold Chain East" }

Devices

Field	Description	Example
device_pk	Internal integer primary key for a device. Used as {device_pk} in nested routes.	128
device_id	Hardware identifier (IMEI, SN). Used when binding devices via safe code.	868686000123456
agri_id (device)	Platform-generated string ID assigned when the device is created. Prefix for factor IDs.	d-1000-abcd
safe_code	Four-character code printed on hardware, required for binding.	8K2P

Factors

Field	Description	Example
unit	Modbus slave ID (integer).	1
address	Register address (integer).	0
data_index	Offset used when reading multiple registers.	0
modbus_type	Register type (holding, input, coil, discrete).	holding
data_type	Encoding for the register value (int16, uint32, float, etc.).	int16
data_endian	Byte order (ABCD, DCBA, BADC, CDAB).	ABCD
data_factor	Multiplier applied to raw data.	0.1
data_delta	Additive offset applied after scaling.	-10
the_type	Logical factor type, matching definitions from /base/device-types/.	temp
the_type_detail	Expanded metadata for the_type (name, unit, icon).	{ "name": "Temperature", "unit": "℃" }
agri_id (factor)	Full factor identifier: <device_agri_id>-<unit>-<address><data_index>.	d-1000-abcd-1-000

Data Payloads

Field	Description	Example
t	UTC timestamp in seconds.	1708070400
value / v	Numeric reading for a factor. Some endpoints use value, others use v.	25.6
project_id	Injected into POST /devices/{device_pk}/data/ responses to show source project.	greenhouse-alpha
org_id	Injected into POST /devices/{device_pk}/data/ responses to show owning organization.	yanji-lab

Access Control

Field	Description	Example
role	Role assigned to AccessConfig (owner, manager, operator, readonly).	manager
all_projects	Boolean flag indicating whether a token/user can access every project.	true
projects	Explicit list of project IDs allowed when all_projects=false.	["greenhouse-alpha"]

Command Tokens

Field	Description	Example
token	Identifier returned by device/factor control endpoints, referencing an AgriCommand.	cmd_01H98Y5EW8HV41ZQMD2D
cmd_type	Command category (e.g., BYTES_ASCII, ON, OFF, FORWARD).	BYTES_ASCII

Refer to this document whenever an endpoint references one of these fields to keep naming consistent across integrations.