POST /verify — Evaluate a State Expression Standalone - NSP

POST /verify lets you evaluate a state predicate against a tracked application outside of an action dispatch. Use it to perform pre-flight checks before your agent commits to an irreversible action, to assert that a precondition holds before a multi-step sequence, or to build custom verification logic in your own agent loop. The endpoint polls the state until the expression becomes true or the timeout_ms window expires, so you do not need to implement your own polling retry logic.

Endpoint

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

Request Body

{
  "pid": 12847,
  "expression": "inbox.unread_count < 10 && inbox.emails[0].is_read == true",
  "timeout_ms": 5000
}

integer

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

string

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

string

required

JavaScript-style predicate to evaluate against the current objects map. Must not exceed 2048 bytes. See the supported syntax table below.

integer

How long to poll until the expression becomes truthy, in milliseconds. Accepts values from 100 to 30000. Defaults to 5000. The request returns early as soon as the expression passes.

Response

{
  "passed": true,
  "expression": "inbox.unread_count < 10 && inbox.emails[0].is_read == true",
  "computed_value": true,
  "explanation": "Expression evaluated to true after 1 poll cycle",
  "latency_ms": 52,
  "poll_cycles": 1,
  "changed_fields": []
}

boolean

true when the expression evaluated to a truthy value within timeout_ms. false if the timeout elapsed without the expression passing.

string

The expression that was evaluated, echoed back for traceability.

any

The final value the expression resolved to. For boolean predicates this is true or false.

string

Human-readable summary of the evaluation outcome, for example which field changed to satisfy the expression.

integer

Total time spent polling, in milliseconds.

integer

Number of probe cycles completed during the polling window.

array

Array of { path, before, after } objects for any state fields that changed during the polling window. Empty when the expression passed on the first cycle.

Supported Expression Syntax

Expressions are JavaScript-like predicates evaluated against the flat objects map returned by GET /state/{pid}. The following operators and patterns are supported:

Syntax	Example
Equality (`==`)	`inbox.emails[0].is_read == true`
Inequality (`!=`)	`inbox.emails[0].id != "msg_18821af3"`
Greater than (`>`)	`flight.altitude_m > 45.0`
Less than (`<`)	`inbox.unread_count < 10`
Logical AND (`&&`)	`flight.is_armed == true && flight.mode == "GUIDED"`
Logical OR (`\|\|`)	`status == "sent" \|\| status == "delivered"`
Negation (`!`)	`!inbox.emails[0].is_read`
String contains (`.includes()`)	`context.url.includes("inbox")`
Existence check	`inbox.unread_count > 0`

// Equality
"inbox.emails[0].is_read == true"

// Numeric comparison
"inbox.unread_count < 10"
"flight.altitude_m > 45.0"

// Compound condition
"flight.is_armed == true && flight.mode == 'GUIDED'"

// Negation
"inbox.emails[0].id != 'msg_18821af3'"

// Existence check
"inbox.unread_count > 0"

// String method
"context.url.includes('inbox')"

Examples

curl -X POST http://127.0.0.1:7842/substrate/v1/verify \
  -H "X-Substrate-Key: nsp_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pid": 12847,
    "expression": "inbox.unread_count > 0",
    "timeout_ms": 3000
  }'

# Pre-flight check before an action
state = await session.refresh()
if state.get_int("inbox.unread_count") > 0:
    # Proceed with the action — unread emails are present
    result = await session.execute(
        "archive",
        parameters={"email_id": state.objects["inbox.emails[0].id"]}
    )

Error Responses

Status	Code	Description
`400`	`bad_request`	Missing required field or malformed expression.
`401`	`unauthorized`	Missing or invalid `X-Substrate-Key` header.
`404`	`not_found`	Neither `pid` nor `app_id` resolved to a tracked process.
`429`	`rate_limited`	Exceeded the 100 requests/second rate limit.

Endpoints

Data Models

POST /verify — Evaluate a State Expression Standalone

Endpoint

Request Body

Response

Supported Expression Syntax

Examples

Error Responses

​Endpoint

​Request Body

​Response

​Supported Expression Syntax

​Examples

​Error Responses

Endpoint

Request Body

Response

Supported Expression Syntax

Examples

Error Responses