Purpose

Deploy the video-analytics-api REST service standalone with the user's chosen config, data-log bind, and Elasticsearch / Kafka connectivity.

Instructions

Follow the routing tables and step-by-step workflows below. Each section that ends in workflow, quick start, or flow is intended to be executed top-to-bottom. Detailed reference material lives in

references/

and helper scripts live in

scripts/

— call them via

run_script

when the skill points to a script by name.

Examples

Worked end-to-end examples are kept under

evals/

(each

*.json

manifest contains a runnable scenario). Run a Tier-3 evaluation to replay them:

bash

nv-base validate skills/vss-setup-video-analytics-api --agent-eval

A minimal standalone bring-up looks like:

bash

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
export VSS_DATA_DIR=${VSS_DATA_DIR:-/tmp/vss-data}
mkdir -p "$VSS_DATA_DIR/data_log/vss_video_analytics_api"
docker compose -f services/analytics/video-analytics-api/compose.yml up -d vss-video-analytics-api
curl -sf http://localhost:8081/livez

references/deploy-video-analytics-api-service.md

for the full workflow (config source, data-log bind, infrastructure dependencies, REST endpoints).

Limitations

Requires the matching VSS profile / microservice to be deployed and reachable from the caller.
NGC-hosted models and NIMs may be subject to rate-limits, GPU memory requirements, and license restrictions.
Concurrency, GPU memory, and storage limits depend on the host hardware and the profile's compose file.

Troubleshooting

Error: REST call returns connection refused. Cause: target microservice not running. Solution: probe
```
/docs
```
or
```
/health
```
; redeploy via
```
vss-deploy-profile
```
or the matching
```
vss-deploy-*
```
skill.
Error: HTTP 401/403 from NGC pulls. Cause: missing/expired
```
NGC_CLI_API_KEY
```
. Solution:
```
docker login nvcr.io
```
and re-export the key before retrying.
Error: container OOM or model fails to load. Cause: insufficient GPU memory for the selected profile. Solution: switch to a smaller variant or free GPUs via
```
docker compose down
```
.

VSS Setup Video Analytics API — Standalone

Deploy just the

vss-video-analytics-api

container (the Node.js REST API from the upstream

video-analytics-api

repo), not as part of the full warehouse blueprint stack.

The full operational walkthrough — config-source options, data-log volume behavior, infrastructure dependencies, REST API endpoints, deploy + verify, troubleshooting — is

references/deploy-video-analytics-api-service.md

. This SKILL.md only handles routing and prerequisites.

When to use

"Deploy video analytics api" / "run video-analytics-api standalone"
"I just want to run the REST API, not the full stack"
"Use my own video-analytics-api config"
"Point the API at a different Elasticsearch / Kafka"
"Start the API without Kafka" / "run the API broker-less"
"Check what REST endpoints are available"

Prerequisites

Repo checkout with
```
$VSS_APPS_DIR
```
pointing at
```
<repo>/deploy/docker/
```
. Required by the service compose's volume binds.
NGC credentials —
```
$NGC_CLI_API_KEY
```
set so docker can pull the image. See
../vss-deploy-profile/references/ngc.md
.
Secure-handling note for
NGC_CLI_API_KEY
: this key is a long-lived credential that pulls all NVIDIA private images available to your NGC org. Never commit the key, never paste it into chat, never store it in
/tmp
. Read it interactively (
read -rs NGC_CLI_API_KEY
) or load it from your secret manager (Vault, AWS Secrets Manager, sealed-secrets) at deploy time. Write any derived
.env
files with
umask 077
+
chmod 600
, add them to
.gitignore
, and rotate the key on a defined cadence and after every host decommission. If it has ever been exposed (host snapshot, shared screen, ticket attachment), rotate immediately.
Docker runtime — Docker Engine 28.3.3 with Docker Compose plugin v2.39.1+. Verify with
```
docker --version
```
and
```
docker compose version
```
.
Elasticsearch — must be reachable at the URL configured in
```
elasticsearch.node
```
. The server pings ES on startup; if unreachable, it exits (and
```
restart: always
```
brings it back). If you need to bring up ES too, use the infra compose:
```
docker compose -f services/infra/compose.yml up -d elasticsearch
```
.
Optional Kafka broker. The API can run without Kafka. If you want a quiet broker-less deployment, use the image-baked config or a custom config with
```
kafka.brokers: []
```
; the service-shipped compose config points at
```
localhost:9092
```
, so Kafka-dependent features (dynamic config, dynamic calibration, RTLS/AMR) will fail until a broker is reachable.
$VSS_DATA_DIR
for the default compose. The base compose bind-mounts
```
$VSS_DATA_DIR/data_log/vss_video_analytics_api
```
for multipart upload handling and file-backed assets such as calibration images. Set the directory to a writable host path and pre-create it, or remove that mount if image uploads are not needed.

If any required prerequisite fails, surface the gap before going further.

Workflow

Hand the user

references/deploy-video-analytics-api-service.md

and walk them through its steps in order:

Choose a config — image-baked default, service-shipped, or custom.
Decide whether a data-log volume is needed for file uploads.
Confirm infrastructure dependencies — Elasticsearch (required), Kafka (optional).
Deploy + verify with
```
docker compose up
```
and health check.

The compose-file edits, config options, deploy + verify commands, REST API endpoint table, and troubleshooting table all live in that reference — don't duplicate them here.

REST API capabilities

Once the container is up and Elasticsearch is reachable, the API serves the endpoint groups listed in

references/deploy-video-analytics-api-service.md

§ REST API endpoints.

The server must initialize against Elasticsearch before

/livez

can return healthy. Data-query endpoints also need matching Elasticsearch indices and data. Endpoints that publish notifications (config, calibration) or expose RTLS / AMR streams also require Kafka.

Kafka-dependent features (runtime, requires broker)

Once the container is up and a Kafka broker is reachable, three additional capabilities are available:

Dynamic config

The API acts as the producer for dynamic config updates. When an operator POSTs to

/config

, the API publishes an

upsert

message to the

mdx-notification

topic with Kafka key

behavior-analytics-config

. The downstream

behavior-analytics

container consumes this and ACKs back. The API also handles the bootstrap flow — when

behavior-analytics

starts, it publishes a

request-config

message, and the API replies with

upsert-all

containing the latest verified config from Elasticsearch.

Consumer-side validation, ACK semantics, and the full wire contract are documented in

../vss-setup-behavior-analytics/references/dynamic-config.md

Dynamic calibration

The API produces calibration update notifications on

mdx-notification

with Kafka key

calibration

. Supports

upsert-all

(full snapshot),

upsert

(per-sensor merge), and

delete

(per-sensor removal). The downstream

behavior-analytics

container consumes these and applies them to the live calibration.

Consumer-side validation and per-action policy are documented in

../vss-setup-behavior-analytics/references/dynamic-calibration.md

RTLS / AMR

The API consumes real-time location (

mdx-rtls

) and AMR (

mdx-amr

) messages from Kafka and exposes them via REST endpoints.

Routing rules

If the user wants "the full stack" (UI / agent / perception): hand off to
```
vss-deploy-profile
```
with profile
```
warehouse
```
(or
```
alerts
```
). Don't run this skill in parallel.
If the user wants to deploy the analytics pipeline (behavior creation, incident detection): hand off to
```
vss-setup-behavior-analytics
```
.
If the user wants to publish a runtime config / calibration update through the REST API: confirm Kafka is reachable, then use the
```
/config
```
or calibration endpoints and point them at the behavior-analytics dynamic-update references for the consumer wire contract.
If the user wants to understand the dynamic config / dynamic calibration wire contract from the consumer (behavior-analytics) side: point them at
```
../vss-setup-behavior-analytics/references/dynamic-config.md
```
and
```
../vss-setup-behavior-analytics/references/dynamic-calibration.md
```
.
If the user wants to query or interact with the REST API endpoints: the endpoint table above and the deploy reference cover what's available. For the full OpenAPI spec, see
```
src/app/specification/openapi.json
```
in the
```
video-analytics-api
```
repo.

vss-setup-video-analytics-api

NPX Install

Tags

SKILL.md Content