StateSet API Docs

The flagship neuro-symbolic-recursive surface. Instead of generating free text, it returns an auditable decision — approved | denied | refused — with a cited proof chain, a confidence, and a safe refusal when the engine cannot ground the answer well enough to be accountable. This is the use case where a pure LLM is unsafe: it will confidently approve actions that violate policy. The symbolic layer gives deterministic, provenance-traced decisions relative to the supplied facts and rules; the recursive layer handles multi-hop policy (transitive role access, bill-of-materials/recall explosion, chained eligibility); the neural layer reads messy natural-language requests. Every request also runs through the canonical Grounded Symbol System (GSS) and a tenant-scoped NSRMachine. Machine inference is mandatory for verified decisions — if the seed pack is unavailable or inference does not complete, the API fails closed with HTTP 503.

This page reflects NSR v0.9.6. Proof verification, negation and valid-time handling were tightened in v0.9.4 — see Behavior changes in v0.9.4 — and several rule-evaluation semantics were corrected earlier in v0.6.0 and v0.7.0. If you wrote rules or a proof verifier against earlier docs, read both sections.

Endpoints

These thirteen are the decision surface. The engine serves 259 operations in all — knowledge base, rules, NSR-L, machines, flywheel, billing and more — each with a generated reference page and playground under the NSR API tab.

Endpoint	Method	Returns
`/v1/decisions`	POST	`approved \| denied \| refused` plus a cited proof chain, confidence, and safe refusal
`/v1/decisions/batch`	POST	Per-item decisions and a batch summary. Items past the time budget are never evaluated or billed (`batch_deadline_exceeded`)
`/v1/decisions/recent`	GET	Most recent decisions for the org (ephemeral analytics, newest first)
`/v1/decisions/stats`	GET	Windowed aggregates: outcome counts, billable volume, p50/p95 latency, top-cited rules
`/v1/decisions/impact`	POST	Policy impact analysis — replay logged decisions under candidate rules
`/v1/decisions/{id}`	GET	One decision, while it is inside the retained window
`/v1/decisions/{id}/outcome`	POST	Record what actually happened
`/v1/decisions/outcome-by-ref`	POST	The same, keyed by your own correlation id rather than ours
`/v1/decisions/calibration`	GET	The reliability curve — how well confidence predicts the honored rate
`/v1/decisions/rule-stats`	GET	Per-rule firing counts, noisiest first
`/v1/decisions/refusal-gaps`	GET	The premises that most often cause a refusal
`/v1/decisions/refusal-roadmap`	GET	Those gaps ranked as “connect this and N% of them resolve”
`/v1/decisions/export`	GET	JSONL for compliance and SIEM pipelines
`/v1/proofs/verify`	POST	Check a proof without trusting this server

POST /v1/decisions
Authorization: Bearer <NSR_API_KEY>   (or X-API-Key)

Request

{
  "query": "Can order A1 be refunded for customer C?",
  "action": "issue_refund",
  "mode": "safe",
  "facts": [
    { "predicate": { "name": "return_received", "args": ["A1"] }, "confidence": 1.0 }
  ],
  "rules": [
    {
      "name": "refund_if_clean",
      "effect": "permit",
      "if": [
        { "name": "return_received", "args": ["?o"] },
        { "name": "fraud_flagged", "args": ["?o", "?r"], "negated": true }
      ],
      "then": [ { "name": "may_refund", "args": ["?o"] } ]
    }
  ],
  "hydrate_org_context": true,
  "include_trace": false
}

Field	Purpose
`query`	The natural-language request
`action`	Optional — the action being authorized
`mode`	`fast` \| `accurate` \| `safe`. Defaults to `safe`, the most thorough verification, because decisions are accountable outputs
`facts`	Optional request-scoped facts, each with a confidence
`rules`	Optional request-scoped rules
`hydrate_org_context`	Pull the org knowledge base (default `true`)
`include_trace`	Include the full proof trace and raw payload

Rule effects

A rule may declare its policy intent explicitly via effect, which is authoritative over predicate-name conventions — better for tenant-specific or non-English vocabularies.

Effect	Meaning
`permit`	A satisfied rule authorizes the action.
`deny`	A satisfied rule blocks it. Deny wins over permit.
`review`	A satisfied rule routes the decision to human review — `refused` plus `requires_human_review`. The third first-class outcome.

effect: "review" became a first-class declared effect in v0.6.0. Before that it was expressible only via predicate-name inference, and an inline rule declaring it would fail with a 422 “unknown variant”. Review rules are subject-bound in the same way deny rules are.

Negation-as-failure

A condition may set negated: true: the rule fires only when no fact matches the atom. A free variable in the negated atom is a wildcard, so not fraud_flagged(?o, ?r) fails whenever any fraud_flagged(?o, *) exists.

{ "name": "fraud_flagged", "args": ["?o", "?r"], "negated": true }

This field is required for negation to take effect. Before v0.6.0, request-scoped rule conditions carried no negated flag, so a negation was silently dropped and read as a positive condition — inverting the guard. A rule written as may_auto_refund(?o) :- refund_requested(?o), NOT fraud_flagged(?o,?r) would auto-refund exactly the fraud-flagged orders it was written to block.Organization rules on the batch endpoint always honored negation; inline rules — what the MCP nsr_decide tool uses — did not. If you authored inline rules against pre-v0.6.0 docs, audit them.

negated is serde-default and skipped when false, so existing payloads are unchanged.

Outcomes

Outcome	When
refused	A fired cited rule with `effect: "review"` (routing to `requires_human_review`); the GSS safety/escalation gate; or — when no cited policy rule resolves the outcome — engine failure, ungrounded (status ≠ grounded and `proof_score` < 0.34), or grounded-but-ambiguous. The safe default — NSR refuses rather than guesses.
approved	A fired, cited request rule with `effect: "permit"` (or, without a declared effect, a positive conclusion `may_`, `can_`, `authorized`, `approved`, `eligible`, `permitted`) whose ground conclusion binds the request’s subject and action. Otherwise, a grounded result with a `ready` tool call, approved action type, or affirmative answer flag.
denied	A fired, cited rule with `effect: "deny"` (or, without a declared effect, a negative conclusion `denied`, `blocked`, `forbidden`, …) binding the request. Deny wins over permit.

Cited symbolic policy is evaluated after GSS safety gates but before conversational uncertainty and execution-runtime state. This matters when policy authorizes an action but answer composition is ambiguous or live runtime state disagrees.

Response

{
  "decision_id": "dec_…",
  "decision": "approved",
  "confidence": 0.85,
  "rationale": "…",
  "plain_explanation": "Approved to issue a refund for order 9412: the return for order 9412 was received and order 9412 passed inspection.",
  "proof": {
    "cited_rules": ["may_refund"],
    "symbolic_steps": 2,
    "neural_steps": 0,
    "planner_steps": 1,
    "proof_score": 0.9,
    "proof_status": "grounded"
  },
  "grounding": { "status": "grounded", "grounded_entity_count": 3, "cited_rule_count": 1 },
  "gss_machine": {
    "authority": "nsr_machine_gss",
    "seed_source": "embedded",
    "seed_grounded": true,
    "categories": ["returns_exchanges"],
    "domains": ["order"]
  }
}

cited_rules is the audit trail, reduced to the backward dependency path. When the request carried inline policy, the proof also carries a SHA-256 over the canonicalized request-scoped facts and rules, pinning the decision to the exact policy inputs it was evaluated against.

Behavior changes in v0.9.4

Three corrections to how proofs are checked. None changes the request shape; all change what the engine will accept as proven. Proof verification checks entailment, not citation shape. Both the in-process checker and the independent nsr-proof-core verifier now unify every cited fact with the atom the rule actually needs, replay rule heads and bodies, evaluate builtins, reject relabelled builtins, and fail closed on uncertified negation. Before this, a real but unrelated fact could be cited in support of an arbitrary goal and pass. Backward chaining also gives each rule invocation a fresh variable namespace, so sibling branches cannot contaminate one another’s substitutions. Negation proofs are complete for finite stratified Datalog. An empty negation-as-failure trace no longer fails merely because some rule defines the predicate. Both proof kernels recompute the bundle’s perfect model and accept absence only when the ground atom is outside it. Negative cycles, function-generating programs, non-ground negation, and closure resource exhaustion all fail closed. Valid-time is enforced during inference. A live evaluation captures one instant and excludes facts that have expired or are not yet valid. Historical reasoning over HTTP and SSE uses the request’s as_of instant, so a past snapshot is no longer filtered against today’s clock.

If you run the offline verifier, upgrade it alongside the server. A bundle produced by v0.9.4 carries the fact and rule slices the new checker replays; an older verifier will accept proofs the server now rejects.

Behavior changes in v0.6.0 and v0.7.0

Several of these were fail-open correctness bugs. If you built against earlier documentation, the following now behave differently — in every case, more conservatively.

Confidence is capped by the weakest supporting fact (v0.7.0)

Decision confidence was 1.0 - grounding_uncertainty, decoupled from the proof and non-monotonic — a 0.4-confidence fact could yield higher confidence than a 1.0 one. An approval is now capped by its weakest supporting fact:

confidence = min(grounding, weakest request-fact confidence)

This is fail-safe (it only lowers values), monotonic, and a no-op when facts are certain.

Subject and action binding (v0.6.0)

A rule fires for whatever the fact base satisfies, not for what the question asks. Given may_authorize(?p,?act) :- has_authority(?p,?act) and the fact has_authority(ceo_kim, approve_wire), the engine proves may_authorize(ceo_kim, …). The gate previously counted any cited request-scoped effect wholesale, so a wire could be authorized for stranger_sven off the CEO’s authority, or delete_account authorized off refund authority. A single conclusion-head check now covers all effects: the cited rule’s effect only applies when its ground conclusion binds the request’s own subject and action. Two related binding fixes:

Numeric builtins — the binding gate replays a cited rule’s body to reconstruct which subject it fired for, but the replay matcher did not evaluate comparison builtins (leq, geq, lt, …). It returned “can’t tell”, so no mismatch was detected. A rule may_refund(?o) :- order_amount(?o,?v), leq(?v, 500) could approve a refund for an order whose amount did not qualify. The matcher now computes comparison builtins under the binding, exactly as the solver does.
Single-character subject tokens — the subject-binding token match dropped tokens shorter than 2 characters, so ord-9 and ord-4 (sharing ord, differing only in the 1-char suffix) were treated as the same subject. A rule that fired for ord-9 could bind a decision about ord-4. The match now requires every alphanumeric token, single characters included. Phrasing variance (order A1 vs order #A1) still grounds.

Abduction no longer asks for un-suppliable builtins (v0.7.0)

A failed comparison builtin such as leq(850,500) was reported in missing_facts with a resolves_with, telling an agent to “supply leq(850,500)” — impossible. Comparison builtins are now excluded; the actionable ask is the base predicate that binds the value, e.g. amount.

Soundness guarantees

A verdict never authorises something the rules do not. Five invariants hold, each regression-tested, with the full set running against a 1,260-case auto-labelled soundness corpus.

Invariant	What it prevents
Subject binding	A rule that fired for one principal or order cannot authorise a decision about another — even under a shared fact base, a multi-step derivation, or subjects differing by one character (`ord-9` vs `ord-4`)
Action binding	Authority for one action cannot authorise another
Negation is fail-closed	`not fraud_flagged(?o, ?r)` blocks a flagged subject; it never fails open
Numeric builtins are computed	`leq`/`geq`/`lt`/`gt` are evaluated rather than looked up, so a threshold decides correctly and a decoy value for a different subject cannot bind
Deny precedence, refuse by default	A fired deny beats a fired permit; when nothing proves, the outcome is `refused` — never a guess

Confidence is never overconfident. An approval resting on a 0.2-confidence fact reports confidence ≤ 0.2, and the relationship is monotonic — a lower fact confidence never yields a higher decision confidence.

Two limits, stated plainly:

The gate’s outcome logic, the rule engine, and the token matching that produces the gate’s binding signals are all machine-checked in Lean 4, and three differential conformance harnesses bind those models to the shipped code — see Formal Verification. That is not an end-to-end verification of NSR: the neural layer, persistence, billing, and concurrency are out of scope, and the remaining gaps are listed there rather than glossed.
The gate faithfully applies the rules you supply. It cannot judge whether those rules are correct. A permissive rule, faithfully enforced, still authorises what it says to.

Policy impact analysis

Before changing a policy, find out what it would have changed.

POST /v1/decisions/impact

It replays your recent logged decisions through the same outcome gate under current versus candidate rules, and reports every decision whose outcome flips — with the fired rules on both sides.

curl -X POST https://api.nsr.stateset.com/v1/decisions/impact \
  -H "X-API-Key: $NSR_API_KEY" \
  -d '{
    "add_rules": [{
      "name": "legal_hold_blocks_refunds",
      "if":   [{"name": "legal_hold", "args": ["?o"]}],
      "then": [{"name": "refund_blocked", "args": ["?o"]}]
    }],
    "remove_rules": ["grandfathered_discount_policy"],
    "limit": 200
  }'

Property	Behaviour
Dry-run by construction	Nothing is billed, logged, or persisted
Policy-layer counterfactual	The neural solve, grounding, and safety gates are not re-run, so the replay isolates exactly the policy contribution. The response’s `scope` field states this
Candidate rule semantics	Candidates preview stored-rule semantics. One carrying a declared `effect` or multiple conclusions is rejected with 400, because a stored org rule can never have those
Skipped decisions	Those logged without a request snapshot are counted in `skipped_no_snapshot`

This is the answer to “we can’t change the refund policy, we don’t know what it’ll break.” Replay 200 real decisions against the candidate rule and read the flips.

Idempotency

Mutating requests accept an Idempotency-Key header, Stripe-style.

curl -X POST https://api.nsr.stateset.com/v1/decisions \
  -H "X-API-Key: $NSR_API_KEY" \
  -H "Idempotency-Key: order-9412-refund" \
  -d '{"query": "Can order 9412 be refunded?", "action": "issue_refund"}'

A repeat within 24 hours returns the cached response byte-for-byte — not re-executed and not re-billed — with Idempotent-Replayed: true and the original decision, billing, and quota headers preserved. Keys are scoped per org, 1–255 URL-safe characters. 2xx and 4xx are cached; 5xx is not, so retries during an incident still reach a healthy backend.

All four SDKs send a key automatically on decide and decide_batch — a fresh UUID per logical call, reused across the client’s internal retries. You get safe retries without doing anything.

Metering

Each resolved decision is one billable unit. A billable outcome is gated by the org quota, which returns HTTP 402 on exhaustion. usage.outcome_cost_microdollars and usage.billing_tier report the charge, tiered by mode and proof depth. Refusals and cache hits are governed by the same billability policy — so a refusal is not a free way to probe, and a replay is not a second charge.

Verify a proof without trusting us

An approved decision carries a verifiable_bundle: the derivation plus the exact facts and rules it stands on. A proof is only proof-carrying if somebody other than the engine can check it, so the checker is a reachable endpoint. POST the bundle back, verbatim:

curl --request POST "$NSR_API/v1/proofs/verify" \
  --header "Content-Type: application/json" \
  --data @bundle.json

Response

{ "verified": true }

A proof that does not check is still a 200 with a located reason — an unsound proof is a valid answer, not a client error:

Response

{
  "verified": false,
  "reason": "step 3 cites rule refund_window but its premise order.age_days <= 30 is unsupported",
  "failed_step": 3
}

The handler is stateless by design. It reads no tenant state and touches no database; the bundle carries its own org_id, and cross-tenant laundering is rejected inside the checker. That is what makes the answer worth anything — the trusted computing base is the checker and the bundle, not the rest of the server.

You do not have to call us at all. The same check ships as the dependency-light nsr-proof-core crate, so you can verify bundles fully offline — in CI, in an air-gapped audit, or inside your own service. An independently verifiable claim you can only verify by asking the claimant is not independently verifiable.

The outcome loop

Confidence is only meaningful if someone checks it against reality. Record what actually happened to a decision and the engine can tell you how well its own confidence predicts outcomes.

# By decision id
curl --request POST "$NSR_API/v1/decisions/$DECISION_ID/outcome" \
  --header "Authorization: Bearer $NSR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "outcome": "honored" }'

# Or by your own correlation key — the order id you already have
curl --request POST "$NSR_API/v1/decisions/outcome-by-ref" \
  --header "Authorization: Bearer $NSR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "ref": "ORD-10428", "outcome": "reversed" }'

Outcome	Meaning
`honored`	The decision held up
`reversed`	It did not — an approved refund charged back, say
`overridden`	A human changed it
`escalated`	It went to review after the fact

Once outcomes are flowing, the calibration curve is the number that matters:

curl "$NSR_API/v1/decisions/calibration" \
  --header "Authorization: Bearer $NSR_API_KEY"

It buckets approved decisions by reported confidence and reports the real honored rate in each bucket, plus an Expected Calibration Error in [0, 1] where 0 is perfect. That is what lets you set an auto-approve threshold you can defend rather than guess at.

Calibration is computed only over approved decisions that have a recorded outcome. Report outcomes for the ones that went wrong and not the ones that went right and the curve will say the engine is badly calibrated when what is actually skewed is your reporting. Record both, or record neither.

POST /v1/decisions/{id}/outcome returns 404 once a decision has rotated out of the retained window, so report outcomes as they happen rather than batching them weeks later. outcome-by-ref exists so you can do that from the system that learns the outcome, using the id it already holds.

Prove it yourself

A proof harness runs labelled policy cases through the real backward-chaining engine:

cargo run --example verified_decision_harness

# head-to-head against an LLM baseline
NSR_HARNESS_LLM=1 OPENAI_API_KEY=sk-... cargo run --example verified_decision_harness

Measured across commerce, access-control, supply-chain, and lending cases — two of them recursive (transitive role access, multi-level recall/BOM):

Decision accuracy   : 100.0%     
Refusal correctness : 100.0%   ← under-grounded cases refused, not guessed
Proof validity      : 100.0%   ← every approval rests on a real rule→fact chain
Unsafe approvals    : 0        ← the number a pure LLM cannot guarantee

The harness exits non-zero on any unsafe approval or missed floor, so it doubles as a CI gate. Wire it into your pipeline and a policy regression fails the build.

The claim worth testing against your own cases: comparable accuracy, zero unsafe approvals, 100% auditable.

MCP server

The NSR MCP server gained a per-request timeout (NSR_TIMEOUT_MS) so an agent never hangs on a slow endpoint, plus client-side input validation that names the exact malformed rule or field instead of surfacing a cryptic 422 deserialize error.

Verification

NSR ships a verifier-as-oracle evaluation apparatus: a 1,260-case auto-labeled decision-soundness corpus, a deterministic generator, and a runner that checks any live /v1/decisions deployment against the ground-truth labels — plus in-process property-based and generative multi-invariant soundness tests.

Neuro-Symbolic Architecture — the conceptual model
NSR-L — the rule language

​Endpoints

​Request

​Rule effects

​Negation-as-failure

​Outcomes

​Response

​Behavior changes in v0.9.4

​Behavior changes in v0.6.0 and v0.7.0

​Confidence is capped by the weakest supporting fact (v0.7.0)

​Subject and action binding (v0.6.0)

​Abduction no longer asks for un-suppliable builtins (v0.7.0)

​Soundness guarantees

​Policy impact analysis

​Idempotency

​Metering

​Verify a proof without trusting us

​The outcome loop

​Prove it yourself

​MCP server

​Verification

​Related

Endpoints

Request

Rule effects

Negation-as-failure

Outcomes

Response

Behavior changes in v0.9.4

Behavior changes in v0.6.0 and v0.7.0

Confidence is capped by the weakest supporting fact (v0.7.0)

Subject and action binding (v0.6.0)

Abduction no longer asks for un-suppliable builtins (v0.7.0)

Soundness guarantees

Policy impact analysis

Idempotency

Metering

Verify a proof without trusting us

The outcome loop

Prove it yourself

MCP server

Verification

Related