VEverdun
events

Create Event

post/events/{stream_id}

Request

  • Base URL
    https://api.verdun.ai (the document declares no server; this is the origin it was published from)
  • URL
    https://api.verdun.ai/events/{stream_id}
  • Auth
    API key in header X-API-Key

Path parameters

stream_idstring required

Request body

zonestring required

Zone code

clip_s3_urlstring required

S3 URL

summarystring nullable

Mapped summary column

motion_scorestring nullable

Mapped motion score column

sourcestring nullable

Mapped source column

detection_modestring nullable

The ingestor runner's detection_mode snapshot for this clip; when present it overrides the live camera row for the response's routing fields. Normalized to lowercase; values outside {legacy, ii_gated} degrade to None (camera-row fallback) rather than rejecting the alarm write

occurred_atstring date-time nullable

When the motion actually started (clip trigger time). The schedule gate is evaluated at this instant so clip-upload latency at an hour boundary can't misclassify the event. Absent = evaluated at receipt time.

camera_idstring nullable

The ingestor runner's own api camera id for this stream, captured once at the processor's construction. When present, create_event 409s if it disagrees with the camera actually resolved by kvs_stream_name. Malformed values degrade to None (the check is skipped) rather than rejecting the alarm write.

Example request

{
  "zone": "A",
  "clip_s3_url": "https://s3.amazonaws.com",
  "summary": "Emergency!",
  "motion_score": "0.9",
  "source": "rtsp_motion",
  "detection_mode": "legacy",
  "occurred_at": "2026-07-09T05:59:30+00:00",
  "camera_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Response

Successful Response

idstring uuid required

UUID of event

kvs_stream_namestring required

KVS stream name

zonestring required

Zone code

clip_s3_urlstring required

S3 URL

summarystring nullable

Mapped summary column

motion_scorenumber nullable

Mapped motion score column

sourcestring nullable

Mapped source column

parent_idstring uuid required

Tenant ID

camera_idstring uuid required

Camera ID

site_idstring uuid required

Site ID

rag_contextstring nullable

Camera scene context for the LLM prompt

site_timezonestring nullable

IANA timezone of the site

event_local_timestring nullable

Event time in the site's local timezone (ISO 8601)

monitoring_statestring nullable

Schedule mode at the event time: 'monitored' or 'heightened' ('off' events are suppressed)

heightened_exceptionsstring nullable

JSON-encoded exception list; null outside heightened windows

ignore_zonesstring nullable

JSON-encoded ignore=true masking polygons (points only, percent 0-100 of the frame) for the AI pipeline to redact before analysis; null when the camera has none

monitoring_profilestring nullable

The camera's monitoring profile: 'security' (intrusion/theft/robbery) or 'safety' (slips/falls/person-down)

detection_modestring nullable

Camera's DeepAlert routing state: 'legacy' | 'ii_gated'; null means legacy

deepalert_sensor_idstring nullable

Provisioned DeepAlert sensor id; populated only when detection_mode == 'ii_gated'

deepalert_confidence_thresholdnumber nullable

The DeepAlert confidence floor (0-100, lower = more sensitive) in force for this event: the camera's valid override, else the fleet default. On the ii_gated path it is always a number (null only for a corrupt persisted tuple, which ii stamps ii_fail_safe); null off the ii_gated path. Persisted per event and returned unchanged on a dedupe retry

deepalert_confidence_threshold_sourcestring nullable

Where that value came from: 'camera' (a valid per-camera override) | 'fleet_default' | 'invalid_override' (the stored override was unusable; the fleet default applied). Null off the ii_gated path. Old ingestors drop this key; ii then stamps the provenance 'unknown'

deepalert_confidence_threshold_revisioninteger nullable

The fleet-default revision the value was resolved under (the epoch key; see PUT /settings/deepalert-default-confidence-threshold). Null off the ii_gated path

deepalert_classesstring nullable

Owner-configured DeepAlert classes as a canonical comma-joined string ('people' | 'vehicles' | 'people,vehicles'); null means both. Populated only when detection_mode == 'ii_gated'

fire_watchboolean nullable

Whether the fire-screen fallback should run for this camera's gate-negative clips

display_rotationinteger

The camera's display rotation (degrees CCW, 0 or 180) that ignore_zones is expressed against. The ingestor compares it with the rotation it stamped on the clip and transforms ignore_zones into the clip's space on a mismatch. 0 = no rotation or an api that predates the field.

deduplicatedboolean

True when this response describes an existing event (a retry of an already-successful create), not a new insert

Example response

{
  "id": "UUID Of some sort",
  "kvs_stream_name": "dev-home-cam01",
  "zone": "A",
  "clip_s3_url": "https://s3.amazonaws.com",
  "summary": "Emergency!",
  "source": "rtsp_motion",
  "parent_id": "UUID of some sort",
  "camera_id": "UUID of some sort",
  "site_id": "UUID of some sort",
  "rag_context": "Cleaning crew expected 19:00-21:00 nightly",
  "site_timezone": "America/Los_Angeles",
  "event_local_time": "2026-07-09T19:42:00-07:00",
  "monitoring_state": "heightened",
  "heightened_exceptions": "[{\"label\": \"Uniformed security\", \"description\": \"Navy uniforms with badge\"}]",
  "ignore_zones": "[{\"points\": [{\"x\": 10, \"y\": 20}, {\"x\": 80, \"y\": 20}, {\"x\": 80, \"y\": 90}]}]",
  "monitoring_profile": "security",
  "detection_mode": "ii_gated",
  "deepalert_sensor_id": "sensor-abc123",
  "deepalert_confidence_threshold": 25,
  "deepalert_confidence_threshold_source": "fleet_default",
  "deepalert_classes": "people",
  "fire_watch": true,
  "display_rotation": 180
}

Changes

No recorded changes to this operation across all 2 revisions of this API.