Skip to main content

Runtime API

This page documents the hosted runtime endpoints used by replay() and zero-config governance.

Most users should not call these endpoints directly. The SDK already wraps them. This page exists for debugging, integration review, and understanding the actual server-backed flow.

Authentication​

Runtime endpoints use the same /api/v1/* API key authentication path as the rest of the hosted API.

Typical behavior:

  • authenticate with Authorization: Bearer <VESANOR_API_KEY>
  • tenant/user context is resolved by middleware
  • unauthorized requests fail closed

Session lifecycle​

POST /api/v1/replay/sessions​

Create a session.

Used for:

  • authoritative replay sessions
  • workflow-root and workflow-child session setup

GET /api/v1/replay/sessions/:session_id​

Load session state.

Used by the SDK to inspect the current runtime view of a session and, when requested, pending work.

Enforcement cycle​

These are the core request/response governance endpoints.

POST /api/v1/replay/sessions/:session_id/preflight​

Prepare a request envelope against the current session state.

Purpose:

  • bind the request to the current state version
  • return a prepared request id
  • reject stale or invalid session writes before the model call

POST /api/v1/replay/sessions/:session_id/proposals​

Submit the model response for evaluation.

Purpose:

  • evaluate the proposed tool calls
  • register pending calls when allowed
  • return allow/block decisions

POST /api/v1/replay/sessions/:session_id/receipts​

Submit execution evidence for a pending call.

Purpose:

  • record execution outcome
  • advance authoritative state when commit requirements are satisfied
  • preserve durable pending/receipt state for recovery

Session controls​

POST /api/v1/replay/sessions/:session_id/labels​

Append an immutable label to a session.

POST /api/v1/replay/sessions/:session_id/tool-filter​

Set a manual tool filter for the session.

POST /api/v1/replay/sessions/:session_id/report-bypass​

Report that a caller bypassed the wrapped client path.

POST /api/v1/replay/sessions/:session_id/kill​

Kill the session.

POST /api/v1/replay/sessions/:session_id/recover​

Recover a recoverable session and rotate its lease/fence state as needed.

Workflow endpoints​

When workflow governance is enabled, the runtime also exposes workflow-scoped endpoints.

GET /api/v1/replay/workflows/:workflow_id​

Load current workflow state.

POST /api/v1/replay/sessions/:session_id/handoffs​

Offer a handoff from one session/role to another.

POST /api/v1/replay/workflows/:workflow_id/handoffs/:handoff_id/complete​

Mark a handoff complete.

POST /api/v1/replay/workflows/:workflow_id/handoffs/:handoff_id/reclaim​

Reclaim an eligible handoff.

POST /api/v1/replay/workflows/:workflow_id/kill​

Kill the workflow.

Zero-config governance lookup​

GET /api/v1/governance/plan?agent=<agent>&environment=<env>​

This is the hosted lookup used by zero-config governance.

It returns:

  • plan status
  • approved compiled_session and compiled_hash when available
  • draft/approved plan metadata for the current agent/environment

This is how replay(client, { apiKey }) discovers whether a zero-config artifact exists for the current workspace.

Checkpoints​

Human checkpoints are callback-driven in the current repo.

That means:

  • the SDK evaluates checkpoint triggers
  • the SDK calls your onCheckpoint callback
  • the public runtime API in this repo does not expose a .../proposals/:proposalId/approve endpoint

If you need the callback types, see SDK API Reference.

When to use this doc​

Use this page when you need to answer:

  • what does the SDK actually call?
  • which hosted endpoint owns preflight/proposal/receipt?
  • how do workflow and session routes differ?
  • is there a public approval endpoint for checkpoints?

For normal application integration, start with: