URL Scheme API

MouseViz supports a URL scheme API that lets you trigger any action programmatically. URL schemes are special links that, when opened, tell MouseViz to perform a specific action.

The general format is:

mouseviz://command-name?param1=value1&param2=value2

Quick Start

You can trigger URL schemes from Terminal, automation tools, or scripts:

Terminal:

open "mouseviz://start-recording"

AppleScript:

open location "mouseviz://start-recording"

Raycast / Alfred / Keyboard Maestro: Use the "Open URL" action with any mouseviz:// command.

Recording Control

Commands to start, stop, pause, and resume mouse tracking sessions.

Start Recording

mouseviz://start-recording

Begin a new mouse tracking session. If tracking is not already active, this starts a countdown and begins recording mouse movements, clicks, and scrolls. Ignored if already recording.

Available since v1.0

Stop Recording

mouseviz://stop-recording

Stop the current tracking session. If auto-save is enabled, the session data is saved automatically. Ignored if not recording.

Available since v1.0

Pause Recording

mouseviz://pause

Pause the current recording without ending it. Events stop being captured until resumed. Ignored if not recording or already paused.

Available since v1.2

Resume Recording

mouseviz://resume

Resume a paused recording session. Ignored if not paused.

Available since v1.2

Markers

Add timestamped markers during a recording to flag important moments.

Add Marker

mouseviz://add-marker?name=Task%201

Add a named task marker at the current timestamp in the active recording. Defaults to "Marker" if no name is provided. Ignored if not recording.

Examples:

# Add a named marker
open "mouseviz://add-marker?name=Checkout%20Flow"

# Add a default marker
open "mouseviz://add-marker"

Available since v1.2

Overlay & Visualization

Commands for controlling the visualization overlay.

Show Overlay

mouseviz://show-overlay

Show the visualization overlay (heatmap, trails, clicks, etc.).

Available since v1.2

Hide Overlay

mouseviz://hide-overlay

Hide the visualization overlay.

Available since v1.2

Set Visualization Mode

mouseviz://set-mode?mode=3

Set the active visualization mode using a bitmask value. See the mode values in Settings > Visualization.

Available since v1.2

Clear Overlay

mouseviz://clear

Clear all visualization data (heatmap, trails, click pulses) from the overlay.

Available since v1.2

Export

Export Heatmap

mouseviz://export-heatmap

Open the export dialog for the current heatmap visualization. Exports to the configured default directory.

Available since v1.2

Query Commands

Query commands return JSON data by copying it to your system clipboard. After opening the URL, paste (⌘V) to access the result.

Get Status

mouseviz://status

Copies JSON with the current recording status to the clipboard:

{
  "isTracking": true,
  "isPaused": false,
  "duration": 125.4,
  "totalMoves": 4200,
  "totalClicks": 38,
  "totalScrolls": 12,
  "markerCount": 3,
  "eventCount": 4250,
  "activeModes": 1,
  "participant": "Alice",
  "project": "Checkout Redesign"
}

Automation example:

open "mouseviz://status" && sleep 0.5 && pbpaste | jq .isTracking

Available since v1.2

List Session History

mouseviz://list-history?limit=5

Copies a JSON array of recent sessions to the clipboard.

Available since v1.2

Get Version

mouseviz://version

Copies the app version and build number as JSON to the clipboard.

Available since v1.2

Health Check

mouseviz://health-check

Copies a diagnostic health report as JSON to the clipboard. Useful for troubleshooting.

Available since v1.2

Navigation

Commands that open specific windows or panels in MouseViz.

Open Settings

mouseviz://settings

Open the MouseViz settings window.

Available since v1.0

Open Study Scripts

mouseviz://study-scripts

Open the Study Scripts panel to view, create, and manage your study scripts.

Available since v1.0

Import Study Script

mouseviz://import-study?file=/path/to/script.json

Import a study script from a JSON file on disk. The file must conform to the MouseViz study script schema. After import, the Study Scripts panel opens automatically.

Examples:

# Import from Desktop
open "mouseviz://import-study?file=/Users/me/Desktop/usability-test.json"

# Import from Downloads
open "mouseviz://import-study?file=/Users/me/Downloads/study.json"

The file path must be URL-encoded if it contains spaces or special characters.

Available since v1.0

Open File

mouseviz://open-file?path=/path/to/image.png&type=image

Open a file in the appropriate MouseViz editor. Used by the Share Extension to hand off files to the main app.

Available since v1.2