Projects

A project groups the devices of one site or use case. Device, point, and export routes sit under /api/v2/projects/{project_id}/.

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

The project object

{
  "project_id": "proj_AbCdEfGhIj",
  "name": "Greenhouse Alpha",
  "favorite": true,
  "open": false,
  "timezone": "Asia/Shanghai",
  "screen_show_time": true,
  "screen_show_project_code": false,
  "scene_image": "https://dl.yengear.com/media/project/project-scene.jpg",
  "created_at": "2026-01-08T10:00:00Z",
  "device_count": 42,
  "offline_device_count": 3
}

Field	Type	Description
project_id	string	Project identifier, read-only after creation
name	string	Display name
favorite	boolean	Pinned projects sort first
open	boolean	When true, signed-in users outside the organization can view the project read-only
timezone	string	IANA time zone for display
screen_show_time	boolean	Show the clock on the dashboard screen
screen_show_project_code	boolean	Show the project code on the dashboard screen
scene_image	string | null	Scene image URL
created_at	string	Creation time
device_count	integer	Devices in the project (read-only)
offline_device_count	integer	Devices that never connected or whose last connection is older than the platform offline threshold (read-only)

List projects

GET /api/v2/projects/

Returns the projects the caller can access: pinned projects first, then the most recently updated. Tokens scoped to specific projects see only those projects.

Authentication

Bearer token. Minimum role: Read-only.

Example request

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

Example response

{
  "success": true,
  "data": [
    {
      "project_id": "proj_AbCdEfGhIj",
      "name": "Greenhouse Alpha",
      "favorite": true,
      "open": false,
      "timezone": "Asia/Shanghai",
      "screen_show_time": true,
      "screen_show_project_code": false,
      "scene_image": null,
      "created_at": "2026-01-08T10:00:00Z",
      "device_count": 42,
      "offline_device_count": 3
    }
  ],
  "error": null
}

Responses

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

Retrieve a project

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

Returns one project.

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/proj_AbCdEfGhIj/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Responses

• 200: The project object.
• 403: The project is outside the token's scope.
• 404: No such project in the organization.

Create a project

POST /api/v2/projects/

Creates a project in the caller's organization.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user). API tokens receive 403.

Request body

Name	Type	Required	Description
name	string	Yes	Display name, up to 64 characters
project_id	string	No	Custom identifier using letters, digits, _, or -. Generated as proj_ plus 10 letters when omitted.
favorite	boolean	No	Pin the project
open	boolean	No	Allow read-only viewing by non-members
timezone	string	No	IANA time zone. Defaults to Asia/Shanghai.
screen_show_time	boolean	No	Dashboard clock
screen_show_project_code	boolean	No	Dashboard project code
scene_image	file	No	Multipart image upload
scene_image_data	string	No	data:image/...;base64, URL; JPG, PNG, or WebP, up to 5 MB. Do not combine with scene_image.

The organization comes from the request context; a body value is ignored.

Example request

curl -X POST 'https://dl.yengear.com/api/v2/projects/' \
  -H 'Authorization: Bearer YOUR_USER_JWT' \
  -H 'X-Organization-Slug: yengear' \
  -H 'Content-Type: application/json' \
  -d '{"project_id": "cold-chain-east", "name": "Cold Chain East", "timezone": "Asia/Shanghai"}'

Responses

• 201: The created project object.
• 400: Validation error, such as an invalid scene image.
• 403: The caller is not an Owner, the request used an API token, or the plan quota is reached (membership_quota_exceeded).

Update a project

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

Updates project 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

Request body

Any writable field from Create a project except project_id. The API ignores project_id and organization_id in the body.

Example request

curl -X PATCH 'https://dl.yengear.com/api/v2/projects/proj_AbCdEfGhIj/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Greenhouse Alpha (North)", "favorite": true}'

Responses

• 200: The updated project object.
• 400: Validation error.
• 403: Role below Manager, or the plan is read-only.
• 404: No such project.

Delete a project

DELETE /api/v2/projects/{project_id}/

Deletes a project. Its devices stay in the organization as unassigned devices. Alerts and notification settings of the project are deleted. Existing export tasks keep the project ID and name.

Authentication

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

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Project identifier

Responses

• 204: Project deleted.
• 403: The caller is not an Owner, or the request used an API token.
• 404: No such project.

Transfer a project

POST /api/v2/projects/{project_id}/transfer/

Moves a project and its devices to another organization. The target plan must be active and have room for one more project plus the moved devices and points. Both organizations' audit logs record the transfer.

Authentication

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

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Project identifier

Request body

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

Example request

curl -X POST 'https://dl.yengear.com/api/v2/projects/proj_AbCdEfGhIj/transfer/' \
  -H 'Authorization: Bearer YOUR_USER_JWT' \
  -H 'X-Organization-Slug: yengear' \
  -H 'Content-Type: application/json' \
  -d '{"target_org_slug": "partner-farm"}'

Responses

• 200: Transfer complete; data is null.
• 400: The project already belongs to the target organization.
• 403: The caller is not an Owner, or the target plan is read-only or over quota.
• 404: The target organization does not exist.

Related

• Devices
• Projects in the console