Project Management

Overview

Project APIs scope devices, alerts, and data pipelines under a single organization (see the Field Reference for project_id, device_pk, etc.). Every project exposes a human-readable name plus a stable project_id used in URLs. Device-level routes are namespaced beneath /projects/{project_id}/.

• Base Path: /api/v2/projects/
• Caching: List and detail responses are cached briefly and refreshed automatically whenever a project changes

Endpoint Summary

Method	Path	Purpose	Notes
GET	/api/v2/projects/	List projects in the active organization	Includes device_count/offline_device_count. See List Projects.
GET	/api/v2/projects/{project_id}/	Retrieve project details	Uses project_id as lookup field. See Retrieve Project.
POST	/api/v2/projects/	Create a new project	organization_id injected server-side. See Create Project.
PATCH	/api/v2/projects/{project_id}/	Update project metadata (name, favorite)	Partial updates only; project_id immutable. See Update Project.
DELETE	/api/v2/projects/{project_id}/	Delete a project	Removes associated device bindings. See Delete Project.
POST	/api/v2/projects/{project_id}/transfer/	Move project (and devices) to another organization	Target org identified by slug. See Transfer Project.

List Projects

GET /api/v2/projects/
Authorization: Bearer <token>

Returns paginated project records ordered by favorite, updated_at, pk.

[
  {
    "project_id": "greenhouse-alpha",
    "name": "Greenhouse Alpha",
    "favorite": true,
    "created_at": "2024-01-08T10:00:00Z",
    "device_count": 42,
    "offline_device_count": 3
  }
]

Notes

• device_count counts all devices bound to the project.
• offline_device_count compares each device connect_time with the offline threshold from system configuration.
• Access tokens limited to specific projects will only see entries listed in request.auth["projects"] when all_projects=false.

Retrieve Project

GET /api/v2/projects/{project_id}/
Authorization: Bearer <token>

Returns the same schema as list entries. Results are cached briefly and refreshed whenever the project changes.

Create Project

POST /api/v2/projects/
Authorization: Bearer <token>
Content-Type: application/json

{
  "project_id": "cold-chain-east",
  "name": "Cold Chain East",
  "favorite": false
}

• If project_id is omitted, the backend generates one in the form proj_<random>.
• organization_id is injected automatically from request.organization and cannot be set manually.

Response includes the persisted record with computed fields.

Update Project

PATCH /api/v2/projects/{project_id}/
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Greenhouse Alpha (North)",
  "favorite": true
}

• Only partial updates are allowed (kwargs['partial']=True).
• project_id and organization_id are ignored if present in the payload.

Delete Project

DELETE /api/v2/projects/{project_id}/
Authorization: Bearer <token>

Deletes the project. Ensure that devices bound to the project are unbound or transferred before deletion to avoid orphaned hardware.

Transfer Project

Move a project (with all underlying devices) to another organization.

POST /api/v2/projects/{project_id}/transfer/
Authorization: Bearer <token>
Content-Type: application/json

{
  "target_org_slug": "yanji-demo"
}

Behavior:

1. Validates that the target organization exists and differs from the current one.
2. Updates the project’s organization foreign key.
3. Devices under the project follow automatically because of the FK relationship.

Errors:

Status	Message
404	"目标组织不存在" (Target org not found)
400	"项目已属于目标组织"

Related Endpoints

Projects act as the root for most nested APIs:

• /projects/{project_id}/devices/… — device CRUD, control, telemetry
• /projects/{project_id}/devices/{device_pk}/factors/… — factor management
• /projects/{project_id}/alert/... — alert configuration and notifications
• /projects/{project_id}/data-download-tasks/ — data export jobs

Refer to those documents for endpoint specifics. Projects must exist before you can call any nested route.