diff --git a/doc/Makefile.am b/doc/Makefile.am
index cf7d6701b303..50f42bfa0db4 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -208,6 +208,9 @@ MAN3_FILES_SECONDARY = \
 	man3/flux_watcher_stop.3 \
 	man3/flux_watcher_is_active.3 \
 	man3/flux_watcher_destroy.3 \
+	man3/flux_watcher_ref.3 \
+	man3/flux_watcher_unref.3 \
+	man3/flux_watcher_is_referenced.3 \
 	man3/flux_watcher_next_wakeup.3 \
 	man3/flux_handle_watcher_get_flux.3 \
 	man3/flux_timer_watcher_reset.3 \
diff --git a/doc/man3/flux_watcher_start.rst b/doc/man3/flux_watcher_start.rst
index a902021e3625..dee40946042d 100644
--- a/doc/man3/flux_watcher_start.rst
+++ b/doc/man3/flux_watcher_start.rst
@@ -15,6 +15,12 @@ SYNOPSIS
 
   bool flux_watcher_is_active (flux_watcher_t *w);
 
+  void flux_watcher_unref (flux_watcher_t *w);
+
+  void flux_watcher_ref (flux_watcher_t *w);
+
+  bool flux_watcher_is_referenced (flux_watcher_t *w);
+
   void flux_watcher_destroy (flux_watcher_t *w);
 
   double flux_watcher_next_wakeup (flux_watcher_t *w);
@@ -36,6 +42,21 @@ callback.
 :func:`flux_watcher_is_active` returns a true value if the watcher is active
 (i.e. it has been started and not yet stopped) and false otherwise.
 
+:func:`flux_watcher_unref` drops the watcher's reference on the reactor.
+This function is idempotent.  :func:`flux_reactor_run` normally runs until
+there are no more active watchers with references.
+
+:func:`flux_watcher_ref` restores the watcher's reference on the reactor.
+This function is idempotent.
+
+:func:`flux_watcher_is_referenced` returns true if the watcher is referenced.
+All watchers are referenced unless updated with :func:`flux_watcher_unref`.
+
+.. note::
+  All watchers in the public API support :func:`flux_watcher_unref`, but some
+  specialized watchers internal to flux-core do not.  If in doubt about whether
+  the call had any effect, check with :func:`flux_watcher_is_referenced`.
+
 :func:`flux_watcher_destroy` destroys a :type:`flux_watcher_t` object :var:`w`,
 after stopping it. It is not safe to destroy a watcher object within a
 :type:`flux_watcher_f` callback.
diff --git a/doc/manpages.py b/doc/manpages.py
index e4c9a8a79dea..afabfd784b88 100644
--- a/doc/manpages.py
+++ b/doc/manpages.py
@@ -280,11 +280,14 @@
     ('man3/flux_stat_watcher_create', 'flux_stat_watcher_create', 'create stat watcher', [author], 3),
     ('man3/flux_timer_watcher_create', 'flux_timer_watcher_reset', 'set/reset a timer', [author], 3),
     ('man3/flux_timer_watcher_create', 'flux_timer_watcher_create', 'set/reset a timer', [author], 3),
-    ('man3/flux_watcher_start', 'flux_watcher_stop', 'start/stop/destroy/query reactor watcher', [author], 3),
-    ('man3/flux_watcher_start', 'flux_watcher_is_active', 'start/stop/destroy/query reactor watcher', [author], 3),
-    ('man3/flux_watcher_start', 'flux_watcher_destroy', 'start/stop/destroy/query reactor watcher', [author], 3),
-    ('man3/flux_watcher_start', 'flux_watcher_next_wakeup', 'start/stop/destroy/query reactor watcher', [author], 3),
-    ('man3/flux_watcher_start', 'flux_watcher_start', 'start/stop/destroy/query reactor watcher', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_stop', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_is_active', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_destroy', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_next_wakeup', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_start', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_ref', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_unref', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_is_referenced', 'common reactor watcher methods', [author], 3),
     ('man3/flux_watcher_set_priority', 'flux_watcher_set_priority', 'set watcher priority', [author], 3),
     ('man3/hostlist_create', 'hostlist_create', 'Manipulate lists of hostnames', [author], 3),
     ('man3/hostlist_create', 'hostlist_destroy', 'Manipulate lists of hostnames', [author], 3),
diff --git a/doc/test/spell.en.pws b/doc/test/spell.en.pws
index a6163e2b6129..591c073ccbfb 100644
--- a/doc/test/spell.en.pws
+++ b/doc/test/spell.en.pws
@@ -939,3 +939,4 @@ aTGTz
 cPATH
 SATTR
 myprogram
+unref