> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nelieo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ActionRequest: POST /action Request Body Reference

> Reference for the ActionRequest body sent to POST /action — target process, action name, parameters, and verification fields explained in full.

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.

<ParamField body="pid" type="integer" required>
  The OS process ID of the target application. You can obtain this from [`AppSummary.pid`](/models/app-summary) or [`SubstrateState.pid`](/models/substrate-state). 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.
</ParamField>

<ParamField body="action_name" type="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`.
</ParamField>

<ParamField body="parameters" type="object" required>
  A JSON object whose keys are parameter names and whose values match the types declared in the corresponding [`ActionSchema.parameters`](/models/action-schema) 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.

  ```json theme={null}
  {
    "thread_id": "thread_7af2b3",
    "body": "Thank you for your message.",
    "cc": ["manager@example.com"]
  }
  ```
</ParamField>

<ParamField body="verify" type="boolean" default="false">
  When `true`, NSP polls the post-action substrate state and evaluates `verify_expression` against it, returning a [`VerificationResult`](/models/verification) inside the [`ActionResponse`](/models/action-response). 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.
</ParamField>

<ParamField body="verify_expression" type="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:

  ```
  inbox.sent_count > 0
  inbox.emails[0].is_read == true
  flight.mode == 'GUIDED'
  ```

  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.
</ParamField>

***

## JSON Examples

**Reversible action — no verification required:**

```json theme={null}
{
  "pid": 12847,
  "action_name": "archive",
  "parameters": {
    "email_id": "msg_18821af3"
  },
  "verify": false
}
```

**Irreversible action — verification required:**

```json theme={null}
{
  "pid": 12847,
  "action_name": "send_reply",
  "parameters": {
    "thread_id": "thread_7af2b3",
    "body": "Thank you for your message.",
    "cc": ["manager@example.com"]
  },
  "verify": true,
  "verify_expression": "inbox.sent_count > 0"
}
```

**Read action — no parameters, no verification needed:**

```json theme={null}
{
  "pid": 12847,
  "action_name": "get_thread",
  "parameters": {
    "thread_id": "thread_7af2b3"
  },
  "verify": false
}
```

***

## `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:

```json theme={null}
{
  "error": "NSPIrreversibleNotConfirmedError",
  "message": "Action 'send_reply' has reversibility 'irreversible_write' and requires a verify_expression. Set verify=true and supply a verify_expression before dispatching.",
  "action_name": "send_reply",
  "reversibility": "irreversible_write"
}
```

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.