HTTP API Reference

The gateway exposes 70+ endpoints across 9 route groups on :8080. All JSON. Authenticate with a bearer token (OVARA_TOKEN / apiKey in the SDKs).

Runtime decisions

POST /v1/runtime/check

Evaluate one action. Request shape (mirrors the SDKs):

{
  "action_type": "shell",
  "resource": "shell:git push origin main",
  "environment": "dev",
  "agent_identity": { "issuer": "ovara", "subject_id": "agt_001" },
  "capability_lease": { "...": "..." },
  "metadata": {},
  "trace_id": "…"
}

Response decisions: allow, deny, escalate (plus reason codes like policy_allow, policy_deny, policy_escalate, trust_escalate, capability_expired, capability_scope_mismatch).

POST /v1/runtime/batch-check

Same shape wrapped as { "requests": [...] } - one round trip for many actions.

GET /v1/runtime/decision/{id}
GET /v1/runtime/agent/{agent_id}/recent
GET /v1/runtime/required_action_fields

Look up a past decision, list an agent's recent decisions, or fetch the machine-readable schema for check requests.

Runtime introspection

GET /v1/runtime/status
GET /v1/runtime/health
GET /v1/runtime/metrics
GET /v1/runtime/summary
GET /v1/runtime/snapshot
GET /v1/runtime/trace
GET /v1/runtime/integrity

Status, liveness, Prometheus-style metrics, aggregate summaries, state snapshots, distributed traces, and store integrity checks.

Approvals

POST /v1/approval/create
GET  /v1/approvals
GET  /v1/approval/pending
GET  /v1/approval/{id}
POST /v1/approval/{id}/approve
POST /v1/approval/{id}/deny
POST /v1/approval/{id}/resume

Create approval requests for escalated decisions, list pending ones, approve or deny by ID, then resume the original action. Continuations track the lifecycle (escalated -> approved -> queued -> ready -> executed, plus failed, timed_out, denied, expired, cancelled, resumed):

GET  /v1/continuations
GET  /v1/continuations/queue
GET  /v1/continuations/stats
GET  /v1/continuations/{id}
POST /v1/continuations/{id}/enqueue
POST /v1/continuations/{id}/execute
POST /v1/continuations/{id}/cancel
POST /v1/continuations/{id}/retry
POST /v1/continuations/{id}/recover-executing
POST /v1/continuations/queue/pause
POST /v1/continuations/queue/resume
POST /v1/continuations/sweep

Capabilities and leases

GET  /v1/capabilities
GET  /v1/capabilities/{id}
GET  /v1/capabilities/history
POST /v1/capabilities/track
POST /v1/capabilities/revoke
POST /v1/capabilities/revoke-by-subject

Issue, inspect, and revoke capability leases; revoke everything held by a subject at once.

Shield and trust

GET  /v1/shield/status
GET  /v1/shield/status/{agent_id}
POST /v1/shield/restrict/{agent_id}
POST /v1/shield/unrestrict/{agent_id}
GET  /v1/trust/context

Read fleet or per-agent trust posture, restrict/unrestrict agents, and fetch the current trust context.

Policy management

GET  /v1/policy/rules
GET  /v1/policy/history
GET  /v1/policy/history/entry
GET  /v1/policy/diff
POST /v1/policy/validate
POST /v1/policy/simulate
POST /v1/policy/simulate-batch
POST /v1/policy/restore
POST /v1/policy/rollback
POST /v1/policy/candidate/load
POST /v1/policy/candidate/promote

Validate rules before deploying, simulate decisions without executing, diff and roll back policy versions, and promote staged candidates.

Receipts, executions, events

GET /v1/receipts
GET /v1/receipts/{id}
GET /v1/receipts/decision/{decision_id}
GET /v1/executions
GET /v1/executions/{id}
GET /v1/executions/stats
GET /v1/events
GET /v1/events/{id}
GET /v1/events/export
GET /v1/audit/export

Signed receipts (HMAC-SHA256 sig_v1:<hex>, ed25519 for federated), execution records, and the exportable audit trail. Receipt retention defaults to 365 days.

Admin and maintenance

POST /v1/admin/compact
POST /v1/admin/sweep/continuations
POST /v1/admin/sweep/events
POST /v1/admin/reconcile/continuations
POST /v1/admin/reconcile/executions