Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sessions): say engineLoaded counts a live peer claim

Yudhi Armyndharis76a850ff4881
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 45f5e501a..635fca69a 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -243,7 +243,7 @@ List all sessions, scoped to the API key's `allowedSessions`, ordered `createdAt
`code` is the engine's own token for the cause, passed through verbatim (`TOS_BLOCK`, `BIZ_QUALITY`, `WEB_COMPANION_ONLY`, …), so a value newer than your gateway build still reaches you rather than being flattened. Because `tos_block`/`proxy_block` prevent the session from linking at all, neither can appear alongside a `ready` status; a `reachout_timelock` can, and usually does. Like `engineLoaded`, the field is derived from live engine state, never persisted, and re-established on the next connect. Changes are also delivered as the `session.restriction` webhook.
-`engineLoaded` reports whether the gateway holds a live engine for the session at the moment of the response. It is the precondition the lifecycle routes enforce, and **`status` is not a substitute for it**: `disconnected` covers both a session whose engine is still registered while an automatic reconnect backs off — where `POST /start` answers `400` — and one stopped through `POST /stop`, which has no engine and does need a start. When `engineLoaded` is `true`, `stop`, `logout` and `force-kill` can act; when it is `false`, `start` is the applicable route. The field is derived per request from live process state, so it is never persisted and never appears in historical/exported data.
+`engineLoaded` reports whether a node of the gateway holds a live engine for the session at the moment of the response: the process that answered, or, in a multi-node deployment, the node with a live claim on the session. It is the precondition the lifecycle routes enforce, and **`status` is not a substitute for it**: `disconnected` covers both a session whose engine is still registered while an automatic reconnect backs off — where `POST /start` answers `400` — and one stopped through `POST /stop`, which has no engine and does need a start. When `engineLoaded` is `true`, `stop`, `logout` and `force-kill` can act; when it is `false`, `start` is the applicable route. The field is derived per request from live state (this process's engines and the other nodes' session claims), so it is never persisted and never appears in historical/exported data.
**Errors:** `400` empty or repeated `name` · `401` missing/invalid `X-API-Key`
diff --git a/docs/13-horizontal-scaling.md b/docs/13-horizontal-scaling.md
index 0ec8225ca..96ff7f520 100644
--- a/docs/13-horizontal-scaling.md
+++ b/docs/13-horizontal-scaling.md
@@ -60,6 +60,14 @@
> which is exactly how a takeover begins. Without `NODE_URL` the whole path is inert and
> single-node deployments pay nothing.
>
+> **List and stats routes answer from the node that received them.** `GET /api/sessions` and
+> `GET /api/sessions/stats/overview` name no session, so they are never forwarded. `lastError`,
+> `restriction`, the stats `active` count and `memoryUsage` are that node's own view, not the owner's:
+> the first two come from what this node's engines recorded, `active` counts only this node's engines,
+> and `memoryUsage` is this process's. `engineLoaded` is the exception, since it also counts a live
+> claim by another node. With routing on, `GET /api/sessions/:sessionId` is forwarded to the owner, so
+> its answer is the owner's.
+>
> **A failed forward says whether the owner could have acted.** When the owner cannot be
> reached at all (connection refused, unresolvable or unusable `NODE_URL`), the answer is
> `503` and the request was not carried out, so it is safe to retry. A timeout answers `504`