vss-setup-video-analytics-api v3.3.0A

Immutable. This exact content is served forever at /api/v1/blob/da3682913a1db151.

---
name: vss-setup-video-analytics-api
description: Use to deploy the vss-video-analytics-api REST service standalone with its Elasticsearch ingest-pipeline and, when configured, Kafka-topic readiness gates. Not for full warehouse deploy.
license: Apache-2.0
metadata:
  author: "NVIDIA Video Search and Summarization team"
  version: "3.3.0"
  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 any 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-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 — 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. **Kafka is optional only when disabled in the config.** With `kafka.brokers: []` or `null`, the API skips Kafka. With brokers configured, it waits before listening until `mdx-notification`, `mdx-amr`, and at least one `mdx-rtls*` topic exist. The service-shipped config enables Kafka, so choose either a broker-less config or provision those topics.
6. **`$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 a config — image-baked default, service-shipped, or custom.
2. Decide whether a data-log volume is needed for file uploads.
3. Confirm readiness dependencies — Elasticsearch plus `insertion-timestamp-pipeline`; and, if Kafka is configured, the required topics.
4. 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 broker)

When Kafka is configured, the container does not become live until its broker and 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-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 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