GET /schema/{pid} — Fetch Action Schema for a Process - NSP

GET /schema/{pid} returns only the actions map from a process’s SubstrateState — without the full objects snapshot or probe metadata. Use this endpoint when your agent needs to discover what actions are available for an application, inspect parameter types and reversibility, or build a prompt for a planning step, without paying the cost of a full state read. When you need both state and actions, use GET /state/{pid} instead.

Endpoint

GET /substrate/v1/schema/{pid}
X-Substrate-Key: <key>

integer

required

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

Response

{
  "pid": 12847,
  "app_id": "gmail-chrome-12847",
  "app_name": "Gmail",
  "schema_version": "1.4.2",
  "actions": {
    "send_reply": {
      "signature": "fn(thread_id: string, body: string, cc?: string[]) -> bool",
      "reversibility": "irreversible_write",
      "description": "Send a reply to an email thread",
      "confidence": 0.99,
      "parameters": [
        { "name": "thread_id", "type_name": "string", "required": true },
        { "name": "body", "type_name": "string", "required": true },
        { "name": "cc", "type_name": "array", "required": false }
      ]
    },
    "archive": {
      "signature": "fn(email_id: string) -> bool",
      "reversibility": "reversible_write",
      "description": "Move an email to the archive",
      "confidence": 0.99,
      "parameters": [
        { "name": "email_id", "type_name": "string", "required": true }
      ]
    }
  }
}

integer

OS process ID of the queried application.

string

Stable semantic identifier for the application.

string

Human-readable application name.

string

Semantic version of the current action schema (semver). Use this value when submitting corrections via POST /learn/{pid}.

object

Map of action names to their typed schemas. Each entry describes how to call the action.

Show Action schema entry fields

string

Human-readable function signature, for example "fn(thread_id: string, body: string, cc?: string[]) -> bool".

string

Reversibility classification. One of: reversible_write, irreversible_write, read_only. Actions with irreversible_write require a verify_expression in POST /action.

string

Plain-language description of what the action does.

float

Probe confidence that this action binding is correct, from 0.0 to 1.0.

array

Ordered list of parameter descriptors. Each item contains name (string), type_name (string), and required (boolean).

Examples

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

# Iterate over available actions on an attached session
for name, schema in session.actions.items():
    print(f"{name}: {schema.signature}")
    print(f"  Reversibility: {schema.reversibility}")
    print(f"  Required params: {[p.name for p in schema.required_params]}")

When to Use `/schema` vs `/state`

Use case	Recommended endpoint
Discover available actions before planning	`GET /schema/{pid}`
Read current state values to inform a decision	`GET /state/{pid}`
Render a full application snapshot for an LLM	`GET /state/{pid}`
Check parameter types before dispatching	`GET /schema/{pid}`
High-frequency polling loop	`GET /schema/{pid}` (lighter payload)

/schema returns a significantly smaller payload than /state because it omits the objects map, which can contain hundreds of dot-notation keys for complex applications.

Error Responses

Status	Code	Description
`401`	`unauthorized`	Missing or invalid `X-Substrate-Key` header.
`404`	`not_found`	The specified PID is not tracked by the daemon.
`429`	`rate_limited`	Exceeded the 100 requests/second rate limit.
`503`	`probe_not_ready`	The cold probe for this process has not yet completed a cycle.

Endpoints

Data Models

GET /schema/{pid} — Fetch Action Schema for a Process

Endpoint

Response

Examples

When to Use `/schema` vs `/state`

Error Responses

​Endpoint

​Response

​Examples

​When to Use /schema vs /state

​Error Responses

Endpoint

Response

Examples

When to Use `/schema` vs `/state`

Error Responses