Alert and alert-rule endpoints

The API splits alert history (fired notifications) under /api/v1/alerts from alert-rule configuration (the conditions that fire alerts) under /api/v1/alert-rules. Both are scoped by the JWT’s org_id.

`GET /api/v1/alerts`

List fired alerts for the caller’s org.

Since: v1.0 Required role: viewer

Query parameters

Name	Type	Default	Constraints
`rule_id`	uuid	—	Filters to one rule
`status`	enum	—	`new`, `acknowledged`, `resolved`
`date_from`	string	—	RFC3339 or `YYYY-MM-DD`
`date_to`	string	—	RFC3339 or `YYYY-MM-DD`
`cursor`	string	null	Pagination cursor
`limit`	int	20	1-100

Response 200

{
  "data": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "rule_id": "f5e4d3c2-b1a0-4f9e-8d7c-6b5a4e3d2c1b",
      "rule_name": "After-hours dock motion",
      "event_id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "camera_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "new",
      "fired_at": "2026-04-21T02:14:00Z",
      "acknowledged_at": null
    }
  ],
  "next_cursor": null,
  "total": 1
}

Error responses

Code	Body.error	Meaning
401	`auth_required`	Missing or invalid token
429	`rate_limited`	See /developer/rate-limits

Examples

curl -H "Authorization: Bearer sk_live_abc123" \
  "https://novavms.novalien.com/api/v1/alerts?status=new"

const alerts = await novavms.alerts.list({ status: 'new' });

alerts = client.alerts.list(status="new")

`GET /api/v1/alerts/{id}/timeline`

Return a chronological timeline of state changes for a single alert: fired, acknowledged, status transitions.

Since: v1.1 Required role: viewer

Response 200

{
  "alert_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "entries": [
    {"at": "2026-04-21T02:14:00Z", "action": "fired", "actor": null},
    {"at": "2026-04-21T02:18:42Z", "action": "acknowledged", "actor": "Jordan Park"},
    {"at": "2026-04-21T03:05:00Z", "action": "status_changed", "actor": "Jordan Park", "to": "resolved"}
  ]
}

Error responses

Code	Body.error	Meaning
404	`not_found`	Alert not in caller’s org

Examples

curl -H "Authorization: Bearer sk_live_abc123" \
  https://novavms.novalien.com/api/v1/alerts/a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/timeline

const timeline = await novavms.alerts.timeline(
  'a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d',
);

timeline = client.alerts.timeline("a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d")

`GET /api/v1/alert-rules`

List alert rules in the caller’s org.

Since: v1.0 Required role: viewer

Response 200

{
  "data": [
    {
      "id": "f5e4d3c2-b1a0-4f9e-8d7c-6b5a4e3d2c1b",
      "name": "After-hours dock motion",
      "trigger_type": "motion",
      "scope_type": "all_cameras",
      "schedule_type": "custom",
      "cooldown_sec": 300,
      "enabled": true
    }
  ],
  "total": 1
}

Error responses

Code	Body.error	Meaning
401	`auth_required`	Missing or invalid token

Examples

curl -H "Authorization: Bearer sk_live_abc123" \
  https://novavms.novalien.com/api/v1/alert-rules

const rules = await novavms.alertRules.list();

rules = client.alert_rules.list()

`POST /api/v1/alert-rules`

Create an alert rule.

Since: v1.0 Required role: operator

Request body

Name	Type	Default	Constraints
`name`	string	—	1-100 chars
`trigger_type`	enum	—	`motion`, `ai_tag`, `manual`
`custom_tags`	string[]	`[]`	Required when `trigger_type=ai_tag`
`min_confidence`	float	—	0.0-1.0, `ai_tag` only
`scope_type`	enum	`all_cameras`	`all_cameras`, `specific_sites`, `specific_cameras`
`site_ids`	uuid[]	`[]`	Required when `scope_type=specific_sites`
`camera_ids`	uuid[]	`[]`	Required when `scope_type=specific_cameras`
`zones_filter`	string[]	`[]`	Optional zone names
`schedule_type`	enum	`always`	`always`, `custom`
`cooldown_sec`	int	300	0-3600
`conditions_json`	object	`{}`	Extra conditions (serialised JSON)
`recipients`	object[]	`[]`	1-25 recipients, each `{type, target}`

Response 201

{
  "id": "f5e4d3c2-b1a0-4f9e-8d7c-6b5a4e3d2c1b",
  "name": "After-hours dock motion",
  "trigger_type": "motion",
  "scope_type": "specific_cameras",
  "camera_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "schedule_type": "custom",
  "cooldown_sec": 300,
  "enabled": true,
  "created_at": "2026-04-21T14:15:00Z"
}

Error responses

Code	Body.error	Meaning
400	`validation_error`	Missing name, invalid trigger, or empty recipients
403	`forbidden`	Role insufficient
404	`not_found`	Referenced camera or site not in caller’s org

Examples

curl -X POST https://novavms.novalien.com/api/v1/alert-rules \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"name":"After-hours dock motion","trigger_type":"motion","scope_type":"specific_cameras","camera_ids":["550e8400-e29b-41d4-a716-446655440000"],"schedule_type":"custom","cooldown_sec":300,"recipients":[{"type":"email","target":"security@acme-logistics.com"}]}'

const rule = await novavms.alertRules.create({
  name: 'After-hours dock motion',
  triggerType: 'motion',
  scopeType: 'specific_cameras',
  cameraIds: ['550e8400-e29b-41d4-a716-446655440000'],
  scheduleType: 'custom',
  cooldownSec: 300,
  recipients: [{ type: 'email', target: 'security@acme-logistics.com' }],
});

rule = client.alert_rules.create(
    name="After-hours dock motion",
    trigger_type="motion",
    scope_type="specific_cameras",
    camera_ids=["550e8400-e29b-41d4-a716-446655440000"],
    schedule_type="custom",
    cooldown_sec=300,
    recipients=[{"type": "email", "target": "security@acme-logistics.com"}],
)

`PATCH /api/v1/alert-rules/{id}`

Update fields on an existing rule. Partial updates are supported.

Since: v1.0 Required role: operator

Request body

Any subset of fields accepted by POST /api/v1/alert-rules.

Response 200

Returns the updated rule — same shape as POST.

Error responses

Code	Body.error	Meaning
400	`validation_error`	Field value fails schema
404	`not_found`	Rule not in caller’s org

Examples

curl -X PATCH https://novavms.novalien.com/api/v1/alert-rules/f5e4d3c2-b1a0-4f9e-8d7c-6b5a4e3d2c1b \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"cooldown_sec":600}'

await novavms.alertRules.update('f5e4d3c2-b1a0-4f9e-8d7c-6b5a4e3d2c1b', {
  cooldownSec: 600,
});

client.alert_rules.update(
    "f5e4d3c2-b1a0-4f9e-8d7c-6b5a4e3d2c1b",
    cooldown_sec=600,
)

`DELETE /api/v1/alert-rules/{id}`

Delete an alert rule. Historical alerts fired by the rule remain accessible via /api/v1/alerts.

Since: v1.0 Required role: operator

Response 204

Empty body.

Error responses

Code	Body.error	Meaning
403	`forbidden`	Role insufficient
404	`not_found`	Rule not in caller’s org

Examples

curl -X DELETE https://novavms.novalien.com/api/v1/alert-rules/f5e4d3c2-b1a0-4f9e-8d7c-6b5a4e3d2c1b \
  -H "Authorization: Bearer sk_live_abc123"

await novavms.alertRules.delete('f5e4d3c2-b1a0-4f9e-8d7c-6b5a4e3d2c1b');

client.alert_rules.delete("f5e4d3c2-b1a0-4f9e-8d7c-6b5a4e3d2c1b")