GET /apps — List All Currently Tracked Applications - NSP

Call GET /apps to retrieve a summary of every process the NSP daemon is currently tracking. The response includes probe health, confidence scores, object and action counts, and — for browser and Electron applications — the current URL and semantic view name. The daemon updates this list continuously as processes start and stop, so you can poll this endpoint to discover newly launched applications without restarting your agent.

Endpoint

GET /substrate/v1/apps
X-Substrate-Key: <key>

Response

{
  "total": 2,
  "apps": [
    {
      "pid": 12847,
      "app_id": "gmail-chrome-12847",
      "app_name": "Gmail",
      "runtime": "v8",
      "runtime_name": "JavaScript (V8)",
      "probe_status": "active",
      "confidence": 0.97,
      "object_count": 23,
      "action_count": 5,
      "last_captured_at": "2026-07-20T13:00:00Z",
      "has_state": true,
      "current_view": "gmail_inbox",
      "current_url": "https://mail.google.com/mail/u/0/#inbox"
    },
    {
      "pid": 4521,
      "app_id": "mission-planner-4521",
      "app_name": "Mission Planner",
      "runtime": "clr",
      "runtime_name": ".NET CLR",
      "probe_status": "active",
      "confidence": 0.95,
      "object_count": 47,
      "action_count": 12,
      "last_captured_at": "2026-07-20T13:00:01Z",
      "has_state": true,
      "current_view": null,
      "current_url": null
    }
  ]
}

integer

Total number of tracked applications in the response.

AppSummary[]

Array of application summary objects, one per tracked process.

Show AppSummary fields

integer

OS process ID. Use this value as the {pid} path parameter in all other endpoints.

string

Stable semantic identifier that survives daemon restarts, for example "gmail-chrome-12847". Prefer app_id over pid when targeting actions, as PIDs can change across sessions.

string

Human-readable application name, for example "Gmail" or "Mission Planner".

string

Runtime kind. One of: v8, jvm, clr, native, unknown.

string

Human-readable runtime label, for example "JavaScript (V8)" or ".NET CLR".

string

Current probe lifecycle state. Possible values:

Value	Meaning
`detecting`	Daemon is identifying the runtime
`attaching`	Daemon is attaching the probe to the process
`cold_probe`	First-ever probe cycle in progress
`active`	Probe is running and state is available
`error`	Last probe attempt failed; daemon will retry automatically
`detached`	Process has exited or was detached

float

State quality score from 0.0 to 1.0. Higher is better. Scores below 0.5 indicate noisy or incomplete labeling.

integer

Number of SSF state objects extracted from the last probe cycle.

integer

Number of typed actions currently available for this application.

datetime

ISO 8601 timestamp of the most recent state snapshot.

boolean

true when a state snapshot is available. false when the cold probe is still in progress — call GET /state/{pid} with fresh=true to wait for the first capture.

string | null

Semantic view name for V8 (browser/Electron) applications, for example "gmail_inbox". null for native and CLR applications.

string | null

Current URL for browser and Electron applications. null for native runtimes.

Examples

curl -H "X-Substrate-Key: nsp_live_sk_..." \
     http://127.0.0.1:7842/substrate/v1/apps

apps = await client.list_apps()

for app in apps:
    print(f"{app.app_name:25s}  {app.runtime:6s}  conf={app.confidence:.2f}  "
          f"objects={app.object_count}  status={app.probe_status}")

const res = await fetch("http://127.0.0.1:7842/substrate/v1/apps", {
  headers: { "X-Substrate-Key": "nsp_live_sk_..." }
});
const { apps } = await res.json();

for (const app of apps) {
  console.log(`${app.app_name} — status: ${app.probe_status}, confidence: ${app.confidence}`);
}

Notes

This endpoint returns cached data and does not trigger new probe cycles. Use GET /state/{pid}?fresh=true if you need a guaranteed up-to-date snapshot.
Apps with has_state: false have been discovered but their cold probe is still running. They will become available shortly.
A probe_status of "error" means the last probe attempt failed. The daemon retries automatically — no action required from your agent.

Error Responses

Status	Code	Description
`401`	`unauthorized`	Missing or invalid `X-Substrate-Key` header.
`429`	`rate_limited`	Exceeded the 100 requests/second rate limit.
`503`	`daemon_overloaded`	The daemon is overloaded and cannot serve the request. Retry after a short delay.

Endpoints

Data Models

GET /apps — List All Currently Tracked Applications

Endpoint

Response

Examples

Notes

Error Responses

​Endpoint

​Response

​Examples

​Notes

​Error Responses

Endpoint

Response

Examples

Notes

Error Responses