ActionRequest is the JSON body you send to POST /substrate/v1/action to execute a typed action on a tracked application. Every request must identify a target process (by pid or app_id), name the action to run, and supply any required parameters. For actions with reversibility: "irreversible_write", you must also include a verify_expression — a JavaScript-style predicate that the daemon will evaluate against post-action state before returning success. The daemon resolves pid from app_id (and vice versa) automatically, so you only need to supply one.
JSON Example
Fields
integer
The OS process ID of the target application. You must supply either
pid or app_id — providing both is allowed, and the daemon validates that they refer to the same process. Use pid when you obtained the value from a recent GET /apps response. Note that PIDs change if an application restarts; prefer app_id for stable long-running agents.string
The stable semantic identifier for the target application, such as
"gmail-chrome-12847". You must supply either app_id or pid. Unlike pid, app_id is stable across restarts and is the recommended way to target an app in agent code that persists between sessions.string
required
The name of the action to execute. This must match a key in the
actions map of the target application’s SubstrateState, or be one of the built-in CDP actions (click, type, navigate, scroll, focus, clear) for V8 apps. Action names are case-sensitive.object
required
A JSON object whose keys are parameter names and whose values match the types declared in the action’s
parameters array. You must include all parameters marked required: true in the ActionSchema. Optional parameters may be omitted. If a required parameter is missing, the daemon returns 400 without dispatching the action.string
A JavaScript-style boolean expression evaluated against the post-action
SubstrateState.objects map. Required when the action’s reversibility is "irreversible_write"; optional for read and reversible_write actions.The expression is limited to 2048 bytes. It is evaluated by polling post-action state until it returns true or verify_timeout_ms is exceeded. If it never becomes true, the daemon returns 422 verification_failed and the ActionResponse includes a VerificationOutcome with passed: false.integer
How long (in milliseconds) the daemon will poll post-action state waiting for
verify_expression to evaluate to true. Must be between 100 and 30000. Defaults to 5000 (5 seconds). The daemon polls approximately every 500ms, so a 5-second timeout allows up to 10 poll cycles.Choose your timeout based on expected action latency — for example, 1000–2000ms for a simple UI state change, or 8000–30000ms for an API call or file export.boolean
If
true, the daemon captures a fresh state snapshot from the runtime probe before dispatching the action. This ensures the action is dispatched against the most current state rather than a cached snapshot. Defaults to false. Enabling this adds 50–200ms of additional latency before execution begins.