curl --request POST \
--url 'https://api.nsr.stateset.com/api/v1/replies' \
--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",
"context": {}
}'
{
"decision": {
"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": [],
"classification_confidence": 1,
"domains": [],
"escalation_triggered": true,
"explanation": "string",
"grounded_symbol": "string",
"gss_v3_shadow": {
"candidate_rules": null,
"matched_predicates": null,
"matched_symbols": null,
"org_scoped": null
},
"horn_clauses_fired": [],
"inferred_symbols": [],
"intents": [],
"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": [],
"derivation": {
"authorizing_predicate": null,
"cited_org_rules": null,
"org_facts_used": null,
"replayable": null,
"steps": null
},
"neural_steps": 1,
"planner_steps": 1,
"proof_score": 1,
"proof_status": "string",
"request_policy_hash": "string",
"symbolic_steps": 1
},
"rationale": "string",
"refusal": {
"missing_facts": [],
"reason": "string",
"requires_human_review": true
},
"trace": [
{
"description": null,
"duration_ms": null,
"input": null,
"output": null,
"step_type": null,
"task_id": null
}
],
"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_runtime": {
"approved_action_types": null,
"blocked_action_types": null,
"executed_action_types": null,
"execution_receipt": null,
"lifecycle_stage": null,
"prepared_action_types": null,
"review_required_action_types": null
},
"answer": null,
"assistant_message": "string",
"audit_trace": [],
"context": {
"hydrated_entities": null,
"hydrated_rules": null,
"hydrated_triples": null,
"request_facts": null,
"request_rules": null,
"skipped_rule_names": null,
"skipped_rules": null
},
"cost": {
"api_surface": null,
"billable_outcome": null,
"billing_tier": null,
"elapsed_ms": null,
"estimated_cost_units": null,
"iterations": null,
"max_depth_reached": null,
"neural_steps": null,
"outcome_cost_microdollars": null,
"planner_steps": null,
"symbolic_steps": null
},
"explanation": "string",
"facts": [],
"goal": "string",
"mode": "fast",
"org_id": "string",
"proof": {
"cited_rules": null,
"completed_tasks": null,
"neural_steps": null,
"planner_steps": null,
"symbolic_steps": null
},
"session_id": "string",
"success": true,
"suggested_actions": [],
"tool_calls": [],
"trace": [],
"trace_id": "string",
"uncertainty": {
"aleatoric": null,
"epistemic": null,
"mandatory_review": null,
"requires_human_review": null,
"total": null
},
"validation": {
"action_execution_eligible": null,
"action_execution_reason": null,
"cited_rule_count": null,
"grounded_entity_count": null,
"grounded_target_count": null,
"grounding_status": null,
"llm_backend_live": null,
"llm_provider": null,
"proof_score": null,
"proof_status": null,
"symbolic_step_count": null,
"validation_level": null
}
}
},
"reply": {
"auto_send": true,
"macro_id": "string",
"macro_name": "string",
"missing_slots": [
"string"
],
"rendered": "string",
"rule_name": "string"
},
"requires_human": [
"string"
],
"tool_blocked_on": [
"string"
],
"tool_call": null
}
Decide, then draft — one call.
Required scope: write
POST
/
api
/
v1
/
replies
curl --request POST \
--url 'https://api.nsr.stateset.com/api/v1/replies' \
--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",
"context": {}
}'
{
"decision": {
"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": [],
"classification_confidence": 1,
"domains": [],
"escalation_triggered": true,
"explanation": "string",
"grounded_symbol": "string",
"gss_v3_shadow": {
"candidate_rules": null,
"matched_predicates": null,
"matched_symbols": null,
"org_scoped": null
},
"horn_clauses_fired": [],
"inferred_symbols": [],
"intents": [],
"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": [],
"derivation": {
"authorizing_predicate": null,
"cited_org_rules": null,
"org_facts_used": null,
"replayable": null,
"steps": null
},
"neural_steps": 1,
"planner_steps": 1,
"proof_score": 1,
"proof_status": "string",
"request_policy_hash": "string",
"symbolic_steps": 1
},
"rationale": "string",
"refusal": {
"missing_facts": [],
"reason": "string",
"requires_human_review": true
},
"trace": [
{
"description": null,
"duration_ms": null,
"input": null,
"output": null,
"step_type": null,
"task_id": null
}
],
"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_runtime": {
"approved_action_types": null,
"blocked_action_types": null,
"executed_action_types": null,
"execution_receipt": null,
"lifecycle_stage": null,
"prepared_action_types": null,
"review_required_action_types": null
},
"answer": null,
"assistant_message": "string",
"audit_trace": [],
"context": {
"hydrated_entities": null,
"hydrated_rules": null,
"hydrated_triples": null,
"request_facts": null,
"request_rules": null,
"skipped_rule_names": null,
"skipped_rules": null
},
"cost": {
"api_surface": null,
"billable_outcome": null,
"billing_tier": null,
"elapsed_ms": null,
"estimated_cost_units": null,
"iterations": null,
"max_depth_reached": null,
"neural_steps": null,
"outcome_cost_microdollars": null,
"planner_steps": null,
"symbolic_steps": null
},
"explanation": "string",
"facts": [],
"goal": "string",
"mode": "fast",
"org_id": "string",
"proof": {
"cited_rules": null,
"completed_tasks": null,
"neural_steps": null,
"planner_steps": null,
"symbolic_steps": null
},
"session_id": "string",
"success": true,
"suggested_actions": [],
"tool_calls": [],
"trace": [],
"trace_id": "string",
"uncertainty": {
"aleatoric": null,
"epistemic": null,
"mandatory_review": null,
"requires_human_review": null,
"total": null
},
"validation": {
"action_execution_eligible": null,
"action_execution_reason": null,
"cited_rule_count": null,
"grounded_entity_count": null,
"grounded_target_count": null,
"grounding_status": null,
"llm_backend_live": null,
"llm_provider": null,
"proof_score": null,
"proof_status": null,
"symbolic_step_count": null,
"validation_level": null
}
}
},
"reply": {
"auto_send": true,
"macro_id": "string",
"macro_name": "string",
"missing_slots": [
"string"
],
"rendered": "string",
"rule_name": "string"
},
"requires_human": [
"string"
],
"tool_blocked_on": [
"string"
],
"tool_call": null
}
Required scope:
write
Request body
JSON body of typeReplyRequest.
Response
ReplyResponse
DecisionResponse
required
Show DecisionResponse
Show 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
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
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
RecursiveChatCost
required
string
required
RecursiveChatFactView[]
string
required
RecursiveChatMode
required
string
required
RecursiveChatProof
required
string
boolean
required
SuggestedAction[]
required
ToolCall[]
required
RecursiveChatTraceStep[]
string
required
RecursiveChatUncertainty
required
RecursiveChatValidation
object
Show reply
Show reply
boolean
required
True only when the macro is approved, fully filled, its tool call fully bound, and the macro itself armed for auto-send. Anything less is a draft for a human.
string
required
string
required
string[]
required
Merge fields with no value supplied. Non-empty blocks sending.
string
required
string
required
string[]
Why a human is needed, when one is. Empty means this can ship.
string[]
Tool arguments that could not be bound. Non-empty means the tool was withheld — and so was the reply, if it announces that action.
object
Status codes
| Code | Meaning |
|---|---|
200 | Decision plus the macro and tool call it selects |
401 | Unauthorized — missing or invalid credentials |
402 | Quota exhausted |
403 | Forbidden — the key/token lacks the required scope |
422 | Malformed decision request |
429 | Rate limited — see Retry-After / X-RateLimit-Reset |
curl --request POST \
--url 'https://api.nsr.stateset.com/api/v1/replies' \
--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",
"context": {}
}'
{
"decision": {
"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": [],
"classification_confidence": 1,
"domains": [],
"escalation_triggered": true,
"explanation": "string",
"grounded_symbol": "string",
"gss_v3_shadow": {
"candidate_rules": null,
"matched_predicates": null,
"matched_symbols": null,
"org_scoped": null
},
"horn_clauses_fired": [],
"inferred_symbols": [],
"intents": [],
"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": [],
"derivation": {
"authorizing_predicate": null,
"cited_org_rules": null,
"org_facts_used": null,
"replayable": null,
"steps": null
},
"neural_steps": 1,
"planner_steps": 1,
"proof_score": 1,
"proof_status": "string",
"request_policy_hash": "string",
"symbolic_steps": 1
},
"rationale": "string",
"refusal": {
"missing_facts": [],
"reason": "string",
"requires_human_review": true
},
"trace": [
{
"description": null,
"duration_ms": null,
"input": null,
"output": null,
"step_type": null,
"task_id": null
}
],
"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_runtime": {
"approved_action_types": null,
"blocked_action_types": null,
"executed_action_types": null,
"execution_receipt": null,
"lifecycle_stage": null,
"prepared_action_types": null,
"review_required_action_types": null
},
"answer": null,
"assistant_message": "string",
"audit_trace": [],
"context": {
"hydrated_entities": null,
"hydrated_rules": null,
"hydrated_triples": null,
"request_facts": null,
"request_rules": null,
"skipped_rule_names": null,
"skipped_rules": null
},
"cost": {
"api_surface": null,
"billable_outcome": null,
"billing_tier": null,
"elapsed_ms": null,
"estimated_cost_units": null,
"iterations": null,
"max_depth_reached": null,
"neural_steps": null,
"outcome_cost_microdollars": null,
"planner_steps": null,
"symbolic_steps": null
},
"explanation": "string",
"facts": [],
"goal": "string",
"mode": "fast",
"org_id": "string",
"proof": {
"cited_rules": null,
"completed_tasks": null,
"neural_steps": null,
"planner_steps": null,
"symbolic_steps": null
},
"session_id": "string",
"success": true,
"suggested_actions": [],
"tool_calls": [],
"trace": [],
"trace_id": "string",
"uncertainty": {
"aleatoric": null,
"epistemic": null,
"mandatory_review": null,
"requires_human_review": null,
"total": null
},
"validation": {
"action_execution_eligible": null,
"action_execution_reason": null,
"cited_rule_count": null,
"grounded_entity_count": null,
"grounded_target_count": null,
"grounding_status": null,
"llm_backend_live": null,
"llm_provider": null,
"proof_score": null,
"proof_status": null,
"symbolic_step_count": null,
"validation_level": null
}
}
},
"reply": {
"auto_send": true,
"macro_id": "string",
"macro_name": "string",
"missing_slots": [
"string"
],
"rendered": "string",
"rule_name": "string"
},
"requires_human": [
"string"
],
"tool_blocked_on": [
"string"
],
"tool_call": null
}