This page outlines a step-by-step process on how to set up Helix in your Verkada Command organization.

Step 1: Generate a Verkada Public API Key

The first step in setting up Event Search is generating a Verkada API Key from Verkada Command. The API key is required to securely authenticate Command users that want to use Verkada APIs, including Verkada Helix. API keys are commonly used to control the utilization of the API’s interface, track how it is being used and by whom. Verkada services use the authentication key to verify that the user requesting to use the API has the right permissions and decide whether to authorize the request.

Note: Make sure that your Verkada API Key has the correct Helix permissions configured for its scope. Additionally, it's important to store your API Keys in a secure location.

To generate an API Key, users will have to be Organization Admins in Command. Generating keys can be done directly through Command by navigating to the Admin page and opening the Verkada API settings. Detailed instructions on generating an API token from Command can be found at the following link: API docs.

Note: When creating the API Key, make sure to set the Helix permissions to “Read/Write” as users will need write permissions to POST events to Command.

Step 2: Define your Helix Event Type

Users with access to the API key can then create an event type along with its associated schema and attributes. For example, when considering Point of Sale implementations, a store manager could have an event type called "Sales Transactions", with attributes such as “price of transaction”, “items purchased”, “transaction type” etc. In addition, when creating an event type, users will need to define each attribute's data type. The supported types are strings, booleans, integers, and floats .

In the example presented below, we are creating an event type which is called "Verkada Helix" which has 2 attributes. The first attribute is "item" which is a "string" data type and the second attribute is "price" which is a "float" data type.

There are two methods available to users for creating a Helix Event Type:

Directly from Verkada Command, under the Alert Inbox page.
Through the Create a Helix Event Type API endpoint.

Option 1 - Creating a Helix Event Type through Command.

Under the Command Alert Inbox page, users are able to create new Helix Event Types by navigating to the Helix Events section.

Clicking on "Set Up Helix Event" will lead the user to a new modal that will allow them to define their own unique Helix schema, relevant to their custom application. In the example below, we are creating a Helix Event Type called "Verkada Helix", which has two attributes: item and price.

Once users have fully defined their Helix Event Type schema, they can click "Save" to confirm their event structure. Command will automatically return the generated Event Type UID (which will be needed when making the API calls to generate Helix Events) as well as the POST request template which outlines how a user would generate Helix Events through a cURL command.

Option 2 - Creating a Helix Event Type through APIs.

Prior to creating a Helix Event Type using the APIs, users will first have to generate an API Token, through the Get API Token endpoint Get API Token. Once users have generated their API Token, they can feely create their event type through the Create a Helix Event Type API endpoint Create a Helix Event Type

The POST request to create an event type can be written in cURL in an MacOS Terminal or Windows PowerShell in the following manner:

curl --request POST \
     --url 'https://api.verkada.com/cameras/v1/video_tagging/event_type' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-verkada-auth: VERKADA_API_TOKEN' \
     --data '
{
     "event_schema": {
          "item": "string",
          "price": "float"
     },
     "name": "Verkada Helix"
}'

Once the POST request has been successfully sent and processed, an Event Type UID will be returned to the user alongside its defined schema. It is important to store the returned Event Type UID as it is a required parameter when creating Helix events tied to this specific Event Type.

{
  "event_schema": {
    "item": "string",
    "price": "float"
  },
  "event_type_uid": "5cd98b8e-daeb-47ee-90ef-e8c99245088d",
  "name": "Verkada Helix",
  "org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

❗️
Key Helix Limitations

Event Types within the same organization must have unique names.

If 2 unique Event Types share the same attribute, the attributes' data type must match.

The maximum number of characters per attribute name is 40.

The maximum number of characters per attribute value is 500.

The maximum number of attributes per Event Type is 25.

The maximum number of custom Event Types per organization is 25.

Step 3: Generating Helix Events

Once the Event Type has been created, users will be able to start posting 3rd party data to Command by using their defined Event Type schema. The attributes used in the API POST request when generating the Helix Events must match those defined in the schema - both in terms of their respective names and data types.

Creating Helix Events is done through a POST request, sent to https://api.verkada.com/cameras/v1/video_tagging/event.

To successfully post an event, users will need to input the following information:

Camera ID: can be found in the URL when streaming a camera in Command (example: https://command.verkada.com/cameras/{camera_id}/).
Time of event (in Unix milliseconds)
Event Type UID
Attributes with corresponding values
API Token

Using a cURL command in your MacOS Terminal or Windows PowerShell, the POST request can be written in the following manner:

curl --request POST \
     --url 'https://api.verkada.com/cameras/v1/video_tagging/event' \
     --header 'content-type: application/json' \
     --header 'x-verkada-auth: VERKADA_API_TOKEN' \
     --data '
{
     "attributes": {
          "item": "Espresso Machine",
          "price": 850.9
     },
     "event_type_uid": "EVENT_TYPE_UID",
     "camera_id": "CAMERA_ID",
     "time_ms": TIME_MS
}
'

Once the request is sent and accepted, the custom event will automatically be reflected in your Command Events’ dashboard under the “Custom Events” section.

The custom events pushed to your Command organization will be accessible to users for the duration of the camera’s retention period or Cloud Backup retention, depending on whichever is greater. For example, if a camera has a retention of 30 days, then the events mapped to that Camera ID will be visible in Command for 30 days.