> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kernite.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute API

> POST /execute and POST /v1/execute.

Use execute endpoints as synchronous write guards.

* `POST /execute`
* `POST /v1/execute`

Decision values are only:

* `approved`
* `denied`

Recommended integration pattern:

1. Validate/normalize input.
2. Evaluate decision.
3. Mutate only on `approved`.
4. Persist `ctx_id`, `trace_hash`, and reason metadata.

## Library Quick Start (Python)

```python theme={null}
from kernite import evaluate_execute

request = {
    "workspace_id": "workspace-demo",
    "principal": {"type": "token", "id": "api:ops-bot"},
    "object_type": "document",
    "operation": "create",
    "payload": {"title": "Q1 Plan"},
}
result = evaluate_execute(request, idempotency_key="req-001")

decision = result["data"]["decision"]
trace_hash = result["data"]["trace_hash"]  # persist with your write/audit record
reason_codes = result["data"]["reason_codes"]
```

## Request Example (Denied)

In v1, an `allow` policy is approved only if all its rules pass.
Any rule failure produces `denied` with structured reasons.

```json theme={null}
{
  "workspace_id": "workspace-demo",
  "principal": {
    "type": "token",
    "id": "api:ops-bot"
  },
  "object_type": "document",
  "operation": "create",
  "payload": {},
  "policy_context": {
    "governed": true,
    "selected_policies": [
      {
        "policy_key": "document_create_default",
        "policy_version": 1,
        "effect": "allow",
        "rules": [
          {
            "rule_key": "require_title",
            "rule_definition": {
              "type": "required_fields",
              "fields": ["title"]
            },
            "reason_code": "missing_required_fields",
            "reason_message": "title is required."
          }
        ]
      }
    ]
  }
}
```

## Response Shape (Denied)

```json theme={null}
{
  "ctx_id": "ctx_...",
  "message": "Denied by governance policy.",
  "data": {
    "decision": "denied",
    "reason_codes": ["missing_required_fields"],
    "reasons": [
      {
        "code": "missing_required_fields",
        "message": "title is required.",
        "rule_key": "require_title",
        "field_path": "payload.title",
        "details": {
          "missing_fields": ["title"]
        }
      }
    ],
    "policy_selection_reason_code": "policy_selected_workspace_default",
    "policy": {
      "policy_key": "document_create_default",
      "policy_version": 1
    },
    "trace_hash": "sha256:...",
    "idempotency_key": "..."
  }
}
```

## Response Shape (Approved)

```json theme={null}
{
  "ctx_id": "ctx_...",
  "message": "Approved by governance policy.",
  "data": {
    "decision": "approved",
    "reason_codes": [],
    "reasons": [],
    "policy_selection_reason_code": "policy_selected_workspace_default",
    "policy": {
      "policy_key": "document_create_default",
      "policy_version": 1
    },
    "trace_hash": "sha256:...",
    "idempotency_key": "..."
  }
}
```

## Policy Context Model

`policy_context` is optional, but recommended for production.
Kernite evaluates policies supplied in `policy_context.selected_policies`.
In OSS mode, Kernite does not fetch policy state from storage.

Main fields:

* `governed` (bool): request is enforced as governed scope
* `selected_policies` (array): policies selected by your resolver
* `governed_scopes` (array): optional scope list (`object_type` + `operation`)
* `policy_selection_reason_code` (string): explicit selection reason

Default behavior:

* governed + no selected policy => `denied` with `no_matching_policy`
* not governed + no selected policy => `approved` with `out_of_scope_phase1`

For full contract invariants, see `/concepts/compatibility`.