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

# Handler for GET /api/v1/kb/diff

> **Required scope:** read

**Required scope:** `read`

### Query parameters

<ParamField query="from" type="string" required>
  RFC3339 start timestamp
</ParamField>

<ParamField query="to" type="string" required>
  RFC3339 end timestamp
</ParamField>

<ParamField query="org_id" type="string">
  Optional org filter
</ParamField>

### Response

`KBDiffResponse`

<ResponseField name="constraint_violations" type="ConstraintViolationDiffSection" required>
  <Expandable title="ConstraintViolationDiffSection">
    <ResponseField name="introduced" type="ConstraintViolationDiffItem[]" required>
      <Expandable title="ConstraintViolationDiffItem">
        <ResponseField name="constraint_id" type="string" required />

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

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

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

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

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

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

    <ResponseField name="resolved" type="ConstraintViolationDiffItem[]" required>
      <Expandable title="ConstraintViolationDiffItem">
        <ResponseField name="constraint_id" type="string" required />

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

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

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

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

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

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

<ResponseField name="entities" type="EntityDiffSection" required>
  <Expandable title="EntityDiffSection">
    <ResponseField name="added" type="EntityDiffItem[]" required>
      <Expandable title="EntityDiffItem">
        <ResponseField name="entity_type" type="string" required />

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

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

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

    <ResponseField name="removed" type="EntityDiffItem[]" required>
      <Expandable title="EntityDiffItem">
        <ResponseField name="entity_type" type="string" required />

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

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

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

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

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

<ResponseField name="rules" type="RuleDiffSection" required>
  <Expandable title="RuleDiffSection">
    <ResponseField name="added" type="RuleDiffItem[]" required>
      <Expandable title="RuleDiffItem">
        <ResponseField name="body_predicates" type="string[]" required />

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

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

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

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

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

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

        <ResponseField name="priority" type="integer (int32)" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="modified" type="ModifiedRuleDiffItem[]" required>
      <Expandable title="ModifiedRuleDiffItem">
        <ResponseField name="after" type="RuleDiffItem" required />

        <ResponseField name="before" type="RuleDiffItem" required />

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

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

    <ResponseField name="removed" type="RuleDiffItem[]" required>
      <Expandable title="RuleDiffItem">
        <ResponseField name="body_predicates" type="string[]" required />

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

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

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

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

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

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

        <ResponseField name="priority" type="integer (int32)" required />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="snapshots" type="KBDiffSnapshots" required>
  <Expandable title="KBDiffSnapshots">
    <ResponseField name="from" type="KBSnapshot" required>
      <Expandable title="KBSnapshot">
        <ResponseField name="as_of" type="string (date-time)" required />

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

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

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

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

    <ResponseField name="to" type="KBSnapshot" required>
      <Expandable title="KBSnapshot">
        <ResponseField name="as_of" type="string (date-time)" required />

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

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

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

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

<ResponseField name="summary" type="KBDiffSummary" required>
  <Expandable title="KBDiffSummary">
    <ResponseField name="added_entities" type="integer" required />

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

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

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

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

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

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

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

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

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

<ResponseField name="triples" type="TripleDiffSection" required>
  <Expandable title="TripleDiffSection">
    <ResponseField name="added" type="TripleDiffItem[]" required>
      <Expandable title="TripleDiffItem">
        <ResponseField name="confidence" type="number (float)" required />

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

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

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

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

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

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

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

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

    <ResponseField name="removed" type="TripleDiffItem[]" required>
      <Expandable title="TripleDiffItem">
        <ResponseField name="confidence" type="number (float)" required />

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

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

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

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

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

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

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

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

<ResponseField name="truncated" type="boolean" required>
  True when any section was truncated by the `limit` parameter
</ResponseField>

### Status codes

| Code  | Meaning                                            |
| ----- | -------------------------------------------------- |
| `200` | Diff between two KB snapshots                      |
| `400` | Invalid timestamp window                           |
| `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 GET \
    --url 'https://api.nsr.stateset.com/api/v1/kb/diff' \
    --header 'X-API-Key: YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "constraint_violations": {
      "introduced": [
        {
          "constraint_id": null,
          "constraint_name": null,
          "details": null,
          "entities": null,
          "entity_names": null,
          "message": null,
          "severity": null
        }
      ],
      "resolved": [
        {
          "constraint_id": null,
          "constraint_name": null,
          "details": null,
          "entities": null,
          "entity_names": null,
          "message": null,
          "severity": null
        }
      ]
    },
    "entities": {
      "added": [
        {
          "entity_type": null,
          "id": null,
          "name": null,
          "org_id": null
        }
      ],
      "removed": [
        {
          "entity_type": null,
          "id": null,
          "name": null,
          "org_id": null
        }
      ]
    },
    "from": "string",
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "rules": {
      "added": [
        {
          "body_predicates": null,
          "confidence": null,
          "enabled": null,
          "head_predicate": null,
          "id": null,
          "name": null,
          "org_id": null,
          "priority": null
        }
      ],
      "modified": [
        {
          "after": null,
          "before": null,
          "id": null,
          "name": null
        }
      ],
      "removed": [
        {
          "body_predicates": null,
          "confidence": null,
          "enabled": null,
          "head_predicate": null,
          "id": null,
          "name": null,
          "org_id": null,
          "priority": null
        }
      ]
    },
    "snapshots": {
      "from": {
        "as_of": "2026-08-31T14:22:05Z",
        "entity_count": 1,
        "events_applied": 1,
        "rule_count": 1,
        "triple_count": 1
      },
      "to": {
        "as_of": "2026-08-31T14:22:05Z",
        "entity_count": 1,
        "events_applied": 1,
        "rule_count": 1,
        "triple_count": 1
      }
    },
    "summary": {
      "added_entities": 1,
      "added_rules": 1,
      "added_triples": 1,
      "introduced_constraint_violations": 1,
      "modified_rules": 1,
      "removed_entities": 1,
      "removed_rules": 1,
      "removed_triples": 1,
      "resolved_constraint_violations": 1
    },
    "to": "string",
    "triples": {
      "added": [
        {
          "confidence": null,
          "object": null,
          "object_name": null,
          "org_id": null,
          "predicate": null,
          "subject": null,
          "subject_name": null,
          "valid_from": null,
          "valid_to": null
        }
      ],
      "removed": [
        {
          "confidence": null,
          "object": null,
          "object_name": null,
          "org_id": null,
          "predicate": null,
          "subject": null,
          "subject_name": null,
          "valid_from": null,
          "valid_to": null
        }
      ]
    },
    "truncated": true
  }
  ```
</ResponseExample>