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

# POST /evaluate

> Evaluate verified signals against a policy and produce a signed attestation

## Endpoint

```http theme={null}
POST /evaluate
Content-Type: application/json
Authorization: Bearer <api-key>
```

`/evaluate` is the primary Parmana runtime endpoint.

It evaluates verified signals against a policy, produces a decision, and returns a signed attestation.

The attestation can then be:

* Used as authorization evidence before execution
* Submitted to an override workflow when required
* Independently verified by auditors
* Confirmed after execution using `/confirm-execution`

***

## Core Principle

Parmana does not verify facts.

External systems are responsible for collecting and verifying signals.

Parmana evaluates verified signals against policy and returns a signed decision.

```text theme={null}
Customer Request
        ↓
System Verifies Facts
        ↓
Verified Signals
        ↓
Parmana Evaluation
        ↓
Decision
        ↓
Signed Attestation
```

<Note>
  Parmana does not trust AI-generated outputs.

  Only verified signals should be submitted for evaluation.
</Note>

***

## Request Body

```json theme={null}
{
  "executionId": "claim-001",
  "policyId": "claims-approval",
  "policyVersion": "1.0.0",
  "verifiedSignals": {
    "insurance_active": true,
    "risk_score": 10,
    "vip_customer": false,
    "claim_amount": 100
  }
}
```

### Fields

| Field             | Type     | Required | Description                                    |
| ----------------- | -------- | -------- | ---------------------------------------------- |
| `executionId`     | `string` | Yes      | Unique business identifier for this evaluation |
| `policyId`        | `string` | Yes      | Policy to evaluate                             |
| `policyVersion`   | `string` | Yes      | Policy version                                 |
| `verifiedSignals` | `object` | Yes      | Facts already verified by the calling system   |

***

## What Parmana Does

When a request is submitted, Parmana:

1. Loads the requested policy
2. Loads the policy schema
3. Validates the verified signals
4. Evaluates policy rules
5. Produces a decision
6. Creates a signed attestation
7. Returns the attestation

```text theme={null}
Policy
   ↓
Policy Schema
   ↓
Verified Signals
   ↓
Evaluation
   ↓
Decision
   ↓
Signed Attestation
```

***

## Response States

The response can return one of three states:

### Approved

The policy authorizes the action.

```json theme={null}
{
  "status": "approved",
  "requires_override": false,
  "attestation": {
    "...": "..."
  }
}
```

### Pending Override

The policy does not authorize the action directly but allows escalation to a human authority.

```json theme={null}
{
  "status": "pending_override",
  "requires_override": true,
  "attestation": {
    "...": "..."
  }
}
```

### Rejected

The policy rejects the request.

```json theme={null}
{
  "status": "rejected",
  "requires_override": false,
  "attestation": {
    "...": "..."
  }
}
```

***

## Example Response

```json theme={null}
{
  "status": "approved",
  "requires_override": false,
  "attestation": {
    "executionId": "claim-001",
    "execution_fingerprint": "fedfc2e7782c166f2233227a126b3e3b6d4b3fcdf6a228209bb09a86a4722bb9",
    "policyId": "claims-approval",
    "policyVersion": "1.0.0",
    "schemaVersion": "1.0.0",
    "runtimeVersion": "1.0.0",
    "signalsHash": "fedfc2e7782c166f2233227a126b3e3b6d4b3fcdf6a228209bb09a86a4722bb9",
    "decision": {
      "status": "decided",
      "outcome": {
        "action": "approve",
        "requires_override": false,
        "reason": "standard_approval"
      }
    },
    "execution_state": "completed",
    "runtimeHash": "f55711983deddba4b6ad3d9d63017980641d242142e8e6e0602f77e0f54c4eb0",
    "provenance": {
      "provenanceVersion": "PARMANA_PROVENANCE_V1",
      "bundleHash": "...",
      "manifestHash": "...",
      "trustRootVersion": "1.0.0",
      "signerKeyId": "parmanasystems-root-2026"
    },
    "signature": "..."
  }
}
```

***

## Attestation

The attestation is Parmana's signed authorization record.

It contains:

* The policy that was evaluated
* The verified signal fingerprint
* The decision outcome
* Runtime provenance
* Cryptographic signature

Store the attestation exactly as returned.

It is required for:

* Verification
* Override workflows
* Execution confirmation
* Audit and compliance

***

## Override Workflow

When:

```json theme={null}
{
  "status": "pending_override",
  "requires_override": true
}
```

the action is not authorized for execution.

A human authority must review the request using:

```http theme={null}
POST /override
```

before execution can proceed.

***

## Execution Confirmation

After the action is executed, submit the attestation to:

```http theme={null}
POST /confirm-execution
```

to produce an Execution Integrity Proof.

```text theme={null}
Attestation
      ↓
Execution
      ↓
Confirm Execution
      ↓
Execution Integrity Proof
```

***

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "error": "Invalid request"
}
```

Request body is malformed or missing required fields.

### 401 Unauthorized

```json theme={null}
{
  "error": "Unauthorized"
}
```

API key is missing or invalid.

### 404 Policy Not Found

```json theme={null}
{
  "error": "Policy not found"
}
```

Requested policy version does not exist.

### 422 Validation Failed

```json theme={null}
{
  "error": "Signal validation failed"
}
```

Submitted verified signals do not satisfy the policy schema.

### 500 Internal Error

```json theme={null}
{
  "error": "Evaluation failed"
}
```

Unexpected runtime error.

***

## Example — curl

```bash theme={null}
curl -X POST https://your-runtime/evaluate \
  -H "Authorization: Bearer $PARMANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "executionId":"claim-001",
    "policyId":"claims-approval",
    "policyVersion":"1.0.0",
    "verifiedSignals":{
      "insurance_active":true,
      "risk_score":10,
      "vip_customer":false,
      "claim_amount":100
    }
  }'
```

***

## How Evaluate Fits Into Parmana

```text theme={null}
Customer Chooses Task
        ↓
Task → Policy Mapping
        ↓
Policy Schema
        ↓
Verified Signals
        ↓
Parmana Evaluation
        ↓
Decision + Attestation
        ↓
Execution or Override
        ↓
Execution Integrity Proof
```

Parmana answers one question:

> Did the right policy authorize this action based on verified facts?

If yes, execute.

If not, don't execute.