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

# state-verify

> POST /state/verify — validates that live state matches assumed state before a write executes. Returns status, decision, and any detected mismatches.

Call this endpoint before executing a write that depends on previously resolved state. Invoke compares your assumed state against current live state and returns a decision — proceed, block, or replan.

## Endpoint

```text theme={null}
POST https://api.invokehq.run/state/verify
```

## Authentication

```bash theme={null}
-H "X-API-Key: your_api_key"
```

## Request body

```json theme={null}
{
  "intent": "crm_update_customer",
  "required_fields": ["customer_id", "account_status"],
  "assumed_state": { "customer_id": "cust_123", "account_status": "qualified" },
  "current_state": { "customer_id": "cust_123", "account_status": "qualified" },
  "conditions": { "customer_id": "cust_123" },
  "on_mismatch": "replan"
}
```

### Fields

| Field             | Type      | Required | Description                                              |
| ----------------- | --------- | -------- | -------------------------------------------------------- |
| `intent`          | string    | Yes      | Human-readable label for the action                      |
| `required_fields` | string\[] | Yes      | Fields that must match between assumed and current state |
| `assumed_state`   | object    | Yes      | State the agent resolved at plan time                    |
| `current_state`   | object    | Yes      | Live state fetched immediately before the call           |
| `conditions`      | object    | Yes      | Field values that must hold for the write to proceed     |
| `on_mismatch`     | string    | Yes      | `"replan"` or `"block"`                                  |

## Response

```json theme={null}
{
  "status": "verified",
  "decision": "proceed",
  "mismatches": []
}
```

### When state has drifted

```json theme={null}
{
  "status": "mismatch_detected",
  "decision": "replan",
  "mismatches": [
    {
      "field": "customer_id",
      "assumed": "cust_123",
      "current": "cust_999"
    }
  ]
}
```

### Decision values

| Decision  | Meaning                                                  |
| --------- | -------------------------------------------------------- |
| `proceed` | State matches, write is safe to execute                  |
| `replan`  | State drifted, agent should re-resolve before proceeding |
| `block`   | State drifted and `on_mismatch` is `"block"`             |

## Full example

```bash theme={null}
curl -X POST https://api.invokehq.run/state/verify \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "crm_update_customer",
    "required_fields": ["customer_id", "account_status"],
    "assumed_state": { "customer_id": "cust_123", "account_status": "qualified" },
    "current_state": { "customer_id": "cust_999", "account_status": "qualified" },
    "conditions": { "customer_id": "cust_123" },
    "on_mismatch": "replan"
  }'
```

## Next steps

* [POST /outcomes/reconcile](/api/outcomes-reconcile) — handle unknown outcomes
* [CRM Updates guide](/guides/crm-updates) — state verification in practice
* [TypeScript SDK](/sdk/typescript) — use via `invoke.call()`