API: Working with events

Cameras can support different types of events, the full list of supported events for a certain camera can be obtained with GET/cameras/{CAMID}/event_processing/events/ request. In the examples below, ACCESS_TOKEN should be replaced with an actual access token of the selected channel with "all" permission.

For example:

CODE

curl -X GET "https://web.vxgdemo.vxgdemo.cloud-vms.com:443/api/v2/cameras/237863/event_processing/events/" 
     -H "accept: application/json" 
     -H "Authorization: Acc ACCESS_TOKEN"

The response contains the list of all supported events along with the capabilities:

CODE

{
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 3
  },
  "objects": [
    {
      "caps": {
        "can_be_triggered": false,
        "can_record": true,
        "can_snapshot": true,
        "is_periodic": false
      },
      "generate_images": false,
      "name": "motion",
      "notify": true,
      "receive": true,
      "record": true,
      "snapshot": true
    },
    {
      "caps": {
        "can_be_triggered": false,
        "can_record": false,
        "can_snapshot": false,
        "is_periodic": false
      },
      "generate_images": false,
      "name": "net",
      "notify": true,
      "receive": true
    },
    {
      "caps": {
        "can_be_triggered": false,
        "can_record": false,
        "can_snapshot": true,
        "is_periodic": true
      },
      "generate_images": false,
      "name": "snapshot",
      "notify": true,
      "period": 0,
      "receive": false,
      "snapshot": true
    }
  ]
}

Adding new types of events

It is possible to add new custom types of events using POST/cameras/{CAMID}/event_processing/events/ request.

For example:

CODE

curl -X POST "https://web.vxgdemo.vxgdemo.cloud-vms.com:443/api/v2/cameras/237863/event_processing/events/" 
     -H "accept: application/json" 
     -H "Content-Type: application/json" 
     -H "Authorization: Acc ACCESS_TOKEN" -d "{ \"name\": \"custom_event\", \"notify\": true}"

The response contains capabilities of the new event type:

CODE

{
  "caps": {
    "can_be_triggered": false,
    "can_record": false,
    "can_snapshot": false,
    "is_periodic": false
  },
  "custom": true,
  "name": "custom_event",
  "notify": true,
  "receive": false
}

Creating events

In most cases, cameras are generating events themselves, but sometimes it is needed to create an event on the backend. For example, custom events can only be created by the backend.

To create an event, you need to specify the camera, type of event (it must be supported), and the event time. Also, it is possible to add metadata if needed. For example:

CODE

curl -X POST "https://web.vxgdemo.vxgdemo.cloud-vms.com:443/api/v2/storage/events/" 
     -H "accept: application/json" 
     -H "Content-Type: application/json" 
     -H "Authorization: Acc ACCESS_TOKEN" -d "{ \"camid\": 237863, \"name\": \"custom_event\", \"time\": \"2021-09-23T16:30:00\", \"meta\": { \"tag1\": \"value1\" }}"

Response:

CODE

{
  "camid": 237863,
  "id": 33794128,
  "meta": {
    "tag1": "value1"
  },
  "name": "custom_event",
  "time": "2021-09-23T16:30:00"
}

Triggering events

Some types of events can be triggered ("can_be_triggered": true in capabilities) which means that the backend sending the command to the camera and the camera generates the event itself.

To trigger an event, you need to specify the camera, type of event, and the event time. Also, it is possible to add metadata if needed. For example:

CODE

curl -X POST "https://web.vxgdemo.vxgdemo.cloud-vms.com:443/api/v2/cameras/240977/event_processing/events/audio_event/trigger/" 
     -H "accept: application/json" -H "Content-Type: application/json" 
     -H "Authorization: Acc ACCESS_TOKEN" -d "{ \"time\": \"2021-09-23T19:15:00\", \"meta\": { \"tag1\": \"value1\" }}"