POST /action — Execute a Typed Action on an Application - NSP

POST /action dispatches a typed action to a tracked application through its runtime probe. You can execute any action that appears in the actions map of a SubstrateState snapshot — from sending an email reply to archiving a message to clicking a UI element via CDP. Before dispatching, the endpoint enforces safety gates that block irreversible actions without a verify_expression, and after dispatching it optionally polls the updated state to confirm the action had its intended effect.

The /action endpoint has a 120-second timeout, separate from the standard 30-second timeout applied to all other endpoints. This extended window accommodates cold probe attachment, CDP command execution, post-action state settlement, and verification polling.

Endpoint

POST /substrate/v1/action
X-Substrate-Key: <key>
Content-Type: application/json

Request Body

Supply either pid or app_id — the daemon resolves the other automatically. Providing both is also valid and the daemon will confirm they refer to the same process.

{
  "pid": 12847,
  "app_id": "gmail-chrome-12847",
  "action": "send_reply",
  "parameters": {
    "thread_id": "thread_7af2b3",
    "body": "Thanks for the report. I'll review it today."
  },
  "verify_expression": "inbox.sent_count > 0",
  "verify_timeout_ms": 5000,
  "fresh_state": false
}

integer

Target process ID. Either pid or app_id must be present.

string

Target application ID. Either pid or app_id must be present. Prefer app_id for robustness across process restarts.

string

required

Name of the action to execute. Must match a key in the actions map returned by GET /state/{pid} or GET /schema/{pid}.

object

required

Key-value map of parameters that match the action’s declared schema. Required parameters must be present; optional parameters may be omitted.

string

A JavaScript-style expression evaluated against the post-action state to confirm success. Required for any action with reversibility: "irreversible_write". Must not exceed 2048 bytes.

integer

How long to poll for the verify_expression to evaluate to true, in milliseconds. Accepts values from 100 to 30000. Defaults to 5000.

boolean

default:"false"

When true, the daemon captures a fresh state snapshot before dispatching the action. Useful when your agent’s view of the application may be stale.

Response

{
  "success": true,
  "action_id": "01j5abc123def456",
  "action": "send_reply",
  "executed": true,
  "runtime": "v8",
  "total_latency_ms": 312,
  "message": "Action executed successfully",
  "verification": {
    "passed": true,
    "expression": "inbox.sent_count > 0",
    "computed_value": true,
    "explanation": "inbox.sent_count changed from 14 to 15",
    "latency_ms": 280,
    "poll_cycles": 2,
    "changed_fields": [
      { "path": "inbox.sent_count", "before": 14, "after": 15 },
      { "path": "inbox.emails[0].is_read", "before": false, "after": true }
    ]
  },
  "updated_state": { "...": "full SubstrateState snapshot" },
  "state_delta": {
    "inbox.sent_count": { "before": 14, "after": 15 }
  },
  "raw_return": null,
  "jvm_invoke_snapshot": null
}

boolean

true when the action ran and any verify_expression passed. false on pre-flight failure or verification failure.

string (UUIDv7)

Unique time-ordered identifier for this execution. Use it for audit logs and idempotency checks.

string

The name of the action that was executed.

boolean

true when the action itself was dispatched to the runtime. May be false when a pre-flight safety gate rejected the request before dispatch.

string

The runtime path used for execution, for example "v8" or "clr".

integer

Total wall time from request receipt to response, in milliseconds.

string

Human-readable status message.

VerificationOutcome | null

Post-action verification result. null when no verify_expression was provided.

Show VerificationOutcome fields

boolean

true when the expression evaluated to a truthy value within verify_timeout_ms.

string

The expression that was evaluated.

any

The value the expression resolved to.

string

Human-readable summary of what changed to cause the expression to pass or fail.

integer

Time spent polling for the verification result, in milliseconds.

integer

Number of probe cycles run during the verification polling window.

array

Array of { path, before, after } objects listing every state field that changed during verification.

SubstrateState | null

Full state snapshot captured after the action completed. null when post-action state capture was skipped.

object | null

Compact before/after diff of the fields that changed as a result of the action.

any | null

Raw return value from the underlying function invocation. Populated for JVM and CLR method calls; null for CDP and V8 actions.

object | null

Snapshot of the JVM invocation context captured at dispatch time. Populated only for JVM method-level actions; null for all other runtimes and action types.

CDP Builtin Actions

For V8 applications, NSP exposes CDP built-in actions that map directly to Chrome DevTools Protocol commands. These are always available regardless of what the probe discovered.

Action Name	CDP Command	Parameters	Description
`click`	`Input.dispatchMouseEvent`	`x`, `y`	Click at pixel coordinates
`type`	`Input.dispatchKeyEvent`	`text`	Type text into the focused element
`navigate`	`Page.navigate`	`url`	Navigate the page to a URL
`clear`	`DOM.focus` + select-all + delete	`selector`	Clear the contents of an input
`focus`	`Runtime.evaluate`	`selector`	Focus a DOM element by CSS selector
`scroll`	`Input.dispatchMouseEvent`	`x`, `y`, `deltaY`	Scroll at a position

// Click at pixel coordinates (847, 392)
{
  "app_id": "gmail-chrome-12847",
  "action": "click",
  "parameters": { "x": 847, "y": 392 }
}

// Navigate to a URL
{
  "app_id": "gmail-chrome-12847",
  "action": "navigate",
  "parameters": { "url": "https://mail.google.com/mail/u/0/#starred" }
}

Action Safety Gates

The daemon enforces three safety gates before dispatching any action. A gate failure returns a 400 immediately — the action is not executed.

1. Irreversible Write Gate

When an action’s schema carries reversibility: "irreversible_write", a verify_expression is required. This ensures that irreversible side-effects are always paired with a confirmation check.

// ❌ Rejected — send_reply is irreversible_write but no verify_expression supplied
{
  "action": "send_reply",
  "parameters": { "thread_id": "thread_7af2b3", "body": "On my way." }
}

// ✅ Accepted
{
  "action": "send_reply",
  "parameters": { "thread_id": "thread_7af2b3", "body": "On my way." },
  "verify_expression": "inbox.sent_count > 0"
}

2. Dangerous Name Heuristic

If the target PID cannot be resolved and the action name contains any of the following strings, the request is rejected with 400: delete · destroy · purge · wipe · reset · clear_all · terminate · shutdown · kill

3. Expression Size Limit

verify_expression must not exceed 2048 bytes. This limit is configurable in the daemon configuration.

Examples

curl -X POST http://127.0.0.1:7842/substrate/v1/action \
  -H "X-Substrate-Key: nsp_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "gmail-chrome-12847",
    "action": "archive",
    "parameters": { "email_id": "msg_18821af3" }
  }'

curl -X POST http://127.0.0.1:7842/substrate/v1/action \
  -H "X-Substrate-Key: nsp_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pid": 12847,
    "action": "send_reply",
    "parameters": {
      "thread_id": "thread_7af2b3",
      "body": "Thank you for reaching out."
    },
    "verify_expression": "inbox.sent_count > 0",
    "verify_timeout_ms": 5000
  }'

# Simple reversible action
result = await session.execute("archive", parameters={"email_id": "msg_18821af3"})

# Irreversible action with mandatory verification
result = await session.execute(
    "send_reply",
    parameters={"thread_id": "thread_7af2b3", "body": "Thank you."},
    verify=True,
    verify_expression="inbox.sent_count > 0",
)
print(f"Success: {result.success}, verified: {result.verification.passed}")

Error Responses

Status	Code	Description
`400`	`missing_verify_expression`	Action has `irreversible_write` reversibility but no `verify_expression` was provided
`400`	`verify_expression_too_large`	Expression exceeds 2048 bytes
`400`	`dangerous_action_unverified`	Action name matches a dangerous heuristic and PID could not be resolved
`404`	`pid_not_found`	Neither `pid` nor `app_id` resolved to a tracked process
`422`	`verification_failed`	Action ran but the post-action state did not satisfy the `verify_expression`
`429`	`rate_limited`	Exceeded the 10 actions/second rate limit
`503`	`confidence_too_low`	Current state confidence is below the threshold required to dispatch actions

Endpoints

Data Models

POST /action — Execute a Typed Action on an Application

Endpoint

Request Body

Response

CDP Builtin Actions

Action Safety Gates

1. Irreversible Write Gate

2. Dangerous Name Heuristic

3. Expression Size Limit

Examples

Error Responses

​Endpoint

​Request Body

​Response

​CDP Builtin Actions

​Action Safety Gates

​1. Irreversible Write Gate

​2. Dangerous Name Heuristic

​3. Expression Size Limit

​Examples

​Error Responses

Endpoint

Request Body

Response

CDP Builtin Actions

Action Safety Gates

1. Irreversible Write Gate

2. Dangerous Name Heuristic

3. Expression Size Limit

Examples

Error Responses