curl --request POST \
--url 'https://api.nsr.stateset.com/v1/decisions' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"action": "string",
"authorization_goal": {
"args": [
"string"
],
"name": "string",
"negated": true
},
"confidence_threshold": 1,
"external_ref": "string",
"facts": [
{
"confidence": 1,
"predicate": {
"args": null,
"name": null,
"negated": null
},
"source": "string"
}
],
"hydrate_org_context": true,
"include_trace": true,
"kb_limits": {
"max_entities": 1,
"max_properties_per_entity": 1,
"max_rules": 1,
"max_triples": 1
},
"max_depth": 1,
"max_iterations": 1,
"mode": "string",
"query": "string",
"rules": [
{
"category": "string",
"constraints": [],
"description": "string",
"effect": {
"0": "p",
"1": "e",
"2": "r",
"3": "m",
"4": "i",
"5": "t"
},
"enabled": true,
"id": "string",
"if": [],
"name": "string",
"priority": 1,
"then": []
}
],
"session_id": "string"
}'
{
"action": {
"confidence": 1,
"name": "string",
"ready": true,
"reason": "string",
"rule_conclusion": "string",
"rule_name": "string"
},
"confidence": 1,
"decision": "string",
"decision_id": "string",
"dropped_citations": [
"string"
],
"evaluated_goal": "string",
"grounding": {
"cited_rule_count": 1,
"grounded_entity_count": 1,
"grounded_target_count": 1,
"status": "string"
},
"gss_machine": {
"authority": "string",
"categories": [
"string"
],
"classification_confidence": 1,
"domains": [
"string"
],
"escalation_triggered": true,
"explanation": "string",
"grounded_symbol": "string",
"gss_v3_shadow": {
"candidate_rules": [],
"matched_predicates": [],
"matched_symbols": [],
"org_scoped": true
},
"horn_clauses_fired": [
"string"
],
"inferred_symbols": [
"string"
],
"intents": [
"string"
],
"machine_confidence": 1,
"machine_output": "string",
"machine_state_version": 1,
"safety_gate_triggered": true,
"seed_grounded": true,
"seed_source": "string",
"symbol_alignment": 1
},
"plain_explanation": "string",
"proof": {
"cited_rules": [
"string"
],
"derivation": {
"authorizing_predicate": "string",
"cited_org_rules": [],
"org_facts_used": [],
"replayable": true,
"steps": []
},
"neural_steps": 1,
"planner_steps": 1,
"proof_score": 1,
"proof_status": "string",
"request_policy_hash": "string",
"symbolic_steps": 1
},
"rationale": "string",
"refusal": {
"missing_facts": [
{
"args": null,
"needed_by_rule": null,
"predicate": null,
"question": null,
"resolves_with": null
}
],
"reason": "string",
"requires_human_review": true
},
"trace": [
{
"description": "string",
"duration_ms": 1,
"input": null,
"output": null,
"step_type": "string",
"task_id": "string"
}
],
"usage": {
"billable": true,
"billing_tier": "string",
"elapsed_ms": 1,
"iterations": 1,
"max_depth_reached": 1,
"outcome_cost_microdollars": 1
},
"verifiable_bundle": null,
"warnings": [
"string"
],
"x_nsr": {
"action_results": [
{
"action_type": null,
"details": null,
"matched_entity_ids": null,
"status": null,
"summary": null,
"tool_name": null
}
],
"action_runtime": {
"approved_action_types": [],
"blocked_action_types": [],
"executed_action_types": [],
"execution_receipt": {
"available_action_types": null,
"expires_at": null,
"receipt_id": null
},
"lifecycle_stage": "string",
"prepared_action_types": [],
"review_required_action_types": []
},
"answer": null,
"assistant_message": "string",
"audit_trace": [
{
"description": null,
"duration_ms": null,
"input": null,
"output": null,
"step_type": null,
"task_id": null
}
],
"context": {
"hydrated_entities": 1,
"hydrated_rules": 1,
"hydrated_triples": 1,
"request_facts": 1,
"request_rules": 1,
"skipped_rule_names": [],
"skipped_rules": 1
},
"cost": {
"api_surface": "string",
"billable_outcome": true,
"billing_tier": "string",
"elapsed_ms": 1,
"estimated_cost_units": 1,
"iterations": 1,
"max_depth_reached": 1,
"neural_steps": 1,
"outcome_cost_microdollars": 1,
"planner_steps": 1,
"symbolic_steps": 1
},
"explanation": "string",
"facts": [
{
"args": null,
"confidence": null,
"predicate": null,
"source": null
}
],
"goal": "string",
"mode": "fast",
"org_id": "string",
"proof": {
"cited_rules": [],
"completed_tasks": [],
"neural_steps": 1,
"planner_steps": 1,
"symbolic_steps": 1
},
"session_id": "string",
"success": true,
"suggested_actions": [
{
"action_type": null,
"can_auto_execute": null,
"execution_status": null,
"label": null,
"missing_inputs": null,
"reason": null,
"required_inputs": null,
"tool_name": null
}
],
"tool_calls": [
{
"arguments": null,
"function": null,
"id": null,
"policy": null,
"status": null
}
],
"trace": [
{
"description": null,
"duration_ms": null,
"input": null,
"output": null,
"step_type": null,
"task_id": null
}
],
"trace_id": "string",
"uncertainty": {
"aleatoric": 1,
"epistemic": 1,
"mandatory_review": true,
"requires_human_review": true,
"total": 1
},
"validation": {
"action_execution_eligible": true,
"action_execution_reason": "string",
"cited_rule_count": 1,
"grounded_entity_count": 1,
"grounded_target_count": 1,
"grounding_status": "string",
"llm_backend_live": true,
"llm_provider": "string",
"proof_score": 1,
"proof_status": "string",
"symbolic_step_count": 1,
"validation_level": "string"
}
}
}
Produce an auditable, policy-grounded decision with a proof chain.
Required scope: write
POST
/
v1
/
decisions
curl --request POST \
--url 'https://api.nsr.stateset.com/v1/decisions' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"action": "string",
"authorization_goal": {
"args": [
"string"
],
"name": "string",
"negated": true
},
"confidence_threshold": 1,
"external_ref": "string",
"facts": [
{
"confidence": 1,
"predicate": {
"args": null,
"name": null,
"negated": null
},
"source": "string"
}
],
"hydrate_org_context": true,
"include_trace": true,
"kb_limits": {
"max_entities": 1,
"max_properties_per_entity": 1,
"max_rules": 1,
"max_triples": 1
},
"max_depth": 1,
"max_iterations": 1,
"mode": "string",
"query": "string",
"rules": [
{
"category": "string",
"constraints": [],
"description": "string",
"effect": {
"0": "p",
"1": "e",
"2": "r",
"3": "m",
"4": "i",
"5": "t"
},
"enabled": true,
"id": "string",
"if": [],
"name": "string",
"priority": 1,
"then": []
}
],
"session_id": "string"
}'
{
"action": {
"confidence": 1,
"name": "string",
"ready": true,
"reason": "string",
"rule_conclusion": "string",
"rule_name": "string"
},
"confidence": 1,
"decision": "string",
"decision_id": "string",
"dropped_citations": [
"string"
],
"evaluated_goal": "string",
"grounding": {
"cited_rule_count": 1,
"grounded_entity_count": 1,
"grounded_target_count": 1,
"status": "string"
},
"gss_machine": {
"authority": "string",
"categories": [
"string"
],
"classification_confidence": 1,
"domains": [
"string"
],
"escalation_triggered": true,
"explanation": "string",
"grounded_symbol": "string",
"gss_v3_shadow": {
"candidate_rules": [],
"matched_predicates": [],
"matched_symbols": [],
"org_scoped": true
},
"horn_clauses_fired": [
"string"
],
"inferred_symbols": [
"string"
],
"intents": [
"string"
],
"machine_confidence": 1,
"machine_output": "string",
"machine_state_version": 1,
"safety_gate_triggered": true,
"seed_grounded": true,
"seed_source": "string",
"symbol_alignment": 1
},
"plain_explanation": "string",
"proof": {
"cited_rules": [
"string"
],
"derivation": {
"authorizing_predicate": "string",
"cited_org_rules": [],
"org_facts_used": [],
"replayable": true,
"steps": []
},
"neural_steps": 1,
"planner_steps": 1,
"proof_score": 1,
"proof_status": "string",
"request_policy_hash": "string",
"symbolic_steps": 1
},
"rationale": "string",
"refusal": {
"missing_facts": [
{
"args": null,
"needed_by_rule": null,
"predicate": null,
"question": null,
"resolves_with": null
}
],
"reason": "string",
"requires_human_review": true
},
"trace": [
{
"description": "string",
"duration_ms": 1,
"input": null,
"output": null,
"step_type": "string",
"task_id": "string"
}
],
"usage": {
"billable": true,
"billing_tier": "string",
"elapsed_ms": 1,
"iterations": 1,
"max_depth_reached": 1,
"outcome_cost_microdollars": 1
},
"verifiable_bundle": null,
"warnings": [
"string"
],
"x_nsr": {
"action_results": [
{
"action_type": null,
"details": null,
"matched_entity_ids": null,
"status": null,
"summary": null,
"tool_name": null
}
],
"action_runtime": {
"approved_action_types": [],
"blocked_action_types": [],
"executed_action_types": [],
"execution_receipt": {
"available_action_types": null,
"expires_at": null,
"receipt_id": null
},
"lifecycle_stage": "string",
"prepared_action_types": [],
"review_required_action_types": []
},
"answer": null,
"assistant_message": "string",
"audit_trace": [
{
"description": null,
"duration_ms": null,
"input": null,
"output": null,
"step_type": null,
"task_id": null
}
],
"context": {
"hydrated_entities": 1,
"hydrated_rules": 1,
"hydrated_triples": 1,
"request_facts": 1,
"request_rules": 1,
"skipped_rule_names": [],
"skipped_rules": 1
},
"cost": {
"api_surface": "string",
"billable_outcome": true,
"billing_tier": "string",
"elapsed_ms": 1,
"estimated_cost_units": 1,
"iterations": 1,
"max_depth_reached": 1,
"neural_steps": 1,
"outcome_cost_microdollars": 1,
"planner_steps": 1,
"symbolic_steps": 1
},
"explanation": "string",
"facts": [
{
"args": null,
"confidence": null,
"predicate": null,
"source": null
}
],
"goal": "string",
"mode": "fast",
"org_id": "string",
"proof": {
"cited_rules": [],
"completed_tasks": [],
"neural_steps": 1,
"planner_steps": 1,
"symbolic_steps": 1
},
"session_id": "string",
"success": true,
"suggested_actions": [
{
"action_type": null,
"can_auto_execute": null,
"execution_status": null,
"label": null,
"missing_inputs": null,
"reason": null,
"required_inputs": null,
"tool_name": null
}
],
"tool_calls": [
{
"arguments": null,
"function": null,
"id": null,
"policy": null,
"status": null
}
],
"trace": [
{
"description": null,
"duration_ms": null,
"input": null,
"output": null,
"step_type": null,
"task_id": null
}
],
"trace_id": "string",
"uncertainty": {
"aleatoric": 1,
"epistemic": 1,
"mandatory_review": true,
"requires_human_review": true,
"total": 1
},
"validation": {
"action_execution_eligible": true,
"action_execution_reason": "string",
"cited_rule_count": 1,
"grounded_entity_count": 1,
"grounded_target_count": 1,
"grounding_status": "string",
"llm_backend_live": true,
"llm_provider": "string",
"proof_score": 1,
"proof_status": "string",
"symbolic_step_count": 1,
"validation_level": "string"
}
}
}
Required scope:
write
Request body
DecisionRequest
string
Optional explicit action being authorized (e.g. ‘issue_refund’). When present, the decision reflects whether this action is permitted.
object
number (double)
string
Optional client correlation key (their order id, case id, claim number). Stored on the decision so the real-world outcome can later be recorded against it via
POST /v1/decisions/outcome-by-ref — a chargeback or override webhook knows this id, not our decision_id.RecursiveChatFactInput[]
Request-scoped facts injected into the working set.
boolean
When false, skip org knowledge-base hydration (default true).
boolean
When true, include the full proof trace and raw engine payload.
object
integer
Recursion depth / iteration / confidence overrides.
integer
string
Reasoning thoroughness:
fast | accurate | safe. Decisions default to safe (highest verification) since they are accountable outputs.string
required
The decision question, e.g. ‘Can order #A1 be refunded for customer C?’.
RecursiveChatRuleInput[]
Request-scoped rules injected into the working set.
string
Optional caller session id (carried into the solver).
Response
DecisionResponse
object
number (double)
required
string
required
approved | denied | refused.string
required
string[]
Org rules the engine fired during hydration that were dropped from
proof.cited_rules as unrelated to this decision. Persistently non-empty values mean a standing rule with permanently satisfied premises fires on every hydrated decision — scope or prune it.string
Exact predicate evaluated as the permit target. Absent for legacy requests that relied on action/query inference.
DecisionGrounding
required
GssMachineGroundingSnapshot
required
Show GssMachineGroundingSnapshot
Show GssMachineGroundingSnapshot
string
required
string[]
required
number (double)
required
Confidence of the GSS perception/classification stage.
string[]
required
boolean
required
string
string
Best-aligned canonical symbol under the variance-aware alignment.
object
Show gss_v3_shadow
Show gss_v3_shadow
GssV3ShadowRule[]
required
string[]
required
GssV3ShadowSymbolMatch[]
required
boolean
required
true when candidate_rules was filtered to rules with an ACTIVATED org_bindings entry for the requesting org. false when the org has zero bindings anywhere in the seed (unknown org) and the shadow matcher fell back to the unfiltered rulebook. Matched symbols are never org-filtered — they are shared vocabulary by design.string[]
required
string[]
required
string[]
required
number (double)
required
Confidence that NSRMachine recognized and executed the supplied grounded symbols. This is not an end-to-end decision confidence.
string
integer (int64)
Chat-mutation version of the org’s NSRMachine this decision inferred against, alongside
request_policy_hash in spirit: two runs of the same request stamped with the same version had the same machine view; differing stamps make cross-run drift auditable rather than silent (FINDING-nondeterministic-outcome, option 3).boolean
required
boolean
required
string
required
number (double)
Variance-aware (isotropic Mahalanobis) alignment of the message composite to that symbol’s centroid, in (0,1]:
exp(−d²/2σ²) with σ² the symbol’s learned seed variance. Use this to assess grounding uncertainty — unlike the classification mixture score, it reflects the symbol’s observed spread, not lexical overlap.string
required
Deterministic, proof-derived, business-readable ‘why’ — distinct from
rationale (engine narration): ‘Approved to issue a refund for order 9412: the return for order 9412 was received and order 9412 passed inspection.’ Always present.DecisionProof
required
Show DecisionProof
Show DecisionProof
string[]
required
Org rules cited in the derivation (the audit trail).
object
Show derivation
Show derivation
string
The decisive conclusion (declared effect or policy-marker head) the verdict stood on.
OrgRuleDefinition[]
Definitions of cited rules that live in the org knowledge base rather than request scope, so an auditor can read the exact policy the verdict stood on even when it cannot be replayed from the request alone.
string[]
Org-KB facts that served as premises in the replayed chain — the org-side evidence a third party needs to check the derivation.
boolean
required
True when every cited rule fired from the evidence carried in this response (request facts plus the org facts listed in
org_facts_used), i.e. the whole chain replays from the response.DerivationStep[]
required
Rule firings in derivation order, restricted to the cited dependency path.
integer
required
integer
required
number (double)
required
0–1 proof strength from the engine’s validation pass.
string
required
string
sha256:<hex> over the canonicalized request-scoped facts and rules — pins this decision to the exact policy inputs it was evaluated against. Absent when the request carried no inline policy.integer
required
string
required
object
Show refusal
Show refusal
MissingFact[]
Request-scoped premises that would unblock an authorization proof: body atoms on the dependency path to a positive policy conclusion that neither the supplied facts nor any derivable conclusion satisfies. Empty for safety-gated refusals, which must not invite resubmission.
string
required
boolean
required
RecursiveChatTraceStep[]
DecisionUsage
required
object
A self-contained, INDEPENDENTLY-VERIFIABLE proof bundle for an approved decision: the exact facts and rules plus a
RuleEngine::backward_chain derivation of the authorization goal, in the knowledge::ProofBundle wire format. POST it verbatim to /v1/proofs/verify (or check it offline with the dependency-light proof_check) to confirm the verdict without trusting this server. Present only when the caller declared an authorization_goal AND the rule engine reproduces the proof; absent otherwise (the verdict still stands on its own derivation).string[]
Non-fatal advisories about how the verdict was derived (e.g. the outcome rested on predicate-name inference rather than declared rule effects). Omitted when empty.
object
Show x_nsr
Show x_nsr
ActionExecutionResult[]
required
RecursiveChatActionRuntime
required
object
string
required
RecursiveChatTraceStep[]
RecursiveChatContextSummary
required
Show RecursiveChatContextSummary
Show RecursiveChatContextSummary
integer
required
integer
required
integer
required
integer
required
integer
required
string[]
Names of the skipped rules, capped for response size.
integer
Org rules that could NOT be represented in the chat rule language and were therefore not applied — today, rules with a negated head (the chat engine has no negated conclusion) and rules with terms that do not convert. Reported rather than silently dropped: a caller reasoning about a policy needs to know part of it was not in force, especially when the dropped part is a prohibition.
RecursiveChatCost
required
string
required
RecursiveChatFactView[]
string
required
RecursiveChatMode
required
string
required
RecursiveChatProof
required
string
boolean
required
SuggestedAction[]
required
ToolCall[]
required
Show ToolCall
Show ToolCall
object
required
Structured arguments extracted from the message and KB context.
string
required
Function name to invoke (e.g., ‘issue_refund’, ‘create_return’, ‘escalate’).
string
required
Unique ID for this tool call.
ToolCallPolicy
required
string
required
Whether this call is ready to execute or needs more context.
RecursiveChatTraceStep[]
string
required
RecursiveChatUncertainty
required
Show RecursiveChatUncertainty
Show RecursiveChatUncertainty
number (double)
required
number (double)
required
boolean
True when review is required for a reason a symbolic proof must NOT override: a safety emergency (medical-emergency language) or the solver explicitly declining. A strong, request-bound symbolic permit may suppress a review driven only by the soft uncertainty threshold, but never this — approving a grounded refund is fine, but a message also reporting a severe reaction still escalates to a human.
boolean
required
number (double)
required
Status codes
| Code | Meaning |
|---|---|
200 | Verified decision with proof |
400 | Invalid request |
401 | Unauthorized — missing or invalid credentials |
402 | Outcome quota exhausted |
403 | Forbidden — the key/token lacks the required scope |
429 | Rate limited — see Retry-After / X-RateLimit-Reset |
curl --request POST \
--url 'https://api.nsr.stateset.com/v1/decisions' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"action": "string",
"authorization_goal": {
"args": [
"string"
],
"name": "string",
"negated": true
},
"confidence_threshold": 1,
"external_ref": "string",
"facts": [
{
"confidence": 1,
"predicate": {
"args": null,
"name": null,
"negated": null
},
"source": "string"
}
],
"hydrate_org_context": true,
"include_trace": true,
"kb_limits": {
"max_entities": 1,
"max_properties_per_entity": 1,
"max_rules": 1,
"max_triples": 1
},
"max_depth": 1,
"max_iterations": 1,
"mode": "string",
"query": "string",
"rules": [
{
"category": "string",
"constraints": [],
"description": "string",
"effect": {
"0": "p",
"1": "e",
"2": "r",
"3": "m",
"4": "i",
"5": "t"
},
"enabled": true,
"id": "string",
"if": [],
"name": "string",
"priority": 1,
"then": []
}
],
"session_id": "string"
}'
{
"action": {
"confidence": 1,
"name": "string",
"ready": true,
"reason": "string",
"rule_conclusion": "string",
"rule_name": "string"
},
"confidence": 1,
"decision": "string",
"decision_id": "string",
"dropped_citations": [
"string"
],
"evaluated_goal": "string",
"grounding": {
"cited_rule_count": 1,
"grounded_entity_count": 1,
"grounded_target_count": 1,
"status": "string"
},
"gss_machine": {
"authority": "string",
"categories": [
"string"
],
"classification_confidence": 1,
"domains": [
"string"
],
"escalation_triggered": true,
"explanation": "string",
"grounded_symbol": "string",
"gss_v3_shadow": {
"candidate_rules": [],
"matched_predicates": [],
"matched_symbols": [],
"org_scoped": true
},
"horn_clauses_fired": [
"string"
],
"inferred_symbols": [
"string"
],
"intents": [
"string"
],
"machine_confidence": 1,
"machine_output": "string",
"machine_state_version": 1,
"safety_gate_triggered": true,
"seed_grounded": true,
"seed_source": "string",
"symbol_alignment": 1
},
"plain_explanation": "string",
"proof": {
"cited_rules": [
"string"
],
"derivation": {
"authorizing_predicate": "string",
"cited_org_rules": [],
"org_facts_used": [],
"replayable": true,
"steps": []
},
"neural_steps": 1,
"planner_steps": 1,
"proof_score": 1,
"proof_status": "string",
"request_policy_hash": "string",
"symbolic_steps": 1
},
"rationale": "string",
"refusal": {
"missing_facts": [
{
"args": null,
"needed_by_rule": null,
"predicate": null,
"question": null,
"resolves_with": null
}
],
"reason": "string",
"requires_human_review": true
},
"trace": [
{
"description": "string",
"duration_ms": 1,
"input": null,
"output": null,
"step_type": "string",
"task_id": "string"
}
],
"usage": {
"billable": true,
"billing_tier": "string",
"elapsed_ms": 1,
"iterations": 1,
"max_depth_reached": 1,
"outcome_cost_microdollars": 1
},
"verifiable_bundle": null,
"warnings": [
"string"
],
"x_nsr": {
"action_results": [
{
"action_type": null,
"details": null,
"matched_entity_ids": null,
"status": null,
"summary": null,
"tool_name": null
}
],
"action_runtime": {
"approved_action_types": [],
"blocked_action_types": [],
"executed_action_types": [],
"execution_receipt": {
"available_action_types": null,
"expires_at": null,
"receipt_id": null
},
"lifecycle_stage": "string",
"prepared_action_types": [],
"review_required_action_types": []
},
"answer": null,
"assistant_message": "string",
"audit_trace": [
{
"description": null,
"duration_ms": null,
"input": null,
"output": null,
"step_type": null,
"task_id": null
}
],
"context": {
"hydrated_entities": 1,
"hydrated_rules": 1,
"hydrated_triples": 1,
"request_facts": 1,
"request_rules": 1,
"skipped_rule_names": [],
"skipped_rules": 1
},
"cost": {
"api_surface": "string",
"billable_outcome": true,
"billing_tier": "string",
"elapsed_ms": 1,
"estimated_cost_units": 1,
"iterations": 1,
"max_depth_reached": 1,
"neural_steps": 1,
"outcome_cost_microdollars": 1,
"planner_steps": 1,
"symbolic_steps": 1
},
"explanation": "string",
"facts": [
{
"args": null,
"confidence": null,
"predicate": null,
"source": null
}
],
"goal": "string",
"mode": "fast",
"org_id": "string",
"proof": {
"cited_rules": [],
"completed_tasks": [],
"neural_steps": 1,
"planner_steps": 1,
"symbolic_steps": 1
},
"session_id": "string",
"success": true,
"suggested_actions": [
{
"action_type": null,
"can_auto_execute": null,
"execution_status": null,
"label": null,
"missing_inputs": null,
"reason": null,
"required_inputs": null,
"tool_name": null
}
],
"tool_calls": [
{
"arguments": null,
"function": null,
"id": null,
"policy": null,
"status": null
}
],
"trace": [
{
"description": null,
"duration_ms": null,
"input": null,
"output": null,
"step_type": null,
"task_id": null
}
],
"trace_id": "string",
"uncertainty": {
"aleatoric": 1,
"epistemic": 1,
"mandatory_review": true,
"requires_human_review": true,
"total": 1
},
"validation": {
"action_execution_eligible": true,
"action_execution_reason": "string",
"cited_rule_count": 1,
"grounded_entity_count": 1,
"grounded_target_count": 1,
"grounding_status": "string",
"llm_backend_live": true,
"llm_provider": "string",
"proof_score": 1,
"proof_status": "string",
"symbolic_step_count": 1,
"validation_level": "string"
}
}
}