API Documentation
HomeHelp CenterCommand

Setting Up Verkada Helix

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

Step 1: Create a Verkada Public API Key Token

The first step in setting up Event Search is generating a Verkada API key token 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 token to verify that the user requesting to use the API has the right permissions and decide whether to authorize the request.

Note: Make sure to store Verkada API tokens in a secure location as they can be used as an authentication method for Verkada APIs for any user that has access to it.

To generate an API token, users will have to be Organization Administrator. This 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 Token, make sure to set the permissions to “Read/Write” as users will need write permissions to to POST events to Command. Additionally, be sure to check the "Expiration" field as once the API Token has expired, any integration that has been setup with this specific token will stop working.

Step 2: Create an 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. When creating the event type, ensure that both the Organization ID and Verkada API Token are correct.

The method of creation for events type is through a POST request, sent to the following Verkada end point https://api.verkada.com/cameras/v1/video_tagging/event_type?org_id={ORGANIZATION_ID}.

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?org_id=ORGANIZATION_ID' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: VERKADA_API_KEY' \
     --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. This Event Type UID is needs to be retained in order to create custom events that follow this specific schema.

Notes:

  • 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 field is 20.
  • The maximum number of attributes per event type is 10.
  • The maximum number of custom event types per organization is 10.

Step 3: Create Events

Once the event type has been created, users will be able to start posting 3rd party data to Command by following the event type's schema. Attributes must match the schema relating to the attribute name and also its corresponding data type.

The method of creation for these custom events is 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:

  • Organization ID: can be found in Verkada Command within the Admin -> Org Settings -> Verkada API
  • 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 Key

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?org_id=ORGANIZATION_ID' \
     --header 'content-type: application/json' \
     --header 'x-api-key: VERKADA_API_KEY' \
     --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.