GET /substrate/v1/diff/{pid} — state diff since capture - NSP

The /diff endpoint returns a field-level comparison between two consecutive state snapshots for a tracked process. Rather than fetching the entire objects map and diffing it yourself, you provide a capture_id from a previous snapshot and the daemon returns only the keys that changed. This is the most efficient way to understand what an action did, why a /watch event fired, or how a process’s state evolved over a time interval.

Endpoint

GET /substrate/v1/diff/{pid}?since={capture_id}
X-Substrate-Key: <key>

Rate limit: 100 requests per second.

Parameters

pid

integer

required

The OS process ID of the target application. Obtain this from GET /apps.

since

string

required

A capture_id (UUIDv7) from a previous GET /state response or a StateChangeNotification message from WS /watch. The diff is computed between this capture and the most recent successful capture.

Response Fields

pid

integer

required

The OS process ID that was queried.

app_id

string

required

Stable semantic identifier for the application.

capture_id

string

required

UUIDv7 of the most recent (current) state snapshot — the “after” side of the diff.

prev_capture_id

string

required

UUIDv7 of the earlier snapshot — the “before” side of the diff. This matches the since query parameter you passed.

changed

array

required

Array of fields that existed in both snapshots but whose values differ. Each entry is a { path, before, after } object.

Show changed entry fields

path

string

Dot-notation key of the changed field, e.g. "inbox.unread_count".

before

any

The field’s value in the earlier snapshot.

after

any

The field’s value in the current snapshot.

added

array

required

Array of { path, value } objects for keys that are present in the current snapshot but were absent in the earlier one. This happens when a new application view loads and exposes state that wasn’t visible before.

removed

array

required

Array of { path, value } objects for keys that existed in the earlier snapshot but are absent in the current one. This happens when the user navigates away from a view or the application unloads a data structure.

Examples

# Step 1: Capture a baseline state and save its capture_id.
CAPTURE_ID=$(curl -s \
  -H "X-Substrate-Key: sk_nsp_..." \
  http://127.0.0.1:7842/substrate/v1/state/12847 \
  | jq -r '.capture_id')

# Step 2: Execute an action or wait for a change.
# Step 3: Fetch the diff since the baseline.
curl -H "X-Substrate-Key: sk_nsp_..." \
     "http://127.0.0.1:7842/substrate/v1/diff/12847?since=${CAPTURE_ID}"

from nelieo import NspClient

client = NspClient(api_key="sk_nsp_...", base_url="http://127.0.0.1:7842")
session = await client.attach("Gmail")

# Capture the pre-action state.
before = await session.refresh()
baseline_id = before.capture_id

# Execute the action.
await session.execute("mark_as_read", parameters={"email_id": "msg_18821af3"})

# Diff what changed.
diff = await session.diff(since=baseline_id)

for change in diff.changed:
    print(f"Changed  {change.path}: {change.before!r} → {change.after!r}")

for entry in diff.added:
    print(f"Added    {entry['path']}: {entry['value']!r}")

for entry in diff.removed:
    print(f"Removed  {entry['path']}: {entry['value']!r}")

Example Response

{
  "pid": 12847,
  "app_id": "gmail-chrome-12847",
  "capture_id": "0196f4a3-1c2d-7e00-9f3a-0b1c2d3e4f50",
  "prev_capture_id": "0196f4a2-3b5c-7d00-8e1f-9a0b2c3d4e5f",
  "changed": [
    {
      "path": "inbox.unread_count",
      "before": 48,
      "after": 47
    },
    {
      "path": "inbox.emails[0].is_read",
      "before": false,
      "after": true
    }
  ],
  "added": [],
  "removed": []
}

Common Patterns

Verifying an action had the expected effect — Call GET /state before dispatching an action to save capture_id, run the action, then call /diff?since=<capture_id> to confirm exactly which fields changed. Processing /watch events efficiently — When a StateChangeNotification arrives, the prev_capture_id field is already included. Pass it to /diff to get the full before/after values without re-reading the whole state. Auditing state over time — Chain consecutive capture_id values to reconstruct a complete audit trail of field-level changes across multiple probe cycles.

Notes

Returns { "changed": [], "added": [], "removed": [] } if state has not changed between the two captures.
Returns 404 if the since capture ID is no longer in the daemon’s capture history window. The daemon retains a fixed number of recent captures per PID; if the requested capture has been evicted, re-capture a fresh baseline via GET /state.
The since parameter must correspond to a capture of the same PID. Cross-PID diff lookups return 400 Bad Request.

Endpoints

Data Models

GET /substrate/v1/diff/{pid} — state diff since capture

Endpoint

Parameters

Response Fields

Examples

Example Response

Common Patterns

Notes

​Endpoint

​Parameters

​Response Fields

​Examples

​Example Response

​Common Patterns

​Notes

Endpoint

Parameters

Response Fields

Examples

Example Response

Common Patterns

Notes