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

# Recursive chat solve handler

> **Required scope:** write

**Required scope:** `write`

### Request body

`RecursiveChatRequest`

<ParamField body="api_surface" type="string" />

<ParamField body="confidence_threshold" type="number (double)" />

<ParamField body="decompositions" type="RecursiveChatDecomposition[]" />

<ParamField body="facts" type="RecursiveChatFactInput[]" />

<ParamField body="goal" type="string" />

<ParamField body="hydrate_org_context" type="boolean" />

<ParamField body="include_facts" type="boolean" />

<ParamField body="include_trace" type="boolean" />

<ParamField body="kb_limits" type="object" />

<ParamField body="max_depth" type="integer" />

<ParamField body="max_iterations" type="integer" />

<ParamField body="messages" type="RecursiveChatMessage[]" required />

<ParamField body="mode" type="object" />

<ParamField body="org_id" type="string" />

<ParamField body="rules" type="RecursiveChatRuleInput[]" />

<ParamField body="session_id" type="string" />

<ParamField body="target" type="string" />

### Response

`RecursiveChatResponse`

<ResponseField name="action_results" type="ActionExecutionResult[]" required>
  <Expandable title="ActionExecutionResult">
    <ResponseField name="action_type" type="string" required />

    <ResponseField name="details" type="string[]" required />

    <ResponseField name="matched_entity_ids" type="string[]" required />

    <ResponseField name="status" type="string" required />

    <ResponseField name="summary" type="string" required />

    <ResponseField name="tool_name" type="string" required />
  </Expandable>
</ResponseField>

<ResponseField name="action_runtime" type="RecursiveChatActionRuntime" required>
  <Expandable title="RecursiveChatActionRuntime">
    <ResponseField name="approved_action_types" type="string[]" required />

    <ResponseField name="blocked_action_types" type="string[]" required />

    <ResponseField name="executed_action_types" type="string[]" required />

    <ResponseField name="execution_receipt" type="object">
      <Expandable title="execution_receipt">
        <ResponseField name="available_action_types" type="string[]" required />

        <ResponseField name="expires_at" type="string" required />

        <ResponseField name="receipt_id" type="string" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="lifecycle_stage" type="string" required />

    <ResponseField name="prepared_action_types" type="string[]" required />

    <ResponseField name="review_required_action_types" type="string[]" required />
  </Expandable>
</ResponseField>

<ResponseField name="answer" type="object" />

<ResponseField name="assistant_message" type="string" required />

<ResponseField name="audit_trace" type="RecursiveChatTraceStep[]">
  <Expandable title="RecursiveChatTraceStep">
    <ResponseField name="description" type="string" required />

    <ResponseField name="duration_ms" type="integer (int64)" required />

    <ResponseField name="input" type="object" />

    <ResponseField name="output" type="object" />

    <ResponseField name="step_type" type="string" required />

    <ResponseField name="task_id" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="context" type="RecursiveChatContextSummary" required>
  <Expandable title="RecursiveChatContextSummary">
    <ResponseField name="hydrated_entities" type="integer" required />

    <ResponseField name="hydrated_rules" type="integer" required />

    <ResponseField name="hydrated_triples" type="integer" required />

    <ResponseField name="request_facts" type="integer" required />

    <ResponseField name="request_rules" type="integer" required />

    <ResponseField name="skipped_rule_names" type="string[]">
      Names of the skipped rules, capped for response size.
    </ResponseField>

    <ResponseField name="skipped_rules" type="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.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cost" type="RecursiveChatCost" required>
  <Expandable title="RecursiveChatCost">
    <ResponseField name="api_surface" type="string" required />

    <ResponseField name="billable_outcome" type="boolean" required />

    <ResponseField name="billing_tier" type="string" required />

    <ResponseField name="elapsed_ms" type="integer (int64)" required />

    <ResponseField name="estimated_cost_units" type="integer (int64)" required />

    <ResponseField name="iterations" type="integer" required />

    <ResponseField name="max_depth_reached" type="integer" required />

    <ResponseField name="neural_steps" type="integer" required />

    <ResponseField name="outcome_cost_microdollars" type="integer (int64)" required />

    <ResponseField name="planner_steps" type="integer" required />

    <ResponseField name="symbolic_steps" type="integer" required />
  </Expandable>
</ResponseField>

<ResponseField name="explanation" type="string" required />

<ResponseField name="facts" type="RecursiveChatFactView[]">
  <Expandable title="RecursiveChatFactView">
    <ResponseField name="args" type="string[]" required />

    <ResponseField name="confidence" type="number (double)" required />

    <ResponseField name="predicate" type="string" required />

    <ResponseField name="source" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="goal" type="string" required />

<ResponseField name="mode" type="RecursiveChatMode" required />

<ResponseField name="org_id" type="string" required />

<ResponseField name="proof" type="RecursiveChatProof" required>
  <Expandable title="RecursiveChatProof">
    <ResponseField name="cited_rules" type="string[]" required />

    <ResponseField name="completed_tasks" type="string[]" required />

    <ResponseField name="neural_steps" type="integer" required />

    <ResponseField name="planner_steps" type="integer" required />

    <ResponseField name="symbolic_steps" type="integer" required />
  </Expandable>
</ResponseField>

<ResponseField name="session_id" type="string" />

<ResponseField name="success" type="boolean" required />

<ResponseField name="suggested_actions" type="SuggestedAction[]" required>
  <Expandable title="SuggestedAction">
    <ResponseField name="action_type" type="string" required />

    <ResponseField name="can_auto_execute" type="boolean" required />

    <ResponseField name="execution_status" type="string" required />

    <ResponseField name="label" type="string" required />

    <ResponseField name="missing_inputs" type="string[]" required />

    <ResponseField name="reason" type="string" required />

    <ResponseField name="required_inputs" type="string[]" required />

    <ResponseField name="tool_name" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="tool_calls" type="ToolCall[]" required>
  <Expandable title="ToolCall">
    <ResponseField name="arguments" type="object" required>
      Structured arguments extracted from the message and KB context.
    </ResponseField>

    <ResponseField name="function" type="string" required>
      Function name to invoke (e.g., 'issue\_refund', 'create\_return', 'escalate').
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique ID for this tool call.
    </ResponseField>

    <ResponseField name="policy" type="ToolCallPolicy" required>
      <Expandable title="ToolCallPolicy">
        <ResponseField name="confidence" type="number (float)" required>
          Confidence from the matching rule.
        </ResponseField>

        <ResponseField name="reason" type="string" required>
          Human-readable reason.
        </ResponseField>

        <ResponseField name="rule_conclusion" type="string" required>
          Rule conclusion (the head of the Horn clause).
        </ResponseField>

        <ResponseField name="rule_name" type="string" required>
          Rule name from the org's KB that triggered this call.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Whether this call is ready to execute or needs more context.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="trace" type="RecursiveChatTraceStep[]">
  <Expandable title="RecursiveChatTraceStep">
    <ResponseField name="description" type="string" required />

    <ResponseField name="duration_ms" type="integer (int64)" required />

    <ResponseField name="input" type="object" />

    <ResponseField name="output" type="object" />

    <ResponseField name="step_type" type="string" required />

    <ResponseField name="task_id" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="trace_id" type="string" required />

<ResponseField name="uncertainty" type="RecursiveChatUncertainty" required>
  <Expandable title="RecursiveChatUncertainty">
    <ResponseField name="aleatoric" type="number (double)" required />

    <ResponseField name="epistemic" type="number (double)" required />

    <ResponseField name="mandatory_review" type="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.
    </ResponseField>

    <ResponseField name="requires_human_review" type="boolean" required />

    <ResponseField name="total" type="number (double)" required />
  </Expandable>
</ResponseField>

<ResponseField name="validation" type="RecursiveChatValidation">
  <Expandable title="RecursiveChatValidation">
    <ResponseField name="action_execution_eligible" type="boolean" required />

    <ResponseField name="action_execution_reason" type="string" required />

    <ResponseField name="cited_rule_count" type="integer" required />

    <ResponseField name="grounded_entity_count" type="integer" required />

    <ResponseField name="grounded_target_count" type="integer" required />

    <ResponseField name="grounding_status" type="string" required />

    <ResponseField name="llm_backend_live" type="boolean" required />

    <ResponseField name="llm_provider" type="string" required />

    <ResponseField name="proof_score" type="number (double)" required />

    <ResponseField name="proof_status" type="string" required />

    <ResponseField name="symbolic_step_count" type="integer" required />

    <ResponseField name="validation_level" type="string" required />
  </Expandable>
</ResponseField>

### Status codes

| Code  | Meaning                                                                  |
| ----- | ------------------------------------------------------------------------ |
| `200` | Recursive-first chat inference result with proof, uncertainty, and trace |
| `400` | Invalid request                                                          |
| `401` | Unauthorized — missing or invalid credentials                            |
| `402` | Tenant is suspended                                                      |
| `403` | Org mismatch with authenticated scope                                    |
| `404` | Session not found                                                        |
| `429` | Rate limited — see Retry-After / X-RateLimit-Reset                       |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.nsr.stateset.com/api/v2/nsr/chat/solve' \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "api_surface": "string",
    "confidence_threshold": 7.5,
    "decompositions": [
      {
        "goal": "string",
        "subtasks": []
      }
    ],
    "facts": [
      {
        "confidence": 7.5,
        "predicate": {
          "args": null,
          "name": null,
          "negated": null
        },
        "source": "string"
      }
    ],
    "goal": "string",
    "hydrate_org_context": true,
    "include_facts": 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": 8,
    "messages": [
      {
        "content": "Two-person tent, green — replacement for damaged pole set.",
        "role": "string"
      }
    ],
    "mode": {
      "0": "f",
      "1": "a",
      "2": "s",
      "3": "t"
    },
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "rules": [
      {
        "category": "standard",
        "constraints": [],
        "description": "Two-person tent, green — replacement for damaged pole set.",
        "effect": {
          "0": "p",
          "1": "e",
          "2": "r",
          "3": "m",
          "4": "i",
          "5": "t"
        },
        "enabled": true,
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "if": [],
        "name": "Two-Person Tent",
        "priority": 1,
        "then": []
      }
    ],
    "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "target": "string"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "action_results": [
      {
        "action_type": "string",
        "details": [],
        "matched_entity_ids": [],
        "status": "pending",
        "summary": "Two-person tent, green — replacement for damaged pole set.",
        "tool_name": "string"
      }
    ],
    "action_runtime": {
      "approved_action_types": [
        "string"
      ],
      "blocked_action_types": [
        "string"
      ],
      "executed_action_types": [
        "string"
      ],
      "execution_receipt": {
        "available_action_types": [],
        "expires_at": "2026-08-31T14:22:05Z",
        "receipt_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      },
      "lifecycle_stage": "string",
      "prepared_action_types": [
        "string"
      ],
      "review_required_action_types": [
        "string"
      ]
    },
    "answer": null,
    "assistant_message": "string",
    "audit_trace": [
      {
        "description": "Two-person tent, green — replacement for damaged pole set.",
        "duration_ms": 8,
        "input": null,
        "output": null,
        "step_type": "string",
        "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ],
    "context": {
      "hydrated_entities": 8,
      "hydrated_rules": 8,
      "hydrated_triples": 8,
      "request_facts": 1,
      "request_rules": 1,
      "skipped_rule_names": [
        "string"
      ],
      "skipped_rules": 1
    },
    "cost": {
      "api_surface": "string",
      "billable_outcome": true,
      "billing_tier": "string",
      "elapsed_ms": 250,
      "estimated_cost_units": 1,
      "iterations": 8,
      "max_depth_reached": 1,
      "neural_steps": 1,
      "outcome_cost_microdollars": 1,
      "planner_steps": 1,
      "symbolic_steps": 1
    },
    "explanation": "string",
    "facts": [
      {
        "args": [],
        "confidence": 7.5,
        "predicate": "string",
        "source": "string"
      }
    ],
    "goal": "string",
    "mode": "fast",
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "proof": {
      "cited_rules": [
        "string"
      ],
      "completed_tasks": [
        "string"
      ],
      "neural_steps": 1,
      "planner_steps": 1,
      "symbolic_steps": 1
    },
    "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "success": true,
    "suggested_actions": [
      {
        "action_type": "string",
        "can_auto_execute": true,
        "execution_status": "string",
        "label": "Replacement tent pole set",
        "missing_inputs": [],
        "reason": "Two-person tent, green — replacement for damaged pole set.",
        "required_inputs": [],
        "tool_name": "string"
      }
    ],
    "tool_calls": [
      {
        "arguments": null,
        "function": "string",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "policy": {
          "confidence": null,
          "reason": null,
          "rule_conclusion": null,
          "rule_name": null
        },
        "status": "pending"
      }
    ],
    "trace": [
      {
        "description": "Two-person tent, green — replacement for damaged pole set.",
        "duration_ms": 8,
        "input": null,
        "output": null,
        "step_type": "string",
        "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ],
    "trace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "uncertainty": {
      "aleatoric": 1.5,
      "epistemic": 1.5,
      "mandatory_review": true,
      "requires_human_review": true,
      "total": 102.12
    },
    "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": 7.5,
      "proof_status": "string",
      "symbolic_step_count": 1,
      "validation_level": "string"
    }
  }
  ```
</ResponseExample>