API Reference

Parmana Systems Runtime REST API — execute governed decisions and verify attestations

The Parmana Systems server (@parmanasystems/server) exposes a Fastify REST API. The full OpenAPI 3.0 spec lives at openapi.json in the repository root and is referenced by this site’s mint.json.

Base URL (local dev): http://localhost:3000

Authentication: Bearer token via Authorization: Bearer <token>. Only enforced when the PARMANA_API_KEY environment variable is set. Omit in development mode.

---

POST /execute

Execute a deterministic governance decision.

Request body

{
  "policyId":      "claims-approval",
  "policyVersion": "v1",
  "signals": {
    "insurance_active": true,
    "risk_score":       42,
    "vip_customer":     false,
    "claim_amount":     8500
  }
}

Field	Type	Required	Description
policyId	string	✓	Policy identifier
policyVersion	string	✓	Exact policy version to evaluate against
signals	object	✓	Key/value map of governed input signals

Response 200 OK

{
  "status":           "ok",
  "executionId":      "a3f2b1c4d8e7f96a012b3c4d5e6f7890a1b2c3d4e5f6789012345678abcdef01",
  "decision":         { "action": "approve", "requires_override": false, "reason": "standard_approval" },
  "execution_state":  "completed",
  "requires_override": false,
  "signature":        "v4F7mK3nQs8rXpLw2YbD9eHtNcAoGiUjZlV0TfRkMyPh1CxBs6WqJ5IuEdOgPm4Qa3bZwF2K8BNrHc+Ts1YxXD=="
}

Field	Type	Description
executionId	string	SHA-256 execution identity
decision	object	Governance outcome
execution_state	string	"completed" / "blocked" / "pending_override"
requires_override	boolean	Whether human escalation is required
signature	string	Ed25519 over canonical attestation JSON

Error responses

Status	Meaning
400	Invalid request body (missing fields, wrong types)
413	Request body too large
422	Execution failure (invariant violation, no matching rule)
429	Rate limit exceeded

Example (curl)

curl -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -d '{
    "policyId":      "claims-approval",
    "policyVersion": "v1",
    "signals": {
      "insurance_active": true,
      "risk_score":       42,
      "vip_customer":     false,
      "claim_amount":     8500
    }
  }'

---

POST /verify

Verify the cryptographic signature and runtime provenance of an ExecutionAttestation.

Request body

The canonical flattened ExecutionAttestation:

{
  "executionId":     "a3f2b1c4d8e7...",
  "decision":        { "action": "approve", "requires_override": false },
  "execution_state": "completed",
  "runtimeHash":     "8f4a2e9c1b3d...",
  "signature":       "v4F7mK3nQs8r..."
}

Field	Type	Required	Description
executionId	string	✓	Execution identity to verify
decision	object	✓	Decision payload to verify against
execution_state	string	✓	Expected execution state
runtimeHash	string	✓	Expected runtime hash
signature	string	✓	Base64 Ed25519 signature to verify

Response 200 OK

{
  "valid": true,
  "checks": {
    "signature_verified": true,
    "runtime_verified":   true,
    "schema_compatible":  true
  }
}

Field	Type	Description
valid	boolean	true if all checks pass
checks.signature_verified	boolean	Ed25519 signature is valid
checks.runtime_verified	boolean	Runtime hash matches expected
checks.schema_compatible	boolean	Schema version is compatible

Example (curl)

curl -X POST http://localhost:3000/verify \
  -H "Content-Type: application/json" \
  -d '{
    "executionId":     "a3f2b1c4d8e7...",
    "decision":        { "action": "approve", "requires_override": false },
    "execution_state": "completed",
    "runtimeHash":     "8f4a2e9c1b3d...",
    "signature":       "v4F7mK3nQs8r..."
  }'

---

Starting the server

# Development
npm run dev --workspace=packages/server

# Production
npm run build --workspace=packages/server
node packages/server/dist/index.js

Environment variables:

Variable	Description	Default
PORT	Server port	3000
PARMANA_API_KEY	Enable Bearer auth	unset (auth disabled)
REDIS_URL	Redis for replay store	unset (uses memory)
DATABASE_URL	PostgreSQL for audit-db	unset (audit disabled)

---

TypeScript client

Use @parmanasystems/sdk-client for type-safe access:

import { ParmanaClient } from "@parmanasystems/sdk-client";

const client = new ParmanaClient({ baseUrl: "http://localhost:3000" });

const result = await client.execute({
  policyId:      "claims-approval",
  policyVersion: "v1",
  signals:       { insurance_active: true, risk_score: 42, vip_customer: false, claim_amount: 8500 },
});

See @parmanasystems/sdk-client for full documentation.