> ## 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 /override

> Record human approval for a policy decision that requires override authority

## Endpoint

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

`/override` allows an authorized human to approve or reject a pending override request.

An override is only possible when a policy evaluation returns:

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

***

## Why Overrides Exist

Policies define normal authority boundaries.

Some situations require escalation to a higher authority.

Instead of bypassing policy, Parmana records a separate override decision made by an authorized human.

```text theme={null}
Verified Signals
        ↓
Policy Evaluation
        ↓
Policy Decision
        ↓
Pending Override
        ↓
Human Authority
        ↓
Override Resolution
```

***

## Core Principle

Overrides do not change the original policy decision.

The original decision remains immutable.

The override creates a separate authority record showing that an authorized human accepted responsibility for proceeding.

```text theme={null}
Policy Decision
      +
Human Override
      =
Execution Authorization
```

***

## Request Body

```json theme={null}
{
  "executionId": "override-test-001",
  "approved": true,
  "approvedBy": "pavan",
  "approverRole": "manager",
  "reason": "manual override validation"
}
```

***

## Fields

| Field          | Type      | Required | Description                               |
| -------------- | --------- | -------- | ----------------------------------------- |
| `executionId`  | `string`  | Yes      | Pending override execution identifier     |
| `approved`     | `boolean` | Yes      | Whether the override is approved          |
| `approvedBy`   | `string`  | Yes      | Human approving or rejecting the override |
| `approverRole` | `string`  | Yes      | Role associated with the approver         |
| `reason`       | `string`  | Yes      | Justification for the override decision   |

***

## Approval Flow

### Step 1

Policy evaluation produces:

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

***

### Step 2

Pending override is recorded.

```text theme={null}
Execution
        ↓
Pending Override
        ↓
Await Human Decision
```

***

### Step 3

Authorized human reviews the request.

```json theme={null}
{
  "approved": true,
  "approvedBy": "manager",
  "approverRole": "manager"
}
```

***

### Step 4

Parmana records a signed override record.

***

### Step 5

Parmana resolves the pending execution.

```text theme={null}
Pending Override
        ↓
Approved
        ↓
Execution Completed
```

***

## Successful Approval Response

```json theme={null}
{
  "status": "approved",
  "overrideId": "7d6f366ac1f01cd1c8657aad5bc119fc5679ac9079d53c798751f3ec0e44cc46",
  "resolution": {
    "executionId": "override-fly-001",
    "execution_fingerprint": "fedfc2e7782c166f2233227a126b3e3b6d4b3fcdf6a228209bb09a86a4722bb9",
    "signature": "...",
    "execution_state": "completed"
  }
}
```

***

## Response Fields

### status

Override result.

Possible values:

```text theme={null}
approved
rejected
```

***

### overrideId

Deterministic identifier for the override record.

***

### resolution

Resolved execution context after override approval.

Contains:

* execution information
* decision information
* provenance information
* cryptographic signature

***

## Rejection Response

If the approver rejects the override:

```json theme={null}
{
  "status": "rejected",
  "executionId": "override-test-001"
}
```

The execution remains blocked.

***

## Immutable Decision History

Overrides never rewrite policy outcomes.

Example:

### Original Policy Decision

```json theme={null}
{
  "action": "reject",
  "requires_override": true,
  "reason": "policy_requirements_not_satisfied"
}
```

### Override Decision

```json theme={null}
{
  "approved": true,
  "approvedBy": "manager"
}
```

Both records are preserved.

```text theme={null}
Original Policy Decision
            +
Override Approval
            =
Complete Audit Trail
```

***

## Human Authority

Overrides exist because policy authority and human authority are different concepts.

Policies enforce normal operating rules.

Humans retain authority to make exceptional decisions.

Parmana records both.

```text theme={null}
AI Request
      ↓
Policy Evaluation
      ↓
Requires Override
      ↓
Human Authority
      ↓
Execution
```

***

## Error Responses

### 400 Bad Request

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

Malformed request.

***

### 401 Unauthorized

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

Missing or invalid API key.

***

### 404 Pending Override Not Found

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

Specified execution does not have an active pending override.

***

### 409 Override Already Resolved

```json theme={null}
{
  "error": "Override already resolved"
}
```

Override was previously approved or rejected.

***

### 500 Internal Error

```json theme={null}
{
  "error": "Override processing failed"
}
```

Unexpected runtime failure.

***

## Example — curl

```bash theme={null}
curl -X POST https://your-runtime/override \
  -H "Authorization: Bearer $PARMANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "executionId":"override-test-001",
    "approved":true,
    "approvedBy":"manager",
    "approverRole":"manager",
    "reason":"approved after review"
  }'
```

***

## Override Auditability

Every override produces:

* Human approver identity
* Approver role
* Approval reason
* Override record
* Cryptographic signature
* Resolution evidence

This creates a verifiable record of who exercised authority and why.

***

## How Override Fits Into Parmana

```text theme={null}
Customer Request
        ↓
Verified Signals
        ↓
Parmana Evaluation
        ↓
Policy Decision
        ↓
Pending Override
        ↓
Human Approval
        ↓
Override Resolution
        ↓
Execution
        ↓
Execution Integrity Proof
```

Parmana preserves both:

> What the policy decided

and

> What the authorized human decided

without losing either record.