Runs, resume, and the governed callback.

Public / host-facing API

The host-facing API is authenticated with the host token. Start a run with a request plus HostContext, resume it after a human decision, and read run state — while the embed subscribes to typed run events over Socket.IO. This is an outline; parameters, payload schemas, and error bodies are completed by engineering, and errors follow RFC 7807 problem+json.

POST /api/v1/runs
  Start an agent run for a request + HostContext.
  Returns a run with its first card (typically a plan card).

POST /api/v1/runs/:id/resume
  Resume a run after a human decision:
  approve / reject / modify / provide-context.

GET  /api/v1/runs/:id
  Fetch current run state and cards.

Socket.IO  (room: run:{runId})
  The embed joins a per-run room and receives typed events:
  status transitions and card updates as the run progresses.

Admin / authoring API

Authoring endpoints are platform-role gated. Admins create and manage agents, skills, tools, and multi-agent compositions, and capture new behavior through Teach / Train — where captures land as drafts, so live agents are never silently mutated.

• /api/v1/agents — author and manage agents.
• /api/v1/skills — author declarative skills.
• /api/v1/tools — define tools and their risk levels.
• /api/v1/compositions — assemble multi-agent teams.
• /api/v1/teach — capture new agents, skills, or templates as drafts.
• Supporting endpoints — card templates, audit events, platform config, and me.

Internal governed callback

The runtime can never execute a side-effecting tool directly. Every action the reasoning runtime wants to take is dispatched to a single internal endpoint so the one governance gate can enforce permission ∩ policy ∩ approval ∩ audit. This endpoint is authenticated with the service token — constant-time compared, never logged, and never exposed to the browser.

POST /internal/tools/execute        (service-to-service only)
  The runtime's governed callback into the platform.
  Every side-effecting tool call is routed here so the single
  governance gate enforces permission ∩ policy ∩ approval ∩ audit.
  Auth: service token (constant-time compared, never logged).

Every tool call described above is dispatched through the governance gate — permission, policy, approval, audit, and the platform-level controls are set out on the security and data-handling page. For host-specific worked examples, see the integration paths.