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

# OpenAPI Reference

> Complete endpoint reference for the Parmana governance server

## Base URL

```
http://localhost:3000
```

All requests require `Authorization: Bearer <api-key>` unless noted.

***

## POST /execute

Verify authority against a signed policy bundle before execution.

**Request:**

```json theme={null}
{
  "executionId": "string",      // required — unique business transaction ID
  "policyId": "string",         // required
  "policyVersion": "string",    // required
  "signals": {}                 // required — object matching policy signalsSchema
}
```

**Response 200:**

```json theme={null}
{
  "status": "string",             // "approved" | execution_state
  "requires_override": "boolean",
  "attestation": {
    "executionId": "string",
    "execution_fingerprint": "string",
    "policyId": "string",
    "policyVersion": "string",
    "schemaVersion": "string",
    "runtimeVersion": "string",
    "runtimeHash": "string",
    "decision": {
      "action": "string",
      "requires_override": "boolean",
      "reason": "string"
    },
    "execution_state": "completed | pending_override",
    "signalsHash": "string",
    "bundleHash": "string",
    "manifestHash": "string",
    "manifestSignature": "string",
    "trustRootVersion": "string",
    "signerKeyId": "string",
    "evaluatorHash": "string",
    "evaluatorSemanticHash": "string",
    "evaluatorArtifactHash": "string",
    "releaseManifestHash": "string",
    "signature": "string"
  }
}
```

**Errors:** 400 (missing fields), 401 (auth), 413 (body too large), 422 (replay / policy not found / signals invalid), 429 (rate limit), 503 (runtime not configured)

***

## POST /verify

Verify an `ExecutionAttestation`. Stateless — requires only the attestation and public key.

**Request:** Full `ExecutionAttestation` object (see /execute response)

**Response 200:**

```json theme={null}
{
  "valid": "boolean",
  "checks": {
    "signature": "verified | failed | unknown",
    "runtime": "verified | failed | unknown",
    "schema": "verified | failed | unknown"
  }
}
```

**Errors:** 400, 401, 503

***

## POST /evaluate

Dry-run policy evaluation. No attestation produced, no side effects.

**Request:**

```json theme={null}
{
  "policyId": "string",
  "policyVersion": "string",
  "signals": {}
}
```

**Response 200:**

```json theme={null}
{
  "wouldDecide": "string",
  "ruleMatched": "string",
  "reason": "string",
  "signalsValidated": "boolean"
}
```

**Errors:** 400, 401, 422

***

## POST /simulate

Full pipeline dry run. No signing, no replay write, no audit record.

**Request:**

```json theme={null}
{
  "policyId": "string",
  "policyVersion": "string",
  "signals": {}
}
```

**Response 200:**

```json theme={null}
{
  "simulation": true,
  "decision": {
    "action": "string",
    "reason": "string",
    "ruleMatched": "string"
  },
  "signalsValidated": "boolean",
  "policyLoaded": "boolean",
  "wouldSign": "boolean",
  "attestationPreview": {}
}
```

**Errors:** 400, 401, 422

***

## POST /override

Approve or reject a pending override decision.

**Request:**

```json theme={null}
{
  "executionId": "string",    // required
  "approved": "boolean",      // required
  "approvedBy": "string",     // required
  "approverRole": "string",   // required
  "reason": "string"          // required
}
```

**Response 200 (approved):**

```json theme={null}
{
  "status": "approved",
  "overrideId": "string",
  "resolution": {
    "status": "executed",
    "execution_fingerprint": "string",
    "signature": "string"
  }
}
```

**Response 200 (rejected):**

```json theme={null}
{
  "status": "rejected",
  "executionId": "string"
}
```

**Errors:** 400, 401, 404 (no pending override), 409 (already resolved), 503

***

## POST /confirm-execution

Create a post-execution integrity proof binding the action taken to the authorized attestation.

**Request:**

```json theme={null}
{
  "attestation": {},            // required — ExecutionAttestation
  "executedAction": {
    "actionType": "string",     // required
    "actionId": "string",       // required
    "actionTimestamp": "string",// required — ISO 8601
    "actionDetails": {}         // optional
  },
  "timeWindowSeconds": "number" // optional
}
```

**Response 200:**

```json theme={null}
{
  "matched": "boolean",
  "executionId": "string",
  "withinTimeWindow": "boolean",
  "proof": "string"
}
```

***

## GET /health

Runtime health. No authentication required.

**Response 200:**

```json theme={null}
{
  "status": "ok",
  "runtimeVersion": "string",
  "runtimeHash": "string",
  "verification": "ok | error",
  "audit_db": "boolean",
  "signing_mode": "env | disk",
  "capabilities": ["string"],
  "supportedSchemaVersions": ["string"]
}
```

***

## GET /runtime/manifest

Runtime manifest — version, hash, capabilities.

**Response 200:**

```json theme={null}
{
  "version": "string",
  "runtimeHash": "string",
  "capabilities": ["string"],
  "supportedSchemaVersions": ["string"],
  "startedAt": "string"
}
```

***

## GET /runtime/capabilities

Active capabilities list.

**Response 200:**

```json theme={null}
{
  "capabilities": ["string"]
}
```

***

## GET /audit/decisions

Paginated list of decisions.

**Query parameters:** `limit` (int), `offset` (int), `policyId` (string), `decision` (string), `from` (ISO 8601), `to` (ISO 8601)

**Response 200:** Array of `DecisionRow` — see [Audit Schema](/reference/audit-schema)

***

## GET /audit/decisions/:executionId

Full decision detail including attestation JSON.

**Response 200:** `DecisionDetail` — see [Audit Schema](/reference/audit-schema)

**Errors:** 404 (not found)

***

## GET /audit/stats

Aggregate counts.

**Response 200:**

```json theme={null}
{
  "total_decisions": "string",
  "decisions_today": "string",
  "total_verifications": "string",
  "valid_verifications": "string",
  "invalid_verifications": "string",
  "total_security_events": "string",
  "total_api_calls": "string"
}
```

***

## GET /audit/security

Security events.

**Query parameters:** `from` (ISO 8601), `to` (ISO 8601), `limit` (int)

**Response 200:** Array of `SecurityEventRow` — see [Audit Schema](/reference/audit-schema)