Skip to content

Watcher API: mobile access and agents

On a running Optic installation, you can enable compatibility with the Flussonic Watcher mobile app and connect cameras through agents. Optic needs a public HTTPS origin reachable by the phone, agents and Peeklio. API and video must be available through the same origin, for example https://optic.example.com.

Enable the Watcher API

For a package installation, create /etc/optic/optic.yaml.d/90-mobile.conf:

optic:
  mobile_compat:
    enabled: true

This directory loads files ending in .conf or .json. A later file replaces the entire optic section: if it already contains custom settings, retain them in the same block alongside mobile_compat.

Restart Optic:

systemctl restart optic

This setting enables the Watcher client API for login and camera playback under /watcher/client-api/v3/. It is disabled by default. Changes require a restart; the Mobile access page shows status and issues login QR codes, but cannot yet change this setting.

Connect the mobile app

  1. Create a named central account. Complete any required temporary password change before connecting the app.
  2. Sign in to the console through Optic's public origin and open Mobile access.
  3. Generate a QR code for your account and scan it in the Watcher app. The code expires after five minutes; a superadministrator can generate one for another eligible account.

Camera viewing permissions:

  • superadmin and admin — all cameras in the installation.
  • viewer — cameras selected by content_labels: an absent field allows all, an empty list allows none, and a nonempty list allows cameras with at least one matching label.
  • security and player — mobile access denied.

The app provides live video and the existing archive. Enabling the API does not enable camera recording by itself.

Enable episode notifications

Configure the Peeklio connection under Connect Optic, then sign in to the Watcher app with your own account. Allow notifications in the phone settings and enable the camera's bell. Only recipients who currently have permission to view the camera receive notifications.

Supported subscriptions:

  • Motion — new motion episodes.
  • Faces — new face recognition episodes when analytics is configured.
  • Vehicles — new vehicle recognition episodes when analytics is configured.

The automatic notification limit is shared by the recipient: at most one notification every ten minutes across all their cameras and devices. Events during this interval do not create a separate delayed notification. Restarting Optic or disabling and re-enabling the bell does not reset the limit. Temporary delivery failures are retried after the same interval.

To check delivery, select Send test notification in the mobile app settings. The test is sent to all registered devices on your account and does not require a camera event or an enabled bell. You can request it without waiting for the automatic notification interval. Automatic notifications resume no sooner than ten minutes after the test is sent.

Tapping an episode notification opens the camera at the episode time. Configure recording and camera events beforehand. Subscribing does not send accumulated history. After migrating from Watcher without importing devices, sign in again and enable camera notifications. Blocking new agent connections does not disable existing push delivery.

Allow cameras to be added through agents

Sign in as admin or superadmin and open Optic connection in the console menu.

  1. Turn on Enable agent registration.
  2. Set Peeklio service origin, for example https://api.peeklio.net, and Public Optic origin, for example https://optic.example.com. Enter origins without additional paths.
  3. Select a Default camera template from the existing central templates. If none exist, create a template with camera settings; a single available template is selected automatically.
  4. Click Save, then Register / update installation. For a new installation, leave Operator ID and Installation API key empty: Optic generates the key and saves the returned Operator ID. For an existing installation, restore its previous Operator ID and API key first.
  5. Click Check connection and confirm that the check succeeds.

Saving settings and registering are separate actions. After registration, the Operator ID can be used to sign in to the app. Restarting Optic does not repeat registration.

Adding a camera from a phone is available to admin and superadmin. In the app, start adding a camera with an agent and follow the selected connection workflow. The agent contacts Peeklio, which sends its details to Optic. A camera named ag-<agent_id> appears in Streams with the selected template. Its appearance alone does not confirm video ingest: the streamer must also be configured.

Configure video ingest through agents

  1. Open Cluster → Streamers and the settings of the streamer that will ingest video. For a single-machine installation, select the local streamer.
  2. Under Connection, set a Public media address reachable by agents. For a single-machine installation, use Optic's public address: host optic.example.com, port 443, scheme https.
  3. Save changes and wait for the streamer to apply the configuration.

When central starts or a new node joins, central automatically creates and saves a missing media tunnel key for each streamer, including the local one. You do not need to enter streampoint_key manually. Existing keys are preserved across restarts.

The agent establishes its control connection to Optic through /endpoint/connect and the media tunnel to the assigned streamer through /streampoint/connect. If a reverse proxy already fronts Optic, both paths must allow persistent HTTP Upgrade connections. When an agent connects without video, check the streamer's public address and whether its configuration has been applied.

Verify operation

To check login, use a named account; curl prompts for its password:

curl -sS --user operator1 --request POST --output /dev/null \
  --write-out '%{http_code}\n' \
  https://optic.example.com/watcher/client-api/v3/login

Expect 200. An incorrect password returns 401; a disabled account or prohibited role returns 403. For 404, check 90-mobile.conf and that Optic was restarted after the change.

Under Agents, check the agent's control connection and its association with a stream and streamer. Open the camera and confirm its status is running and video plays. Then check the same camera in the mobile app.

Disable access

To disable mobile login and playback, set enabled: false in 90-mobile.conf and restart Optic.

To prevent new agents from being added, turn off Enable agent registration under Optic connection and save. Existing agents and streams remain; these settings do not stop camera recording by themselves.

Linked phones

Open Linked phones in the Optic menu. Administrators can see the owner's login, phone model and platform, version, registration and latest push confirmation times, and counts of sent and unconfirmed notifications. An unconfirmed notification does not by itself prove that nothing appeared on the phone.

Devices and subscriptions belong to a login. Recreating an account with the same login preserves these links. Push tokens are not shown in the list.

Operator API: GET /optic/api-v1/devices?offset=0. The response contains devices and next_offset. If next_offset is not null, pass it as offset for the next page. A page contains up to 100 registrations.