Vss Setup Video Analytics Api

---
name: vss-setup-video-analytics-api
description: Use to deploy the vss-video-analytics-api REST service standalone with its Elasticsearch ingest-pipeline, selectable Kafka/Redis stream type, and Kafka-topic readiness gates when Kafka is selected. Not for full warehouse deploy.
license: Apache-2.0
metadata:
  author: "NVIDIA Video Search and Summarization team"
  version: "3.3.0-rc0"
  github-url: "https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization"
  tags: "nvidia blueprint operational deployment video-analytics-api rest-api"
---
## Purpose

Deploy the video-analytics-api REST service standalone with the user's chosen config and data-log bind. The service exposes port 8081 and `/livez` only after Elasticsearch, the `insertion-timestamp-pipeline`, and, when `STREAM_TYPE=kafka`, the configured Kafka topic requirements are ready.

## 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/`.

## 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/deployment/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
```

Follow [`references/deploy-video-analytics-api-service.md`](references/deploy-video-analytics-api-service.md) for the full
workflow (config source, data-log bind, infrastructure dependencies, REST endpoints).
For the field-by-field JSON config reference, see [`references/configuration.md`](references/configuration.md).

## 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-build-vision-ai` 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 — lives in [`references/deploy-video-analytics-api-service.md`](references/deploy-video-analytics-api-service.md). The field-by-field JSON config reference lives in [`references/configuration.md`](references/configuration.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

1. **Repo checkout** with `$VSS_APPS_DIR` pointing at `<repo>/deploy/docker/`. Required by the service compose's volume binds.
2. **NGC credentials** — `$NGC_CLI_API_KEY` set so docker can pull the image. See [`references/ngc-api-key-registry-login.md`](references/ngc-api-key-registry-login.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.
3. **Docker runtime** — Docker Engine **28.3.3** with Docker Compose plugin **v2.39.1+**. Verify with `docker --version` and `docker compose version`.
4. **Elasticsearch and ingest pipeline** — the endpoint in `elasticsearch.node` must be reachable and contain `insertion-timestamp-pipeline`. Elasticsearch port availability alone is insufficient: the API deliberately waits for that pipeline before binding port 8081. When using the infra compose, start both `elasticsearch` and `elasticsearch-init-container`.
5. **`STREAM_TYPE`** — Compose passes this environment variable to the API. It accepts only `kafka` or `redis`; unset defaults to `kafka`, and any other value makes the API exit at startup. With `STREAM_TYPE=kafka`, the API waits for configured Kafka topics. With `STREAM_TYPE=redis`, it skips Kafka startup work and topic readiness gates; the API does not create a Redis client.
6. **Kafka configuration when `STREAM_TYPE=kafka`.** With `kafka.brokers: []` or `null`, Kafka startup work is skipped. With brokers configured, the API waits before listening until `mdx-notification`, `mdx-amr`, and at least one `mdx-rtls*` topic exist. The service-shipped config enables Kafka, so provision those topics when selecting Kafka.
7. **`$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`](references/deploy-video-analytics-api-service.md) and walk them through its steps in order:

1. Choose `STREAM_TYPE`: `kafka` or `redis`; omit it only to use the Kafka default.
2. Choose a config — image-baked default, service-shipped, or custom.
3. Decide whether a data-log volume is needed for file uploads.
4. Confirm readiness dependencies — Elasticsearch plus `insertion-timestamp-pipeline`; and, only for `STREAM_TYPE=kafka` with configured brokers, the required topics.
5. 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.

## Endpoint Reference

Use [`references/deploy-video-analytics-api-service.md`](references/deploy-video-analytics-api-service.md) for the REST endpoint table and runtime dependency notes.

## Kafka-dependent features (runtime, requires `STREAM_TYPE=kafka` and non-empty `kafka.brokers`)

When `STREAM_TYPE=kafka` and `kafka.brokers` is non-empty, the container does not become live until those brokers and the required topics are available. Once it is live, 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 the `vss-setup-behavior-analytics` dynamic-config reference.

### 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 the `vss-setup-behavior-analytics` dynamic-calibration reference.

### 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-build-vision-ai` 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 `STREAM_TYPE=kafka` and Kafka are 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 the `vss-setup-behavior-analytics` dynamic-config and dynamic-calibration references.
- If the user wants to query or interact with the REST API endpoints: the deploy reference endpoint table covers what's available. For the full OpenAPI spec, see `src/app/specification/openapi.json` in the `video-analytics-api` repo.


bump:1