Skip to content
NovaVMS Manual

Your first curl

By the end of this tutorial you will have hit the NovaVMS REST API from your terminal with curl and parsed a real JSON response listing your organisation’s cameras. No SDK, no framework — just an HTTPS request and a shell.

What you will need

  • A NovaVMS organisation in production (novavms.novalien.com) with at least one camera
  • An admin or owner account (you mint the API key yourself)
  • curl installed (any version since 7.x)
  • Optionally jq for pretty JSON — not required

Step 1 — Mint a service-account API key

Sign in to https://novavms.novalien.com as an admin, then follow Rotate an API key to create a new key. Copy the key — it looks like sk_live_abc123 — and keep it ready. If you lose it, create a new one; keys are displayed exactly once.

Step 2 — Export environment variables

In your shell (since v1.0):

Terminal window
export NOVAVMS_API="https://novavms.novalien.com/api/v1"
export NOVAVMS_KEY="sk_live_abc123"    # the key you just minted

Step 3 — List your cameras

Terminal window
curl -H "Authorization: Bearer $NOVAVMS_KEY" "$NOVAVMS_API/cameras"

Expected response (truncated to one camera for readability):

{
  "cameras": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Lobby Camera",
      "connection_mode": "gateway",
      "status": "online",
      "site_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "site_name": "Headquarters",
      "gateway_id": "9a7e8b14-3c2d-4e5f-8a9b-1c2d3e4f5a6b",
      "codec": "h265",
      "resolution_width": 2560,
      "resolution_height": 1440,
      "has_audio": true,
      "has_ptz": false,
      "last_event_at": "2026-04-21T14:00:00Z",
      "enabled": true,
      "created_at": "2026-02-01T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

The response shape is stable since v1.0. thumbnail_url is only returned when the camera has a recent snapshot — don’t rely on its presence.

Step 4 — Pretty-print with jq (optional)

Terminal window
curl -s -H "Authorization: Bearer $NOVAVMS_KEY" "$NOVAVMS_API/cameras" \
  | jq '.cameras[] | {id, name, status}'
{"id":"550e8400-e29b-41d4-a716-446655440000","name":"Lobby Camera","status":"online"}

Step 5 — Fetch one camera by id

Terminal window
curl -H "Authorization: Bearer $NOVAVMS_KEY" \
  "$NOVAVMS_API/cameras/550e8400-e29b-41d4-a716-446655440000"

The single-camera response includes the same fields plus nested site and gateway objects. See the camera endpoints reference for the full schema.

You have finished

You have authenticated with a service-account key, hit a production REST endpoint, and parsed real JSON. Next, you may want to: