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

# OpenAI-compatible chat completions endpoint backed by the recursive v2

> solver. **Required scope:** write

solver.

**Required scope:** `write`

### Request body

`object`

<ParamField body="model" type="string">
  Model identifier. Selects the NSR v2 mode when it matches `nsr-v2-fast`, `nsr-v2-accurate`, or `nsr-v2-safe`.
</ParamField>

<ParamField body="messages" type="object[]" required>
  Conversation messages in OpenAI format.
</ParamField>

<ParamField body="tools" type="object[]">
  Tool/function definitions. Used to filter which `tool_calls` are returned.
</ParamField>

<ParamField body="tool_choice" type="string">
  Tool selection mode (`auto`, `none`, `required`) or a specific function as `&#123;'type': 'function', 'function': &#123;'name': …&#125;&#125;`.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature. Accepted for compatibility, ignored by NSR v2.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum tokens for the response. Accepted for compatibility.
</ParamField>

<ParamField body="response_format" type="object">
  Deterministic structured output contract layered on top of the recursive answer.
</ParamField>

<ParamField body="session_id" type="string">
  Optional caller-supplied session identifier forwarded to the recursive solver.
</ParamField>

<ParamField body="goal" type="string">
  Optional explicit root goal for the recursive solver.
</ParamField>

<ParamField body="target" type="string">
  Optional target hint for the recursive solver.
</ParamField>

<ParamField body="facts" type="object[]">
  Request-scoped facts injected into the recursive working set.
</ParamField>

<ParamField body="rules" type="object[]">
  Request-scoped rules injected into the recursive working set.
</ParamField>

<ParamField body="decompositions" type="object[]">
  Request-scoped planner overrides for explicit recursive decompositions.
</ParamField>

<ParamField body="hydrate_org_context" type="boolean">
  When false, skip org knowledge-base hydration.
</ParamField>

<ParamField body="kb_limits" type="object">
  Optional per-request hydration limits for the org context.
</ParamField>

<ParamField body="max_depth" type="integer">
  Optional recursion depth override.
</ParamField>

<ParamField body="max_iterations" type="integer">
  Optional iteration budget override.
</ParamField>

<ParamField body="confidence_threshold" type="number">
  Optional confidence threshold override.
</ParamField>

<ParamField body="stream" type="boolean">
  When true, emit OpenAI-style SSE chunks.
</ParamField>

<ParamField body="stream_options" type="object">
  Optional stream controls.
</ParamField>

<ParamField body="n" type="integer">
  Accepted for compatibility. NSR always returns a single choice.
</ParamField>

<ParamField body="include_nsr_metadata" type="boolean">
  When true, include the full recursive v2 payload under `x_nsr`.
</ParamField>

<ParamField body="api_surface" type="string">
  Internal surface label forwarded to the recursive solver for metering.
</ParamField>

### Response

`object`

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

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

<ResponseField name="created" type="integer" required>
  Unix timestamp (seconds).
</ResponseField>

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

<ResponseField name="choices" type="object[]" required>
  <Expandable title="choices">
    <ResponseField name="index" type="integer" required />

    <ResponseField name="message" type="object" required>
      <Expandable title="message">
        <ResponseField name="role" type="string" required />

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

        <ResponseField name="tool_calls" type="object[]">
          Present only when tool calls were produced.
        </ResponseField>
      </Expandable>
    </ResponseField>

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

<ResponseField name="usage" type="object" required>
  <Expandable title="usage">
    <ResponseField name="prompt_tokens" type="integer" required />

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

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

<ResponseField name="system_fingerprint" type="string" required>
  Stable fingerprint of the backend configuration that served this request. Lets clients detect backend changes.
</ResponseField>

<ResponseField name="x_nsr" type="object">
  Full recursive NSR payload. Present only when `include_nsr_metadata` is true.
</ResponseField>

### Status codes

| Code | Meaning |
| - | - |
| `200` | OpenAI-compatible chat completion. With `stream: true` the body is a `text/event-stream` of OpenAI-style chunks instead. |
| `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/v1/chat/completions' \
    --header "X-API-Key: $STATESET_NSR_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "string",
    "messages": [
      {
        "role": "string",
        "content": "Two-person tent, green — replacement for damaged pole set.",
        "tool_calls": [],
        "tool_call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ],
    "tools": [
      {}
    ],
    "tool_choice": "string",
    "temperature": 1.5,
    "max_tokens": 1,
    "response_format": {
      "type": "standard",
      "json_schema": {
        "name": "Two-Person Tent",
        "schema": {},
        "strict": true
      }
    },
    "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "goal": "string",
    "target": "string",
    "facts": [
      {}
    ],
    "rules": [
      {}
    ],
    "decompositions": [
      {}
    ],
    "hydrate_org_context": true,
    "kb_limits": {},
    "max_depth": 1,
    "max_iterations": 8,
    "confidence_threshold": 7.5,
    "stream": true,
    "stream_options": {
      "include_usage": true
    },
    "n": 1,
    "include_nsr_metadata": true,
    "api_surface": "string"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "object": "string",
    "created": 1,
    "model": "string",
    "choices": [
      {
        "index": 1,
        "message": {
          "role": null,
          "content": null,
          "tool_calls": null
        },
        "finish_reason": "string"
      }
    ],
    "usage": {
      "prompt_tokens": 1,
      "completion_tokens": 1,
      "total_tokens": 1
    },
    "system_fingerprint": "string",
    "x_nsr": {}
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.