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

# SandboxPolicyEvaluate

> **Required scope:** write

**Required scope:** `write`

### Request body

`SandboxPolicyRequest`

<ParamField body="candidate" type="SandboxActionCandidate" />

<ParamField body="context" type="SandboxPolicyContext" />

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

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

<ParamField body="phase" type="SandboxPolicyPhase" />

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

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

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

### Response

`SandboxPolicyApiResponse`

<ResponseField name="evaluation" type="SandboxPolicyEvaluation" required>
  <Expandable title="SandboxPolicyEvaluation">
    <ResponseField name="canonical_action" type="CanonicalSandboxAction" required>
      <Expandable title="CanonicalSandboxAction">
        <ResponseField name="desktop_os" type="string" />

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

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

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

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

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

    <ResponseField name="evidence" type="SandboxPolicyEvidence[]" required>
      <Expandable title="SandboxPolicyEvidence">
        <ResponseField name="key" type="string" required />

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

    <ResponseField name="expected_effects" type="SandboxExpectedEffects" required>
      <Expandable title="SandboxExpectedEffects">
        <ResponseField name="egress_domains" type="string[]" required />

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

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

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

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

    <ResponseField name="proof_trace" type="SandboxProofStep[]" required>
      <Expandable title="SandboxProofStep">
        <ResponseField name="detail" type="string" required />

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

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

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

    <ResponseField name="rewritten_action" type="object">
      <Expandable title="rewritten_action">
        <ResponseField name="desktop_os" type="string" />

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

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

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

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

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

    <ResponseField name="rule_verdict" type="SandboxPolicyVerdict" required />

    <ResponseField name="triggered_rules" type="SandboxPolicyRuleMatch[]" required>
      <Expandable title="SandboxPolicyRuleMatch">
        <ResponseField name="reason" type="string" required />

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

        <ResponseField name="verdict" type="SandboxPolicyVerdict" required />

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

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

<ResponseField name="final_verdict" type="SandboxPolicyVerdict" required />

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

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

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

<ResponseField name="machine_proof" type="SandboxMachineProofNode[]" required>
  <Expandable title="SandboxMachineProofNode">
    <ResponseField name="input" type="string" required />

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

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

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

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

<ResponseField name="machine_verdict" type="SandboxPolicyVerdict" required />

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

### Status codes

| Code  | Meaning                                            |
| ----- | -------------------------------------------------- |
| `200` | Sandbox policy evaluation result                   |
| `400` | Invalid request                                    |
| `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` | Internal server error                              |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.nsr.stateset.com/api/v1/policy/sandbox/evaluate' \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "candidate": {
      "action": {
        "desktop_os": "string",
        "image": "https://cdn.example.com/products/tent-2p.jpg",
        "isolation": "string",
        "timeout_seconds": 250,
        "type": "create_sandbox"
      },
      "payload": null,
      "raw_text": "string",
      "route": "string",
      "tool_name": "string"
    },
    "context": {
      "active_repl_sessions": [
        "string"
      ],
      "allowed_egress_domains": [
        "string"
      ],
      "allowed_read_roots": [
        "string"
      ],
      "allowed_write_roots": [
        "string"
      ],
      "budget_available": true,
      "enabled_mcp_servers": [
        "string"
      ],
      "gui_grounded": true,
      "mounted_secrets": [
        "YOUR_API_KEY"
      ],
      "requested_runtime": "string",
      "runtime_class": "string",
      "sandbox_role": "string",
      "sandbox_state": "string",
      "workspace_root": "string"
    },
    "observed": {
      "changed_paths": [
        "string"
      ],
      "contacted_domains": [
        "string"
      ],
      "exit_code": 1,
      "output_truncated": true
    },
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "phase": "admission",
    "sandbox_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "evaluation": {
      "canonical_action": {
        "desktop_os": "string",
        "image": "https://cdn.example.com/products/tent-2p.jpg",
        "isolation": "string",
        "timeout_seconds": 250,
        "type": "create_sandbox"
      },
      "canonical_action_hash": "string",
      "evidence": [
        {
          "key": null,
          "value": null
        }
      ],
      "expected_effects": {
        "egress_domains": [],
        "may_execute_code": true,
        "recommended_runtime": "string",
        "requires_confirmation": true,
        "touched_paths": []
      },
      "proof_trace": [
        {
          "detail": null,
          "outcome": null,
          "stage": null
        }
      ],
      "recommended_runtime": "string",
      "rewritten_action": {
        "desktop_os": "string",
        "image": "https://cdn.example.com/products/tent-2p.jpg",
        "isolation": "string",
        "timeout_seconds": 250,
        "type": "create_sandbox"
      },
      "rule_score": 8,
      "rule_verdict": "allow",
      "triggered_rules": [
        {
          "reason": null,
          "rule_id": null,
          "verdict": null,
          "weight": null
        }
      ]
    },
    "evidence_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "final_verdict": "allow",
    "grounded_inputs": [
      "string"
    ],
    "machine_confidence": 7.5,
    "machine_override": true,
    "machine_proof": [
      {
        "input": "string",
        "position": 1,
        "symbol": "string",
        "value": "49.00"
      }
    ],
    "machine_score": 8,
    "machine_verdict": "allow",
    "processing_time_ms": 250
  }
  ```
</ResponseExample>