Skip to content

API & Third-Party Integrations 🔌

VibeNVR is designed to be extensible and easily integrated into your existing smart home or dashboard ecosystem.

🏠 Homepage Integration

Homepage is a modern, static, semi-automated dashboard. VibeNVR provides a compatible API endpoint for the customapi widget.

⚙️ Configuration

Add the following to your services.yaml in Homepage:

- VibeNVR:
    icon: mdi-cctv
    href: http://your-vibenvr-ip:8080/
    description: Video Surveillance
    widget:
      type: customapi
      url: http://your-vibenvr-ip:8080/api/v1/homepage/stats
      headers:
        X-API-Key: "your-api-token-here"  # Found in Settings -> General
      method: GET
      mappings:
        - { field: cameras_online, label: Online }
        - { field: cameras_recording, label: Recording }
        - { field: events_today, label: Events (24h) }
        - { field: storage_used_gb, label: Storage (GB) }
        - { field: storage_total_gb, label: Total Disk (GB) }

🔑 Obtaining an API Key

Navigate to Settings -> General in the VibeNVR UI. Your API key is unique to your installation and should be kept private.

🤖 Home Assistant (MQTT)

VibeNVR supports MQTT Discovery, meaning it will automatically appear in Home Assistant once the MQTT service is configured.

⚙️ Setup

  1. Go to Settings -> MQTT Service.
  2. Enable the service and provide your broker details.
  3. In Home Assistant, navigate to Settings -> Devices & Services -> MQTT.
  4. You should see a new device for each of your cameras.

📊 Available Entities

  • Binary Sensor: Motion detection state (ON/OFF).
  • Sensor: Camera status (online/offline).
  • Attributes: JSON metadata containing AI detection results (labels, confidence).

For more details, see the MQTT Integration Guide.

📹 Home Assistant Live View / Restream

VibeNVR integrates go2rtc internally as its core stream gateway, which can be used to expose streams to Home Assistant with zero latency, preventing multiple connections to the physical cameras (Camera → VibeNVR → HA).

  1. Edit your docker-compose.yml to expose the internal go2rtc ports from the engine service: 
      engine:
    ...
    ports:
      - "1984:1984" # go2rtc API & WebRTC
      - "8554:8554" # go2rtc RTSP
  2. Restart the containers.
  3. In Home Assistant, install the WebRTC Camera custom component (or use the generic RTSP integration).
  4. Point the integration to http://<VIBENVR_IP>:1984.

The streams are automatically named cam_<id> (e.g., cam_1, cam_2). This will give you zero-latency Live View in HA using the stream already managed by VibeNVR.

Note: Ensure the "Internal go2rtc Gateway" is enabled in VibeNVR's global settings (Settings -> General).

📱 Telegram Notifications

VibeNVR supports real-time alerts with snapshot attachments via Telegram Bots.

🛠️ Hardened Security

The notification pipeline is hardened to ensure that special characters in camera names or object labels do not cause API failures. - HTML Escaping: All data sent to Telegram is automatically HTML-escaped. - Snapshot Cleanup: Temporary snapshots used for notifications are automatically cleaned up after 1 hour.

⚙️ Setup

  1. Create a bot using @BotFather.
  2. Obtain your Bot Token.
  3. Get your Chat ID (using bots like @userinfobot).
  4. Configure these in Settings -> Notifications.

🌍 SOCKS/HTTPS Proxy & Auto-Retry

If your NVR is on a restricted network or Telegram is blocked in your region, VibeNVR natively supports routing notifications through a proxy. - Format: socks5://user:pass@host:port or http://... - Auto-Retry: Since free public proxies are often unstable, VibeNVR implements an intelligent background retry mechanism. You can configure the Max Retries and Retry Delay in the Settings UI. If a proxy drops the connection, VibeNVR will silently retry sending the notification without crashing or blocking the recording engine.

🛠️ REST API

For custom scripts or advanced integrations, VibeNVR exposes a full REST API.

📚 Documentation

  • Interactive Swagger: Access /docs on your backend port (default: 5005).
  • API Reference: See the API.md wiki page for common endpoints.

🛡️ Authentication

All API requests (except public assets) require a Bearer token or a valid X-API-Key header.