WS /watch/{pid} — Subscribe to Real-Time State Changes - NSP

WS /watch/{pid} gives your agent a live feed of state changes without polling. After you establish the WebSocket connection, the daemon sends a JSON notification every time a probe cycle detects that one or more state keys have changed. The message tells you which keys changed and at what timestamp — your agent can then call GET /state/{pid} or GET /diff/{pid} to read the new values. This pattern is far more efficient than polling /state in a tight loop.

Endpoint

ws://127.0.0.1:7842/substrate/v1/watch/{pid}?key=<api_key>

Path Parameters

Parameter	Type	Description
`pid`	integer	OS process ID of the application to watch. Obtain from `GET /apps`.

Authentication

Pass your API key as the key query parameter. WebSocket clients do not reliably support custom HTTP headers during the upgrade handshake, so the query parameter approach is required.

ws://127.0.0.1:7842/substrate/v1/watch/12847?key=nsp_live_sk_...

Message Format

The server sends a JSON object for each state change event. Your client receives these messages asynchronously as the daemon completes probe cycles.

{
  "pid": 12847,
  "app_id": "gmail-chrome-12847",
  "sequence": 142,
  "changed_keys": [
    "inbox.unread_count",
    "inbox.emails[0].is_read"
  ],
  "captured_at": "2026-07-20T13:00:00.123Z"
}

integer

OS process ID of the application that changed.

string

Stable semantic identifier for the application.

integer

Monotonically increasing counter for change events on this connection. If you observe a gap in sequence numbers, events were dropped or the connection was briefly interrupted.

string[]

Dot-notation state keys whose values changed since the previous probe cycle, for example "inbox.unread_count" or "inbox.emails[0].is_read".

datetime

ISO 8601 timestamp (with millisecond precision) of the probe cycle that detected the change.

Behavior

The daemon fires a notification on every probe cycle that detects at least one changed key. Cycles with no changes produce no message.
The default probe interval is 2 seconds. Your agent should not assume a specific cadence — intervals can vary based on application activity.
When the tracked process exits, the daemon closes the WebSocket with close code 1000 (normal closure).
If the daemon itself restarts, the connection is dropped without a close frame. Your client should detect this and reconnect.
There is no heartbeat or server-side ping. If you need to detect stale connections, implement a client-side ping or timeout.

Examples

const ws = new WebSocket(
  `ws://127.0.0.1:7842/substrate/v1/watch/12847?key=nsp_live_sk_...`
);

ws.onmessage = (msg) => {
  const event = JSON.parse(msg.data);
  console.log("Changed keys:", event.changed_keys);
  console.log("Sequence:", event.sequence);
  console.log("Captured at:", event.captured_at);
};

ws.onclose = (e) => {
  console.log("Stream closed:", e.code, e.reason);
  // Implement exponential back-off reconnect logic here
};

ws.onerror = (err) => {
  console.error("WebSocket error:", err);
};

# Via session (recommended — automatically resolves pid from app name)
async with session.watch() as stream:
    async for event in stream:
        print(event.changed_keys, event.sequence)

# Via client (raw — supply pid directly)
async with client.watch(pid=12847) as stream:
    async for event in stream:
        print(event.changed_keys)

Error Responses (HTTP Upgrade Phase)

These errors occur during the initial HTTP-to-WebSocket upgrade request, before the connection is established.

Status	Description
`401`	Missing or invalid `key` query parameter
`404`	The specified PID is not tracked by the daemon
`426`	Upgrade Required — the request was made over plain HTTP instead of WebSocket

Endpoints

Data Models

WS /watch/{pid} — Subscribe to Real-Time State Changes

Endpoint

Path Parameters

Authentication

Message Format

Behavior

Examples

Error Responses (HTTP Upgrade Phase)

​Endpoint

​Path Parameters

​Authentication

​Message Format

​Behavior

​Examples

​Error Responses (HTTP Upgrade Phase)

Endpoint

Path Parameters

Authentication

Message Format

Behavior

Examples

Error Responses (HTTP Upgrade Phase)