Skip to main content

Workflows and event types

A workflow is a rule: a condition plus the steps to run when it matches. See Rules and workflows for conditions, steps and placeholders.

Reading endpoints work for operators and admins. Endpoints that change workflows or event types need the admin role. Workflow changes take effect within about 30 seconds.

Operators see secrets in workflows masked as ********: webhook and API call headers, tokens in URLs and similar values. Admins get the real values. When an admin saves a workflow back with a masked value unchanged, Argus keeps the stored secret. Sending ******** in a new workflow or a changed field returns 422.

The workflow object​

idintegeroptional
The workflow ID.
namestringoptional
The name. It appears on each alert the workflow raises.
conditionobjectoptional
Which detections match: camera, classes, zone (the name of one of the camera's zones), schedule ({"start": "22:00", "end": "06:00"}, in the site's time zone) and min_dwell_seconds. See Conditions.
stepsarrayoptional
The steps to run, in order. Each step is {"action_type": "...", "params": {...}}. See Step parameters.
actionobjectoptional
A legacy field. Send {}.
enabledbooleanoptional
Whether the workflow runs.
event_type_idinteger or nulloptional
An event type. When set, the workflow only fires for events of that type, as set by the camera's detection profile. Events from a profile without an event type are not filtered.
event_type_keystring or nulloptional
The key of that event type.

Step parameters​

action_typeparams
create_alertseverity (info, medium or high) and message, both optional. Recorded in the run log.
send_webhookurl (required) and payload_template, a JSON object. Sent as POST.
api_callurl (required), method (GET by default, or POST, PUT, PATCH, DELETE), headers and payload_template, both JSON objects.
tag_eventtag. Defaults to flagged.
send_emailchannel_id (required, an email notification channel), to (required, one address or a list), subject and body.
send_smschannel_id (required, an SMS notification channel), to (required, one number or a list) and message.

Webhook, API call, email and SMS text can use the placeholders {{event_id}}, {{camera_name}}, {{caption}}, {{severity}} and {{ts}}. Webhook and API call URLs may not point at the site node itself (loopback), link-local or cloud metadata addresses.

List workflows​

GET/workflows

Lists every workflow, enabled or not.

Responses​

200
An array of workflows.
401
You are not signed in.

Create a workflow​

POST/workflows

Creates an enabled workflow. Requires the admin role.

Body​

namestringrequired
The name.
conditionobjectrequired
Which detections match. Send {} to match every detection that passes the camera's profile.
stepsarrayrequired
The steps to run, in order.
actionobjectrequired
A legacy field. Send {}.
event_type_idinteger or nulloptional
Only fire for events of this type.

Response fields​

idintegeroptional
The new workflow's ID.
namestringoptional
The name.
enabledbooleanoptional
true.

Responses​

200
The workflow was created.
403
You are not an admin.
422
A required field is missing, or a field contains a masked ******** value.

Change a workflow​

PATCH/workflows/{workflow_id}

Changes one or more fields. Send only the fields you want to change. condition and steps are replaced as a whole. Requires the admin role.

Path parameters​

workflow_idintegerrequired
The workflow.

Body​

namestringoptional
A new name.
conditionobjectoptional
A new condition.
stepsarrayoptional
New steps.
event_type_idintegeroptional
A new event type filter.
enabledbooleanoptional
false to stop the workflow, true to start it again.

Responses​

200
{"status": "updated"}, or {"status": "unchanged"} if the body had no fields.
403
You are not an admin.
404
No workflow with this ID.

Delete a workflow​

DELETE/workflows/{workflow_id}

Deletes a workflow. To stop it but keep it, set enabled to false instead. Requires the admin role.

Path parameters​

workflow_idintegerrequired
The workflow.

Responses​

200
{"status": "deleted"}.
403
You are not an admin.
404
No workflow with this ID.

List workflow runs​

GET/workflow-runs

Lists workflow runs, newest first. Argus records a run each time a workflow matches.

Query parameters​

limitintegeroptional
The most runs to return. Defaults to 50.

Response fields​

An array of runs:

idintegeroptional
The run ID.
workflow_idintegeroptional
The workflow.
workflow_namestringoptional
The workflow's name.
event_idintegeroptional
The rule event that started the run.
statusstringoptional
success, partial or failed.
logarrayoptional
One entry per step, with action, status and either result or error.
started_atstringoptional
When the run started.
finished_atstring or nulloptional
When it finished.

Responses​

200
The runs.
401
You are not signed in.

Event types​

An event type names a kind of event, such as perimeter-breach. A detection profile stamps its events with an event type, and a workflow with an event type only fires for events of that type. An event type's default_severity is used for alerts when neither the workflow step nor the profile sets one. See Event types.

Each event type has id, key, display_name, description, category (security, safety or operational), default_severity (info, medium or high), enabled and created_at.

List event types​

GET/event-types

Lists every event type, sorted by category and display name.

Responses​

200
The event types.
401
You are not signed in.

Create an event type​

POST/event-types

Creates an event type. Requires the admin role.

Body​

keystringrequired
Lower-case letters and digits, with words joined by single hyphens, such as perimeter-breach. Must be unique. Can't be changed later.
display_namestringrequired
The name shown in the dashboard.
descriptionstringoptional
A description.
categorystringoptional
security (the default), safety or operational.
default_severitystringoptional
medium (the default), info or high.

Responses​

201
The event type was created. Returns the event type.
403
You are not an admin.
409
An event type with this key already exists.
422
The key, category or severity is not valid.

Change an event type​

PATCH/event-types/{event_type_id}

Changes one or more fields. The key can't be changed. Requires the admin role.

Path parameters​

event_type_idintegerrequired
The event type.

Body​

display_namestringoptional
A new display name.
descriptionstringoptional
A new description.
categorystringoptional
security, safety or operational.
default_severitystringoptional
info, medium or high.
enabledbooleanoptional
Turn the event type on or off.

Responses​

200
The event type was changed. Returns the event type.
403
You are not an admin.
404
No event type with this ID.
422
A value is not valid, or the body has no fields.

Delete an event type​

DELETE/event-types/{event_type_id}

Deletes an event type that no workflow or detection profile uses. Otherwise set enabled to false. Requires the admin role.

Path parameters​

event_type_idintegerrequired
The event type.

Responses​

200
{"status": "deleted"}.
403
You are not an admin.
404
No event type with this ID.
409
A workflow or detection profile still uses it.
Was this page helpful?