In addition to managing events that are generated by your Eagle Eye Cloud Surveillance system, there may be times when you need to report an event that was detected by an external system. For example, you may wish to create an event based on sensor data from smoke detectors or microphones. Or, you may wish to initiate an event when someone employed in your facility activates a panic alarm. By triggering an event, you will create a record in the cloud VMS that can be retrieved via the List Events endpoint.

Event Schema

Eagle Eye Networks events must adhere to a specific schema which is made up of four sections, the Type, Timestamps, Source, and the Data. The event metadata is consistent for all events and always contains the same fields. The data block is specific to the event type and contains a set of event specific data objects.

Type

Events must include a type field that specifies the type of event that was triggered. This field is used to identify the event and determine how it should be processed. The type name itself is a string that includes three sections.

een.motionDetectionEvent.v1

Organization Code
The prefix of the event type is the organization code. This is a unique identifier that is assigned to the organization that created the event. For example, the organization code for Eagle Eye Networks is een.

Type Name
The body of the event type is the type name. This is a string that describes the event that was triggered. For example, motionDetectionEvent.

Version
The suffix of the event type is the version number. This is a string that indicates the version of the event schema that was used to create the event. For example, v1.

For a full list of event types and their corresponding schemas, see the Event Types page.

Timestamps

The timestamp fields must be in ISO 8601 format with millisecond precision. For example, 2025-03-11T20:23:12.766+00:00. Only +/- notation is supported for the timezone offset.
If the event is one that spans a period of time, it may be created with only a start timestamp and the end timestamp can be omitted. You can then update the event with the end timestamp using a second POST request when the event ends. In this case, you will need to include the Event ID in the body of the second request.

Source

This section contains information about the entity that created the event. This is used to identify the source of the event and to determine how it should be processed.

Creator ID

When creating an event, you'll need to include a creatorId in the event data. This ID is used to identify the entity that published the event. To obtain a creator ID, you'll need to contact API Support. We'll review your request to create events and will provide you with a Creator ID if approved.

Actor

The actor fields are used to identify the local device that either reported or observed the event. Generally, this will refer to a camera that is related to the event in some way. For example, an event that is triggered by a smoke detector should indicate the camera that is monitoring the area where the smoke detector is installed as the actor.

In addition to the actor ID, you'll need to include the Actor Account ID. This should be the Eagle Eye Networks Account ID for the account that owns the actor device.

🚧

Shared Devices

If a device or camera is shared from one account to another, it may have a different Account ID than the account for which the API call is authenticated. In this case, the actor account ID will refer to the original owner of the device.

Data

The data section contains metadata that is specific to the event type. This section includes both the data and dataSchemas properties. The dataSchemas field is an array of strings that specify the schemas that define the items in the data array. The data field is an array of objects that contain the event specific data.

    "dataSchemas": [
        "een.objectClassification.v1",
        "een.objectDetection.v1",
        "een.fullFrameImageUrl.v1",
        "een.personAttributes.v1"
    ],
    "data": [
        {
            "creatorId": "een.analytics.v1",
            "httpsUrl": "https://api.c028.eagleeyenetworks.com/api/v3.0/media/recordedImage.jpeg?deviceId=10023191&timestamp__gte=2025-03-11T20:23:12.766%2B00:00&type=preview",
            "timestamp": "2025-03-11T20:23:12.766+00:00",
            "type": "een.fullFrameImageUrl.v1"
        }
    ]

The full list of the data schemas and their associated types can be found on the Data Schemas page.

Publishing Events

To create an event, you'll need to submit the event data to the Eagle Eye Networks REST API by sending a POST command to the /api/v3.0/events endpoint. The body of the POST request should contain the event data in JSON format.

curl --request POST \
     --url https://api.cxxx.eagleeyenetworks.com/api/v3.0/events \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "startTimestamp": "{{startTimestamp}}",  
  "endTimestamp": "{{endTimestamp}}", 
  "span": true,
  "actorAccountId": "",
  "actorId": "",  
  "actorType": "camera",
  "creatorId": "unknown",
  "type": "een.deviceCloudStatusUpdateEvent.v1"
}
'

curl --request POST \
     --url https://api.cxxx.eagleeyenetworks.com/api/v3.0/events \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{  
  "startTimestamp": "{{startTimestamp}}",  
  "endTimestamp": "{{endTimestamp}}", 
  "span": false,  
  "accountId": "",
  "actorId": "",  
  "actorAccountId": "",  
  "actorType": "camera",  
  "creatorId": "",
  "type": "een.objectIntrusionEvent.v1",  
  "dataSchemas": [  
    "een.intrusionArea.v1"  
  ],  
  "data": [  
    {  
      "type": "een.intrusionArea.v1",  
      "id": "area789",  
      "name": "",  
      "area": [  
        [0.0, 0.0],  
        [1.0, 0.0],  
        [1.0, 1.0],  
        [0.0, 1.0]  
      ]  
    }  
  ]  
}