Skip to main content
When you invoke an action on a tracked application you send an ActionRequest as the JSON body of POST /action. The request identifies which process to target, names the action to invoke, supplies the typed parameter values the action requires, and optionally specifies a post-action verification expression that NSP evaluates against the updated state to confirm the action succeeded. For irreversible_write actions the verification expression is not optional — omitting it causes NSP to reject the request before any action is dispatched.
​
pid
integer
required
The OS process ID of the target application. You can obtain this from AppSummary.pid or SubstrateState.pid. Because PIDs are recycled when a process exits and a new one starts, you should confirm the PID is still live (for example by checking probe_status: "active" on the corresponding AppSummary) before constructing a request.
​
action_name
string
required
The name of the action to invoke. Must exactly match a key present in SubstrateState.actions for the target process. Action names are case-sensitive. You can enumerate available actions from the actions map in a recent SubstrateState or by calling GET /schema.
​
parameters
object
required
A JSON object whose keys are parameter names and whose values match the types declared in the corresponding ActionSchema.parameters array. You must include every parameter whose required field is true. Optional parameters may be omitted entirely — do not pass null for optional parameters unless the schema explicitly lists null as an allowed value.
​
verify
boolean
default:"false"
When true, NSP polls the post-action substrate state and evaluates verify_expression against it, returning a VerificationResult inside the ActionResponse. When false, NSP dispatches the action and returns immediately without confirming the outcome in state.For irreversible_write actions, setting verify: false raises NSPIrreversibleNotConfirmedError — you cannot skip verification on permanent actions. See the note below.
​
verify_expression
string
A boolean expression evaluated against the post-action objects map to confirm the action had its intended effect. Required whenever verify: true and the action’s reversibility is irreversible_write. Maximum length: 2048 bytes.Expressions reference dot-notation state keys directly:
NSP polls the state repeatedly — up to verify_timeout_ms — and returns as soon as the expression evaluates to true. If the timeout is reached without the expression becoming true, the response carries success: false and an HTTP 422 Unprocessable Entity status.

​
JSON Examples

Reversible action — no verification required:
Irreversible action — verification required:
Read action — no parameters, no verification needed:

​
NSPIrreversibleNotConfirmedError

If you submit a request for an action whose reversibility is irreversible_write and you either omit verify_expression or set verify: false, NSP raises NSPIrreversibleNotConfirmedError and returns HTTP 400 before dispatching anything. This is an intentional hard gate — irreversible actions such as send_reply, delete_permanently, or submit_form require you to explicitly declare what post-action state change you expect. The error message includes the action name and the verify_expression requirement so you can correct the request:
To resolve this, always pass verify: true and a meaningful verify_expression for irreversible actions. Choose an expression that confirms the observable outcome in state — for example inbox.sent_count > 0 after sending an email — rather than a trivially true expression that does not reflect real success.