> ## 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.

# Execute a reasoning query using the NSR engine.

> This is the primary endpoint for performing neural-symbolic reasoning…

This is the primary endpoint for performing neural-symbolic reasoning.
It accepts a query string and optional parameters to control the reasoning
process, including strategy selection and configuration overrides.
**Request Body**

* `query`: The question or goal to reason about
* `strategy`: Optional reasoning strategy (SymbolicFirst, NeuralFirst, Hybrid, Ensemble, Cascading)
* `session_id`: Optional session ID for context continuity
* `options`: Optional configuration overrides (max\_depth, confidence\_threshold, neural\_weight)
  **Response**
  Returns a `ReasonResponse` containing:
* `answer`: The reasoning result
* `confidence`: Confidence score (0.0-1.0)
* `explanation`: Human-readable explanation of the reasoning path
* `session_id`: Session ID for follow-up queries
  **Errors**
* `400 Bad Request`: Invalid input (empty query, exceeds max length)
* `500 Internal Server Error`: Reasoning engine failure
  **Example**
  **Example (curl)**

```bash theme={null}
curl -X POST 'https://api.nsr.stateset.com/api/v1/reason' \
-H 'X-API-Key: your-api-key' \
-H 'Content-Type: application/json' \
-d '{'query': 'What are the properties of entity X?', 'strategy': 'hybrid'}'
```

Execute a reasoning query.

**Required scope:** `write`

### Request body

`ReasonRequest`

<ParamField body="as_of_timestamp" type="string">
  Optional RFC3339 timestamp for time-travel reasoning against a historical KB snapshot
</ParamField>

<ParamField body="include_evidence" type="boolean">
  Include evidence/citation objects in the response
</ParamField>

<ParamField body="ir" type="object">
  Optional pre-compiled IR. Provide exactly one of `query` or `ir`.
</ParamField>

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

<ParamField body="query" type="string">
  The query to reason about
</ParamField>

<ParamField body="session_id" type="string">
  Session ID for context persistence
</ParamField>

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

### Response

`ReasonResponse`

<ResponseField name="answer" type="string">
  The answer to the query
</ResponseField>

<ResponseField name="confidence" type="number (float)" required>
  Confidence score (0.0 to 1.0)
</ResponseField>

<ResponseField name="evidence" type="any[]">
  Optional evidence/citation objects supporting the answer
</ResponseField>

<ResponseField name="explanation" type="object">
  Detailed explanation of reasoning steps
</ResponseField>

<ResponseField name="metadata" type="ResponseMetadata" required>
  <Expandable title="ResponseMetadata">
    <ResponseField name="facts_used" type="integer" required>
      Number of facts used in reasoning
    </ResponseField>

    <ResponseField name="query_time_ms" type="integer (int64)" required>
      Query processing time in milliseconds
    </ResponseField>

    <ResponseField name="rules_fired" type="integer" required>
      Number of rules fired during inference
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reasoning_type" type="string" required>
  Type of reasoning used (symbolic, neural, hybrid)
</ResponseField>

<ResponseField name="session_id" type="string">
  Session ID for follow-up queries
</ResponseField>

### Status codes

| Code  | Meaning                                             |
| ----- | --------------------------------------------------- |
| `200` | Reasoning completed successfully                    |
| `400` | Invalid request - empty query or exceeds max length |
| `401` | Unauthorized — missing or invalid credentials       |
| `403` | Forbidden — the key/token lacks the required scope  |
| `429` | Rate limited — see Retry-After / X-RateLimit-Reset  |
| `500` | Reasoning engine failure                            |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.nsr.stateset.com/api/v1/reason' \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "as_of_timestamp": "2026-08-31T14:22:05Z",
    "include_evidence": true,
    "ir": null,
    "options": {
      "confidence_threshold": 7.5,
      "include_explanation": true,
      "max_depth": 1,
      "neural_weight": 1.2
    },
    "query": "string",
    "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "strategy": {
      "0": "s",
      "1": "y",
      "2": "m",
      "3": "b",
      "4": "o",
      "5": "l",
      "6": "i",
      "7": "c",
      "8": "_",
      "9": "f",
      "10": "i",
      "11": "r",
      "12": "s",
      "13": "t"
    }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "answer": "string",
    "confidence": 7.5,
    "evidence": [],
    "explanation": null,
    "metadata": {
      "facts_used": 1,
      "query_time_ms": 250,
      "rules_fired": 1
    },
    "reasoning_type": "string",
    "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
  ```
</ResponseExample>