Core Concepts

Every Gaard surface (web app, API, CLI) shares the same vocabulary. This page explains the concepts you will meet everywhere else in the documentation. Read it once and the rest of the guides will read faster.

Tenants and isolation

A tenant is the isolation boundary in Gaard. It owns your cameras, classifications, labels, configuration, and users, and nothing crosses from one tenant to another. When you sign in to the web app or authenticate an API token, you are always operating within a single tenant.

A tenant name is also a database identifier, so it follows strict rules:

• starts with a lowercase letter
• uses only a-z, 0-9, -, and _
• is at most 64 characters
• is never admin, config, or local

Because the tenant is the isolation boundary, every classification result carries its tenant, and every API token is scoped to one tenant. Shared views (for example, shareable links) only resolve for people in the same organization.

Solutions and entitlements

A solution is an entitleable product line. Your account is entitled to one or both:

• Classify: AI video classification (the subject of these guides).
• Replay: cloud video recording and playback.

Entitlements drive what you see: the solutions your account holds determine which apps appear in the web app switcher. Entitlements are about discoverability and access: they decide which surfaces are available to you, not how any single clip is scored.

Flows

A flow is a scoping and configuration unit within a tenant. Where the tenant is the hard isolation boundary, a flow lets you partition work inside it: for example, one flow per customer, region, or integration.

Flows matter when you:

• Scope a token or webhook. An API token or webhook can be tied to a specific flow so its traffic and delivery stay separated.
• Review a subset of alarms. The web app lets you switch the active flow to focus the dashboard and review workspace on one slice of activity.

See Flows for when to create one and how to scope tokens and webhooks to it.

Sites and cameras

Gaard organizes cameras under sites:

• A site is a physical location. Its identifier is the SID.
• A camera belongs to a site. Its identifier is the CID.

Both the Classify and Replay pipelines key on CID/SID, so a classification result and a recorded segment refer to the same physical camera, and the web app routes and filters on them.

There are two kinds of camera:

Camera type	Created by	Carries
API camera	Classify traffic, automatically	Only an identity derived from request metadata: no stream or credentials.
Managed camera	Configured explicitly	A full stream and credential configuration (used by Replay).

How metadata maps to a camera

When you submit a clip through the API, its metadata carries loose external identifiers. Gaard normalizes them into a stable identity:

• the site key is site_id
• the camera key is camera_id

The first time Gaard sees a new site/camera key, it creates an API camera (and its site) automatically; subsequent clips with the same keys resolve to the same camera. Clips with no usable site or camera key are classified but not attached to a camera. See Metadata for the full field list.

Risk levels

Gaard exposes three and only three risk levels:

• safe
• danger
• intrusion

The risk level is derived exclusively from the intrusion score using two configurable thresholds. The other scores are exposed for observability, but they do not drive the risk level.

Intrusion score	Risk level	Operational meaning
< low_threshold	safe	Normal background activity. May be filtered out.
>= low_threshold and < high_threshold	danger	Ambiguous or suspicious. Must be reviewed.
>= high_threshold	intrusion	High-confidence intrusion. Must be reviewed and escalated.

Typical thresholds are low_threshold = 0.2 and high_threshold = 0.8, and they are configurable per tenant. Anything that is not safe stays visible to operators: it is never discarded automatically. For the full derivation, see Risk, labels, and scores.

Labels

Where a score is the model’s raw confidence and the risk level is the derived decision, a label is a tag attached to a classification. There are three kinds:

• Standard labels: the built-in concepts Gaard recognizes, such as person, vehicle, animal, flag, rain, and wind.

• Custom labels: any tag your team defines for its own tracking.

• Feedback labels: an operator’s verdict on whether the model was right:

  Label	Meaning
  TP	True positive: Gaard correctly flagged a threat.
  FP	False positive: Gaard flagged a clip with no real threat.
  FN	False negative: Gaard missed a real threat.
  TN	True negative: Gaard correctly classified a clip as safe.

Feedback labels are how the model improves over time. See the Labels API for the endpoints, and Labeling & Feedback for the operator workflow.

The classification lifecycle

Every clip you submit becomes a classification, identified by a classify_id (the id in every API response). You use that ID to poll for the result, attach labels, or download the annotated video.

A classification moves through a set of statuses:

Status	Meaning
accepted	The clip has been accepted for analysis.
in-progress	Analysis is running.
done	Analysis is complete; the result is available.
error	An error occurred during analysis.
timeout	Analysis timed out.

Submit a clip asynchronously and you get back a classify_id immediately, then poll until the status is done; submit synchronously (?sync=true) and Gaard blocks until the result is ready. Either way, the finished result (risk level, labels, scores, and annotated highlight) lives against that classify_id and is reachable from every surface. See Classification result for the full result structure.

Next steps

• Web App Quickstart: see these concepts in the review workspace.
• API Quickstart: submit your first clip and watch it move through the lifecycle.
• Risk, labels, and scores: the detailed threshold reference.