Governance Evaluate

Evaluate an action against the 8 governance laws without executing it. Returns the governance verdict (proceed, escalate, or block) and per-law evaluation results.

This is the primary endpoint of the ARQERA API.

POST /api/v1/ara/governance/evaluate

Request

Headers

Header	Required	Description
X-API-Key	Yes	Your ARQERA API key (ak_...)
Content-Type	Yes	application/json

Body

{
  "action": "email.send",
  "description": "Send a welcome email to a new user",
  "context": {
    "risk_level": "low",
    "is_irreversible": false,
    "has_approval": false,
    "estimated_cost_usd": 0.01
  }
}

Field	Type	Required	Description
action	string	Yes	Action identifier (e.g., email.send, data.delete, ai.generate, payment.process)
description	string	No	Human-readable description of the action
context	object	No	Additional context for evaluation (see below)

Context Fields

All context fields are optional. Providing more context improves evaluation accuracy.

Field	Type	Description
risk_level	string	"low", "medium", "high", or "critical"
is_irreversible	boolean	Whether the action cannot be undone
has_approval	boolean	Whether human approval was obtained
estimated_cost_usd	number	Estimated cost of the action in USD
budget_remaining_usd	number	Remaining budget in USD
confidence_score	number	AI confidence level (0.0 to 1.0)
min_confidence	number	Minimum required confidence threshold
trust_score	number	Actor's trust score (0 to 100)
actor_type	string	"human" or "ai_agent"
artifact_type	string	Evidence artifact type to produce

Response

200 OK

{
  "verdict": "proceed",
  "action": "email.send",
  "explanation": "All 8 governance laws passed.",
  "duration_ms": 12.34,
  "evaluated_at": "2026-02-22T10:30:00Z",
  "evaluations": [
    {
      "law_id": "audit_conservation",
      "law_name": "Audit Conservation",
      "result": "pass",
      "reason": "Action produces an auditable trace",
      "details": {
        "has_tenant": true,
        "has_user": true
      },
      "duration_ms": 0.45
    },
    {
      "law_id": "budget_conservation",
      "law_name": "Budget Conservation",
      "result": "pass",
      "reason": "Within budget allocation",
      "details": {},
      "duration_ms": 1.23
    },
    {
      "law_id": "evidence_gravity",
      "law_name": "Evidence Gravity",
      "result": "pass",
      "reason": "Evidence chain maintained",
      "details": {},
      "duration_ms": 0.31
    },
    {
      "law_id": "least_action_path",
      "law_name": "Least Action Path",
      "result": "pass",
      "reason": "Optimal path selected",
      "details": {},
      "duration_ms": 0.28
    },
    {
      "law_id": "safety_dominance",
      "law_name": "Safety Dominance",
      "result": "pass",
      "reason": "No safety concerns",
      "details": {},
      "duration_ms": 0.52
    },
    {
      "law_id": "monotonic_truth",
      "law_name": "Monotonic Truth",
      "result": "pass",
      "reason": "Truth invariant maintained",
      "details": {},
      "duration_ms": 0.19
    },
    {
      "law_id": "bounded_autonomy",
      "law_name": "Bounded Autonomy",
      "result": "pass",
      "reason": "Within autonomy bounds",
      "details": {},
      "duration_ms": 1.87
    }
  ]
}

Response Fields

Field	Type	Description
verdict	string	"proceed", "escalate", or "block"
action	string	The action that was evaluated
explanation	string	Human-readable summary of the evaluation
duration_ms	number	Total evaluation time in milliseconds
evaluated_at	string	ISO 8601 timestamp of the evaluation
evaluations	array	Per-law evaluation results (see below)

Law Evaluation Object

Field	Type	Description
law_id	string	Law identifier (e.g., audit_conservation)
law_name	string	Human-readable law name
result	string	"pass", "warn", or "fail"
reason	string	Explanation of why the law passed or failed
details	object	Additional metadata from the law check
duration_ms	number	Time taken to evaluate this law

Verdict Logic

Condition	Verdict
All 8 laws pass	proceed
Any law returns warn (none fail)	escalate
Any law returns fail	block

429 Too Many Requests

Returned when you exceed your monthly governance evaluation allowance.

{
  "detail": "Free tier limit reached. Used 1001/1000 governance evaluations this period. Upgrade at arqera.io/pricing"
}

Additional headers on 429 responses:

Header	Description
X-Usage-Limit	Your monthly allowance
X-Usage-Current	Your current usage count
X-Usage-Type	governance_eval
Retry-After	Seconds until next billing period

401 Unauthorized

{
  "detail": "Invalid or expired API key."
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "action"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Examples

Low-risk action

curl -s -X POST https://api.arqera.io/api/v1/ara/governance/evaluate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ARQERA_API_KEY" \
  -d '{
    "action": "data.read",
    "description": "Read dashboard metrics"
  }'

High-risk irreversible action

curl -s -X POST https://api.arqera.io/api/v1/ara/governance/evaluate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ARQERA_API_KEY" \
  -d '{
    "action": "data.delete",
    "description": "Delete all user data for GDPR request",
    "context": {
      "risk_level": "high",
      "is_irreversible": true,
      "has_approval": false
    }
  }'

AI agent action with cost estimation

curl -s -X POST https://api.arqera.io/api/v1/ara/governance/evaluate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ARQERA_API_KEY" \
  -d '{
    "action": "ai.generate",
    "description": "Generate quarterly financial summary using GPT-4",
    "context": {
      "actor_type": "ai_agent",
      "estimated_cost_usd": 0.15,
      "budget_remaining_usd": 50.00,
      "confidence_score": 0.92
    }
  }'

Usage Headers

Every successful response includes usage-related headers when you approach your monthly limit:

Header	Description
X-Usage-Warning	Warning when at 80% of your monthly allowance
X-Usage-Limit	Your monthly governance evaluation limit
X-Usage-Current	Your current usage count