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

# Forward chaining endpoint with parameters

> Derives new facts by applying rules to the knowledge base. Supports fine-grained control over inference depth, iterations, and which rules to apply…

Derives new facts by applying rules to the knowledge base.
Supports fine-grained control over inference depth, iterations, and which rules to apply.
Run forward-chaining inference over the knowledge base.

**Required scope:** `write`

### Request body

`ForwardChainRequest`

<ParamField body="include_details" type="boolean">
  Include full fact details in response (subject, predicate, object)
</ParamField>

<ParamField body="limit" type="integer">
  Maximum number of results to return (default: 1000)
</ParamField>

<ParamField body="max_depth" type="integer">
  Maximum depth of rule application (default: config value, max: 100)
</ParamField>

<ParamField body="max_iterations" type="integer">
  Maximum number of inference iterations (default: config value, max: 10000)
</ParamField>

<ParamField body="rule_ids" type="string[]">
  Optional list of rule IDs to apply (if empty, applies all enabled rules)
</ParamField>

### Response

`ForwardChainResponse`

<ResponseField name="execution_time_ms" type="integer (int64)" required>
  Execution time in milliseconds
</ResponseField>

<ResponseField name="inferred_facts" type="InferredFactResponse[]" required>
  List of inferred facts

  <Expandable title="InferredFactResponse">
    <ResponseField name="confidence" type="number (double)" required>
      Confidence score of the inference
    </ResponseField>

    <ResponseField name="predicate" type="string" required>
      The predicate of the inferred fact
    </ResponseField>

    <ResponseField name="rule_id" type="string" required>
      The rule ID that produced this fact
    </ResponseField>

    <ResponseField name="substitution" type="object">
      Variable substitutions used (if applicable)
    </ResponseField>

    <ResponseField name="terms" type="string[]" required>
      Arguments/terms of the fact
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="iterations_used" type="integer" required>
  Number of iterations performed
</ResponseField>

<ResponseField name="rules_fired" type="string[]" required>
  Rules that fired during inference
</ResponseField>

<ResponseField name="total_inferred" type="integer" required>
  Total number of facts inferred (before limit)
</ResponseField>

### Status codes

| Code  | Meaning                                            |
| ----- | -------------------------------------------------- |
| `200` | Inference completed                                |
| `400` | Invalid parameters                                 |
| `401` | Unauthorized — missing or invalid credentials      |
| `403` | Forbidden — the key/token lacks the required scope |
| `429` | Rate limited — see Retry-After / X-RateLimit-Reset |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.nsr.stateset.com/api/v1/forward-chain' \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "include_details": true,
    "limit": 20,
    "max_depth": 1,
    "max_iterations": 8,
    "rule_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "execution_time_ms": 250,
    "inferred_facts": [
      {
        "confidence": 7.5,
        "predicate": "string",
        "rule_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "substitution": {},
        "terms": []
      }
    ],
    "iterations_used": 8,
    "rules_fired": [
      "string"
    ],
    "total_inferred": 1
  }
  ```
</ResponseExample>