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):

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Lobby Camera",
      "connection_mode": "gateway",
      "status": "online",
      "site_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "gateway_id": "9a7e8b14-3c2d-4e5f-8a9b-1c2d3e4f5a6b",
      "type": "onvif",
      "active_tier": "main",
      "created_at": "2026-02-01T10:00:00Z"
    }
  ],
  "next_cursor": null,
  "total": 1
}

The list response uses cursor-based pagination, not page-based. The next page is fetched with ?cursor=<next_cursor> from the previous response; the loop ends when next_cursor is null. total is the all-pages count.

Step 4 — Pretty-print with jq (optional)

Terminal window
curl -s -H "Authorization: Bearer $NOVAVMS_KEY" "$NOVAVMS_API/cameras" \
  | jq '.data[] | {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: