syncthing · acolomb · Mar 19, 2020 · Apr 1, 2020 · Jun 14, 2020 · Nov 22, 2020
diff --git a/dev/rest.rst b/dev/rest.rst
@@ -32,9 +32,21 @@ Config Endpoints
 
 .. toctree::
    :maxdepth: 1
+   :glob:
 
    /rest/config/... <../rest/config.rst>
 
+Cluster Endpoints
+-----------------
+
+Concerns the mesh network structure.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   ../rest/cluster-*
+
 Database Endpoints
 ------------------
 

diff --git a/rest/cluster-candidate-devices-get.rst b/rest/cluster-candidate-devices-get.rst
@@ -0,0 +1,75 @@
+GET /rest/cluster/candidate/devices
+===================================
+
+.. versionadded:: 1.FIXME
+
+Lists remote devices which were introduced as part of another remote
+device's ``ClusterConfig`` message, but do not directly share a
+specific folder with our instance.  See :ref:`clusterconfig` for what
+information is available about such devices.  They share a folder with
+us already, but only indirectly over at least one extra "hop", the
+introducing device.  Adding the missing direct link densifies the
+cluster's mesh structure without giving additional access to anyone.
+
+Given an ID in the ``folder`` parameter, candidate devices are
+enumerated where it is only shared indirectly.  Any device which is
+already known locally is referenced only by its device ID.  Unknown
+device entries are supplemented with metadata from the introducing
+devices.
+
+.. code-block:: json
+
+    {
+      "DOVII4U-SQEEESM-VZ2CVTC-CJM4YN5-QNV7DCU-5U3ASRL-YVFG6TH-W5DV5AA": {
+        "introducedBy": {
+          "YZJBJFX-RDBL7WY-6ZGKJ2D-4MJB4E7-ZATSDUY-LD6Y3L3-MLFUYWE-AEMXJAC": {
+            "commonFolders": {
+              "cpkn4-57ysy": "Pictures from Joe"
+            },
+            "time": "2020-03-18T11:43:07+01:00"
+          }
+        }
+      },
+      "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
+        "addresses": [
+          "tcp://192.168.1.2:22000",
+          "tcp://[2a02:8070::ff34:1234::aabb]:22000",
+          "tcp://janes.laptop.example.com:22000",
+          "dynamic"
+        ],
+        "certName": "",
+        "introducedBy": {
+          "DOVII4U-SQEEESM-VZ2CVTC-CJM4YN5-QNV7DCU-5U3ASRL-YVFG6TH-W5DV5AA": {
+            "commonFolders": {
+              "cpkn4-57ysy": "Pics from Jane"
+            },
+            "suggestedName": "Jane",
+            "time": "2020-03-01T10:12:13+01:00"
+          },
+          "YZJBJFX-RDBL7WY-6ZGKJ2D-4MJB4E7-ZATSDUY-LD6Y3L3-MLFUYWE-AEMXJAC": {
+            "commonFolders": {
+              "cpkn4-57ysy": "Pics of J & J"
+            },
+            "suggestedName": "Jane's Laptop",
+            "time": "2020-03-18T11:43:07+01:00"
+          }
+        }
+      },
+      "UYGDMA4-TPHOFO5-2VQYDCC-7CWX7XW-INZINQT-LE4B42N-4JUZTSM-IWCSXA4": {
+        "introducedBy": {
+          "AIBAEAQ-CAIBAEC-AQCAIBA-EAQCAIA-BAEAQCA-IBAEAQC-CAIBAEA-QCAIBA7": {
+            "commonFolders": {
+              "cpkn4-57ysy": "Family pics"
+            },
+            "time": "2020-02-22T14:56:00+01:00"
+          },
+          "YZJBJFX-RDBL7WY-6ZGKJ2D-4MJB4E7-ZATSDUY-LD6Y3L3-MLFUYWE-AEMXJAC": {
+            "commonFolders": {
+              "abcde-fghij": "Mighty nice folder",
+              "cpkn4-57ysy": "Family pics"
+            },
+            "time": "2020-03-18T11:43:07+01:00"
+          }
+        }
+      }
+    }
diff --git a/rest/cluster-candidate-folders-get.rst b/rest/cluster-candidate-folders-get.rst
@@ -0,0 +1,55 @@
+GET /rest/cluster/candidate/folders
+===================================
+
+.. versionadded:: 1.FIXME
+
+Lists folder IDs that we do not currently share with a known remote
+device directly, but which they already have indirect access to.  That
+information was collected as part of other remote devices'
+``ClusterConfig`` messages, which share the specific folder with both
+our instance and the candidate device.  See :ref:`clusterconfig` for
+what information is available about such devices.  They share a folder
+with us already, but only indirectly over at least one extra "hop",
+the introducing device.  Adding the missing direct link densifies the
+cluster's mesh structure without giving additional access to anyone.
+This endpoint does not mention any locally unknown devices.
+
+Given a known device ID in the ``device`` parameter, the list is
+limited to only folder IDs for which that device is a candidate.
+
+.. code-block:: json
+
+    {
+      "abcde-fghij": {
+        "UYGDMA4-TPHOFO5-2VQYDCC-7CWX7XW-INZINQT-LE4B42N-4JUZTSM-IWCSXA4": {
+          "introducedBy": {
+            "YZJBJFX-RDBL7WY-6ZGKJ2D-4MJB4E7-ZATSDUY-LD6Y3L3-MLFUYWE-AEMXJAC": {
+              "label": "Mighty nice folder",
+              "time": "2020-03-18T11:43:07+01:00"
+            }
+          }
+        }
+      },
+      "cpkn4-57ysy": {
+        "DOVII4U-SQEEESM-VZ2CVTC-CJM4YN5-QNV7DCU-5U3ASRL-YVFG6TH-W5DV5AA": {
+          "introducedBy": {
+            "YZJBJFX-RDBL7WY-6ZGKJ2D-4MJB4E7-ZATSDUY-LD6Y3L3-MLFUYWE-AEMXJAC": {
+              "label": "Pictures from Joe",
+              "time": "2020-03-18T11:43:07+01:00"
+            }
+          }
+        },
+        "UYGDMA4-TPHOFO5-2VQYDCC-7CWX7XW-INZINQT-LE4B42N-4JUZTSM-IWCSXA4": {
+          "introducedBy": {
+            "AIBAEAQ-CAIBAEC-AQCAIBA-EAQCAIA-BAEAQCA-IBAEAQC-CAIBAEA-QCAIBA7": {
+              "label": "Family pics",
+              "time": "2020-11-22T14:56:00+01:00"
+            },
+            "YZJBJFX-RDBL7WY-6ZGKJ2D-4MJB4E7-ZATSDUY-LD6Y3L3-MLFUYWE-AEMXJAC": {
+              "label": "Family pics",
+              "time": "2020-03-18T11:43:07+01:00"
+            }
+          }
+        }
+      }
+    }
diff --git a/specs/bep-v1.rst b/specs/bep-v1.rst
@@ -213,6 +213,8 @@ protocol buffer message just as in the uncompressed case.
 Message Subtypes
 ----------------
 
+.. _clusterconfig:
+
 Cluster Config
 ^^^^^^^^^^^^^^