From 2593edca179e86883e74c7039629564f4ea6ec55 Mon Sep 17 00:00:00 2001
From: tv <tv@krebsco.de>
Date: Tue, 27 Oct 2026 01:34:15 +0100
Subject: admit nodeId and addresses in the API

---
 docs/openapi.yaml | 36 +++++++++++++++++++++++++++---------
 1 file changed, 27 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 3025146..47c7596 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -210,7 +210,7 @@ paths:
       summary: List known peers
       responses:
         '200':
-          description: Peers, by public key.
+          description: Peers, by node ID.
           content:
             application/json:
               schema:
@@ -230,7 +230,7 @@ paths:
         - name: peer
           in: path
           required: true
-          description: The peer's public key.
+          description: The peer's node ID (`continuum:<hex>`).
           schema:
             type: string
         - name: force
@@ -340,7 +340,7 @@ paths:
       description: |
         JSON by default. When `Accept` names `application/openmetrics-text` or
         `text/plain` (as Prometheus does), the Prometheus text format (0.0.4) instead,
-        with per-peer series labelled `peer` (the public key). Aliases are only in
+        with per-peer series labelled `peer` (the node ID). Aliases are only in
         `continuum_info` and `continuum_peer_info`, for joining.
       responses:
         '200':
@@ -1090,10 +1090,15 @@ components:
 
     PeerList:
       type: object
-      required: [localEpoch, localHeads, peers]
+      required: [localAddresses, localEpoch, localHeads, peers]
       properties:
         localAlias:
           type: [string, 'null']
+        localAddresses:
+          type: array
+          items:
+            type: string
+          description: Where this node can be reached, e.g. `mycelium:<public key>`.
         localEpoch:
           $ref: '#/components/schemas/Epoch'
         localHeads:
@@ -1101,17 +1106,24 @@ components:
           description: 'Heads of the local document (more than one: concurrent changes not yet merged).'
         peers:
           type: object
-          description: By public key.
+          description: By node ID.
           additionalProperties:
             $ref: '#/components/schemas/Peer'
 
     Peer:
       type: object
-      required: [status, handshakeComplete, hasPendingDelivery, neighbour, traffic, incidents]
+      required: [addresses, status, handshakeComplete, hasPendingDelivery, neighbour, traffic, incidents]
       properties:
         alias:
           type: [string, 'null']
           description: The name the peer gave itself (`--alias`); not unique.
+        addresses:
+          type: array
+          items:
+            type: string
+          description: |
+            Where this node reaches the peer: the address it proved itself at, else
+            where others say it is.
         validatedSwarm:
           type: [string, 'null']
         status:
@@ -1221,10 +1233,16 @@ components:
 
     Stats:
       type: object
-      required: [publicKey, uptimeSecs, ready, epoch, document, catchUp, remakes, sync, relay, topology, stability, staleHelloReplies, traffic, incidents, propagation, disk]
+      required: [nodeId, addresses, uptimeSecs, ready, epoch, document, catchUp, remakes, sync, relay, topology, stability, staleHelloReplies, traffic, incidents, propagation, disk]
       properties:
-        publicKey:
+        nodeId:
           type: string
+          description: '`continuum:<hex>`, from the node key.'
+        addresses:
+          type: array
+          items:
+            type: string
+          description: Where this node can be reached, e.g. `mycelium:<public key>`.
         alias:
           type: [string, 'null']
         uptimeSecs:
@@ -1600,7 +1618,7 @@ components:
         votes:
           type: object
           description: |
-            Votes for this remake by member public key, from the votes register (only
+            Votes for this remake by member node ID, from the votes register (only
             electorate members count; one that also voted for another remake counts
             for neither).
           additionalProperties:
-- 
cgit v1.3.1