Project Alerts

Overview

Alert APIs allow each project to configure notification channels (SMS, Email), tune global thresholds, and query/cancel triggered alerts. Reference common identifiers (e.g., project_id, device_pk) via the Field Reference.

• Base Prefix: /api/v2/projects/{project_id}/alert/

Endpoint Summary

Method	Path	Purpose	Notes
GET	/projects/{project_id}/alert/config/	Read project-level alert switches (single instance)	See Project Alert Config.
PATCH	/projects/{project_id}/alert/config/	Update alert switches or throttling settings	See Project Alert Config.
GET/POST/PUT/PATCH/DELETE	/projects/{project_id}/alert/sms-notifications/	Manage SMS notification receivers	See SMS Notifications.
GET/POST/PUT/PATCH/DELETE	/projects/{project_id}/alert/email-notifications/	Manage email notification receivers	See Email Notifications.
GET/POST/PUT/PATCH/DELETE	/projects/{project_id}/alert/items/	Manage alert items list	See Alert Items.
POST	/projects/{project_id}/alert/items/{alert_pk}/cancel/	Cancel an active alert item	See Cancel Alert.
GET	/projects/{project_id}/alert/items/current/	List all active alerts	See Current Active Alerts.
POST	/projects/{project_id}/alert/items/trigger-test/	Trigger synthetic alert for validation	See Trigger Test Alert.

Project Alert Config (Singleton)

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

If the project does not yet have AlertProjectConfig, the backend creates one on the fly.

Update Config

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

{
  "enabled": true,
  "cooldown_minutes": 10
}

Fields mirror the alert configuration schema (e.g., enabling/disabling threshold alerts, cooldown intervals, notification toggles). The backend enforces project ownership automatically.

SMS Notifications

CRUD operations for SMS recipients.

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

{
  "phone_number": "+8613800000000",
  "name": "Operations Team"
}

The API automatically binds new entries to the project referenced in the URL. Listing endpoints return all SMS contacts for the project.

Email Notifications

Structure mirrors SMS notifications but stores email addresses.

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

{
  "email": "alerts@yanjiiot.com",
  "name": "Primary Alert Inbox"
}

Alert Items

GET /api/v2/projects/{project_id}/alert/items/?status=active&the_type=threshold
Authorization: Bearer <token>

• Pagination: page / page_size (default 20, max 100) as defined by AlertItemPagination.
• Filters:
  • status: filter by alert status (active, cancelled, resolved, etc.).
  • the_type: filter by alert category (e.g., threshold).

Each alert item includes associated device, project, level, trigger data, and status fields.

Cancel Alert

POST /api/v2/projects/{project_id}/alert/items/{alert_pk}/cancel/
Authorization: Bearer <token>

• Only alerts with STATUS_ACTIVE can be cancelled; other statuses return HTTP 400.
• Response contains the updated alert item.

Current Active Alerts

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

Returns all active alerts without pagination (useful for dashboards).

Trigger Test Alert

POST /api/v2/projects/{project_id}/alert/items/trigger-test/
Authorization: Bearer <token>

Creates a synthetic alert for integration testing:

1. Finds the first device inside the project.
2. Locates an AlertLevel (prefers threshold type).
3. Deletes any previous test alerts (trigger_data.test = true).
4. Creates a new alert item with trigger_data flagged as test data.

Requires at least one device and alert level; otherwise returns HTTP 404.

Error Codes

Status	Code	Description
400	INVALID_ALERT_STATE	Attempted to cancel a non-active alert
401	UNAUTHORIZED	Missing or invalid credentials
403	FORBIDDEN	Caller lacks manager role
404	PROJECT_NOT_FOUND | DEVICE_NOT_FOUND	Project not in organization, or preconditions missing

Operational Notes

1. Auto-creation: Project config objects are lazily created, making GET idempotent even before any manual setup.
2. Testing: Use trigger-test before going live with third-party notifications to ensure SMS/email servers are reachable.
3. Localization: Alert descriptions originate from upstream rule engines and may contain Chinese text; normalize on the client if needed.