Runtime Runs API

REST and stream interfaces for orchestrated runs, approvals, artifacts, and Omar loop execution.

  • runtime-api
  • sse
  • websocket
  • omar-loop
  • approvals

Runtime APIs expose deterministic run lifecycle and replayable evidence.

Core endpoints

  • `POST /api/v1/runs` create run
  • `GET /api/v1/runs/{run_id}/status` fetch status and summaries
  • `POST /api/v1/runs/{run_id}/cancel` cancel run
  • `GET /api/v1/runs/{run_id}/events` SSE event stream
  • `GET /api/v1/runs/{run_id}/events/list` paged poll endpoint for deterministic replay
  • `WS /api/v1/runs/{run_id}/terminal` terminal stream with resume cursor
  • `POST /api/v1/runs/{run_id}/approvals` approve or deny gated actions
  • `GET /api/v1/runs/{run_id}/evidence` export run evidence bundle
  • `GET /api/v1/runtime/kpi?compare_window_days=&baseline_window_days=` compare and baseline KPI windows
  • `POST /api/v1/runs/git/pr/checkpoints` execute git/PR checkpoints across multiple run IDs
  • `GET /api/v1/models/catalog` account-aware model catalog and ranking
  • `POST /api/v1/loops/omar` start remediation loop
  • `GET /api/v1/loops/omar/{loop_id}` inspect loop state and exit reason

Event contract

All runtime events include:

  • stable identifiers and timestamps
  • event kind, actor, and normalized payload
  • usage/accounting metadata for audit reporting

Typical event families

  • lifecycle transitions (start, progress, complete, failure)
  • tool execution summaries (call + result)
  • output streaming updates (terminal and narrative)
  • governance checkpoints (approval requested, approved, denied)

Omar loop stop semantics

Loop terminates only when one of the following is true:

  • clean `P0-P2` and green quality gates
  • explicit budget or iteration ceiling reached
  • policy or approval checkpoint denies continuation

Structured Answers

How do I stream run output in real time?

Subscribe to SSE events at /api/v1/runs/{run_id}/events and open terminal WebSocket at /api/v1/runs/{run_id}/terminal for stdout/stderr chunks.

What should I use for audit exports?

Use /api/v1/runs/{run_id}/evidence for downloadable run evidence with timeline, integrity chain metadata, redaction status, findings summary, and artifacts.