Helix

Helix API client and functional wrappers for pykada.

The HelixClient provides access to Helix video event tags — creating, reading, updating, deleting, and searching custom event types and individual events through Verkada’s Helix API.

Client

class pykada.helix.HelixClient(api_key=None, token_manager=None)

Bases: BaseClient

Client for interacting with Verkada’s Helix API. This client provides methods to manage and search video event tags.

Initialize the client with either an API key or a token manager. If not key is provided, a default token manager will be used based on the environment configuration (VERKADA_API_KEY in a .env file).

Parameters:

• api_key (Optional[str]) – Optional API key for authentication.

• token_manager (Optional[VerkadaTokenManager]) – Optional token manager for handling tokens.

create_helix_event_type(event_schema, name)

Create a new Helix Event Type.

Parameters:

• event_schema (Dict[str, str]) – A dictionary defining the event schema (e.g., {“item”: “string”, “price”: “float”}). Maximum number of attributes is 10; each attribute name and type must be non-empty and within length limits.

• name (str) – The unique name for the Helix event type.

Return type:

Dict[str, Any]

Returns:

JSON response containing the created event type info (including its UID).

Raises:

ValueError – If name is empty or event_schema is not valid.

get_helix_event_types(event_type_uid=None, name=None)

Retrieve a list of Helix Event Types from the organization.

This method returns all Helix Event Types along with their associated names and schemas. You can optionally narrow down the results by specifying either an event type UID or an event type name.

Parameters:

• event_type_uid (Optional[str]) – (Optional) The unique identifier of the event type to filter by.

• name (Optional[str]) – (Optional) The name of the event type to filter by.

Return type:

Dict[str, Any]

Returns:

JSON response containing Helix Event Types.

Raises:

ValueError – If event_type_uid or name is provided as an empty string.

update_helix_event_type(event_type_uid, event_schema, name)

Update an existing Helix Event Type.

Parameters:

• event_type_uid (str) – The unique identifier of the Helix Event Type.

• event_schema (Dict[str, str]) – A dictionary representing the updated event schema.

• name (str) – The updated name for the event type.

Return type:

Dict[str, Any]

Returns:

JSON response containing the updated event type information.

Raises:

ValueError – If any required parameter is missing or invalid.

delete_helix_event_type(event_type_uid)

Delete a Helix Event Type from Command.

Parameters:

event_type_uid (str) – The unique identifier of the Helix Event Type to delete.

Return type:

Dict[str, Any]

Returns:

JSON response confirming deletion of the event type.

Raises:

ValueError – If event_type_uid is empty.

create_helix_event(camera_id, event_type_uid, time_ms, flagged=False, attributes=None)

Create a Helix Event in Command.

This method generates a Helix Event by sending a POST request to the Verkada API. Required attributes for the event include:

• camera_id: The unique identifier of the camera.

• event_type_uid: The unique identifier of the Helix Event Type.

• time_ms: The event epoch time in milliseconds.

The flagged attribute is optional and defaults to False. In addition, users can supply any extra attributes (that adhere to the pre-defined event schema) via the extra_attributes parameter. Attributes not provided are simply omitted from the request.

Parameters:

• camera_id (str) – The unique identifier of the camera.

• event_type_uid (str) – The unique identifier of the Helix Event Type.

• time_ms (int) – The event epoch time in milliseconds.

• flagged (Optional[bool]) – Boolean indicating whether the event is flagged (defaults to False).

• attributes (Optional[Dict[str, Any]]) – Optional dictionary of additional attribute values.

Return type:

Dict[str, Any]

Returns:

JSON response containing the created Helix Event details.

Raises:

ValueError – If camera_id or event_type_uid is an empty string, or if time_ms is not a positive integer.

get_helix_event(camera_id, time_ms, event_type_uid)

Retrieve a Helix Event.

Parameters:

• camera_id (str) – The unique identifier of the camera.

• time_ms (int) – The event time as a Unix timestamp in milliseconds.

• event_type_uid (str) – The UID of the Helix Event Type.

Return type:

Dict[str, Any]

Returns:

JSON response containing the event details.

Raises:

ValueError – If any required parameter is missing or invalid.

update_helix_event(camera_id, time_ms, event_type_uid, flagged, extra_attributes=None)

Update an existing Helix Event in Command.

This method updates an already-posted Helix Event. To perform the update, you must supply the following query parameters:

• camera_id: The unique identifier of the camera.

• time_ms: The event epoch time in milliseconds.

• event_type_uid: The unique identifier of the event type.

In the request body, an "attributes" object is provided, which must include the required flagged boolean parameter. Additional attribute updates can be supplied via the extra_attributes parameter.

Parameters:

• camera_id (str) – The unique identifier of the camera.

• time_ms (int) – The event epoch time in milliseconds (must be a positive integer).

• event_type_uid (str) – The unique identifier of the Helix Event Type.

• flagged (bool) – Boolean indicating whether the event is flagged.

• extra_attributes (Optional[Dict[str, Any]]) – Optional dictionary of additional attribute key-value pairs to update.

Return type:

Dict[str, Any]

Returns:

JSON response containing the updated Helix Event details.

Raises:

ValueError – If camera_id or event_type_uid is an empty string, or if time_ms is not positive.

delete_helix_event(camera_id, time_ms, event_type_uid)

Delete a Helix Event from Command.

Parameters:

• camera_id (str) – The unique identifier of the camera.

• time_ms (int) – The event time as a Unix timestamp in milliseconds.

• event_type_uid (str) – The UID of the Helix Event Type.

Return type:

Dict[str, Any]

Returns:

JSON response confirming deletion of the event.

Raises:

ValueError – If any required parameter is missing or invalid.

search_helix_events(camera_ids, end_time_ms, event_type_uid, flagged, keywords, start_time_ms, attribute_filters=None)

Search for Helix Events in Command.

This function sends a POST request to search for one or more Helix Events

that have already been posted

to Command. It requires that the API token (provided via headers)

has Helix permissions.

The search is refined by specifying:

• camera_ids: A list of unique camera IDs.

• end_time_ms: The query end epoch time in milliseconds.

• event_type_uid: The unique identifier of the event type.

• flagged: A boolean indicating whether to filter for flagged events.

• keywords: A list of search keywords.

• start_time_ms: The query start epoch time in milliseconds.

Parameters:

• attribute_filters (Optional[List[Dict[str, Any]]]) – Optional list of additional filter objects.

• camera_ids (List[str]) – List of unique camera IDs (must be non-empty).

• end_time_ms (int) – Query end epoch time in milliseconds (must be positive).

• event_type_uid (str) – Unique identifier of the event type (non-empty string).

• flagged (bool) – Boolean indicating whether to filter for flagged events.

• keywords (List[str]) – List of search keywords (each must be non-empty).

• start_time_ms (int) – Query start epoch time in milliseconds (must be positive and <= end_time_ms).

Return type:

Dict[str, Any]

Returns:

JSON response containing the search results.

Raises:

ValueError – If any required parameter is missing or invalid.

property request_manager: VerkadaRequestManager

Returns the request manager used by this client.

Functional wrappers

Helix API client and functional wrappers for pykada.

The HelixClient provides access to Helix video event tags — creating, reading, updating, deleting, and searching custom event types and individual events through Verkada’s Helix API.

pykada.helix.create_helix_event(camera_id, event_type_uid, time_ms, flagged=False, attributes=None)

Create a Helix Event in Command.

This method generates a Helix Event by sending a POST request to the Verkada API. Required attributes for the event include:

• camera_id: The unique identifier of the camera.

• event_type_uid: The unique identifier of the Helix Event Type.

• time_ms: The event epoch time in milliseconds.

The flagged attribute is optional and defaults to False. In addition, users can supply any extra attributes (that adhere to the pre-defined event schema) via the extra_attributes parameter. Attributes not provided are simply omitted from the request.

Parameters:

• camera_id (str) – The unique identifier of the camera.

• event_type_uid (str) – The unique identifier of the Helix Event Type.

• time_ms (int) – The event epoch time in milliseconds.

• flagged (Optional[bool]) – Boolean indicating whether the event is flagged (defaults to False).

• attributes (Optional[Dict[str, Any]]) – Optional dictionary of additional attribute values.

Returns:

JSON response containing the created Helix Event details.

Raises:

ValueError – If camera_id or event_type_uid is an empty string, or if time_ms is not a positive integer.

—

Note: This is a functional wrapper for its equivalent method in the HelixClient. It creates a new client instance on every call, making it best for single, convenient operations. For making multiple API calls, instantiate and use a HelixClient object directly for better performance.

pykada.helix.create_helix_event_type(event_schema, name)

Create a new Helix Event Type.

Parameters:

• event_schema (Dict[str, str]) – A dictionary defining the event schema (e.g., {“item”: “string”, “price”: “float”}). Maximum number of attributes is 10; each attribute name and type must be non-empty and within length limits.

• name (str) – The unique name for the Helix event type.

Returns:

JSON response containing the created event type info (including its UID).

Raises:

ValueError – If name is empty or event_schema is not valid.

—

Note: This is a functional wrapper for its equivalent method in the HelixClient. It creates a new client instance on every call, making it best for single, convenient operations. For making multiple API calls, instantiate and use a HelixClient object directly for better performance.

pykada.helix.delete_helix_event(camera_id, time_ms, event_type_uid)

Delete a Helix Event from Command.

Parameters:

• camera_id (str) – The unique identifier of the camera.

• time_ms (int) – The event time as a Unix timestamp in milliseconds.

• event_type_uid (str) – The UID of the Helix Event Type.

Returns:

JSON response confirming deletion of the event.

Raises:

ValueError – If any required parameter is missing or invalid.

—

Note: This is a functional wrapper for its equivalent method in the HelixClient. It creates a new client instance on every call, making it best for single, convenient operations. For making multiple API calls, instantiate and use a HelixClient object directly for better performance.

pykada.helix.delete_helix_event_type(event_type_uid)

Delete a Helix Event Type from Command.

Parameters:

event_type_uid (str) – The unique identifier of the Helix Event Type to delete.

Returns:

JSON response confirming deletion of the event type.

Raises:

ValueError – If event_type_uid is empty.

—

Note: This is a functional wrapper for its equivalent method in the HelixClient. It creates a new client instance on every call, making it best for single, convenient operations. For making multiple API calls, instantiate and use a HelixClient object directly for better performance.

pykada.helix.get_helix_event(camera_id, time_ms, event_type_uid)

Retrieve a Helix Event.

Parameters:

• camera_id (str) – The unique identifier of the camera.

• time_ms (int) – The event time as a Unix timestamp in milliseconds.

• event_type_uid (str) – The UID of the Helix Event Type.

Returns:

JSON response containing the event details.

Raises:

ValueError – If any required parameter is missing or invalid.

—

Note: This is a functional wrapper for its equivalent method in the HelixClient. It creates a new client instance on every call, making it best for single, convenient operations. For making multiple API calls, instantiate and use a HelixClient object directly for better performance.

pykada.helix.get_helix_event_types(event_type_uid=None, name=None)

Retrieve a list of Helix Event Types from the organization.

This method returns all Helix Event Types along with their associated names and schemas. You can optionally narrow down the results by specifying either an event type UID or an event type name.

Parameters:

• event_type_uid (Optional[str]) – (Optional) The unique identifier of the event type to filter by.

• name (Optional[str]) – (Optional) The name of the event type to filter by.

Returns:

JSON response containing Helix Event Types.

Raises:

ValueError – If event_type_uid or name is provided as an empty string.

—

Note: This is a functional wrapper for its equivalent method in the HelixClient. It creates a new client instance on every call, making it best for single, convenient operations. For making multiple API calls, instantiate and use a HelixClient object directly for better performance.

pykada.helix.search_helix_events(camera_ids, end_time_ms, event_type_uid, flagged, keywords, start_time_ms, attribute_filters=None)

Search for Helix Events in Command.

This function sends a POST request to search for one or more Helix Events

that have already been posted

to Command. It requires that the API token (provided via headers)

has Helix permissions.

The search is refined by specifying:

• camera_ids: A list of unique camera IDs.

• end_time_ms: The query end epoch time in milliseconds.

• event_type_uid: The unique identifier of the event type.

• flagged: A boolean indicating whether to filter for flagged events.

• keywords: A list of search keywords.

• start_time_ms: The query start epoch time in milliseconds.

Parameters:

• attribute_filters (Optional[List[Dict[str, Any]]]) – Optional list of additional filter objects.

• camera_ids (List[str]) – List of unique camera IDs (must be non-empty).

• end_time_ms (int) – Query end epoch time in milliseconds (must be positive).

• event_type_uid (str) – Unique identifier of the event type (non-empty string).

• flagged (bool) – Boolean indicating whether to filter for flagged events.

• keywords (List[str]) – List of search keywords (each must be non-empty).

• start_time_ms (int) – Query start epoch time in milliseconds (must be positive and <= end_time_ms).

Returns:

JSON response containing the search results.

Raises:

ValueError – If any required parameter is missing or invalid.

—

Note: This is a functional wrapper for its equivalent method in the HelixClient. It creates a new client instance on every call, making it best for single, convenient operations. For making multiple API calls, instantiate and use a HelixClient object directly for better performance.

pykada.helix.update_helix_event(camera_id, time_ms, event_type_uid, flagged, extra_attributes=None)

Update an existing Helix Event in Command.

This method updates an already-posted Helix Event. To perform the update, you must supply the following query parameters:

• camera_id: The unique identifier of the camera.

• time_ms: The event epoch time in milliseconds.

• event_type_uid: The unique identifier of the event type.

In the request body, an "attributes" object is provided, which must include the required flagged boolean parameter. Additional attribute updates can be supplied via the extra_attributes parameter.

Parameters:

• camera_id (str) – The unique identifier of the camera.

• time_ms (int) – The event epoch time in milliseconds (must be a positive integer).

• event_type_uid (str) – The unique identifier of the Helix Event Type.

• flagged (bool) – Boolean indicating whether the event is flagged.

• extra_attributes (Optional[Dict[str, Any]]) – Optional dictionary of additional attribute key-value pairs to update.

Returns:

JSON response containing the updated Helix Event details.

Raises:

ValueError – If camera_id or event_type_uid is an empty string, or if time_ms is not positive.

—

Note: This is a functional wrapper for its equivalent method in the HelixClient. It creates a new client instance on every call, making it best for single, convenient operations. For making multiple API calls, instantiate and use a HelixClient object directly for better performance.

pykada.helix.update_helix_event_type(event_type_uid, event_schema, name)

Update an existing Helix Event Type.

Parameters:

• event_type_uid (str) – The unique identifier of the Helix Event Type.

• event_schema (Dict[str, str]) – A dictionary representing the updated event schema.

• name (str) – The updated name for the event type.

Returns:

JSON response containing the updated event type information.

Raises:

ValueError – If any required parameter is missing or invalid.

—

Note: This is a functional wrapper for its equivalent method in the HelixClient. It creates a new client instance on every call, making it best for single, convenient operations. For making multiple API calls, instantiate and use a HelixClient object directly for better performance.