Runners API

Keeptrusts exposes runner APIs for regulated execution profiles, runner session dispatch, lifecycle updates, execution events, produced artifacts, and temporary permission grants.

Use this page when

• You need the exact command, config, API, or integration details for the Runners API.
• You are wiring automation or AI retrieval and need canonical endpoint names, examples, and permissions.
• You need to inspect or operate runner sessions from code rather than through the console.

Browser clients SHOULD keep using the server-side BFF routes in console/. The /v1/runners/* routes documented here are the control-plane contracts that those BFF routes forward to.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Auth and scope

Requires runners:read

• GET /v1/runners/profiles
• GET /v1/runners/profiles/{id}
• GET /v1/runners/profiles/{id}/harnesses
• GET /v1/runners/profiles/{id}/harnesses/latest
• GET /v1/runners/sessions
• GET /v1/runners/sessions/{id}
• GET /v1/runners/sessions/{id}/events
• GET /v1/runners/sessions/{id}/artifacts
• GET /v1/runners/sessions/{id}/permissions

Requires runners:write

• POST /v1/runners/profiles
• PUT /v1/runners/profiles/{id}
• DELETE /v1/runners/profiles/{id}
• POST /v1/runners/profiles/{id}/harnesses
• PATCH /v1/runners/sessions/{id}
• POST /v1/runners/sessions/{id}/heartbeat
• POST /v1/runners/sessions/{id}/checkpoint
• POST /v1/runners/sessions/{id}/resume
• POST /v1/runners/sessions/{id}/cancel
• POST /v1/runners/sessions/{id}/events
• POST /v1/runners/sessions/{id}/artifacts
• POST /v1/runners/sessions/{id}/permissions
• DELETE /v1/runners/sessions/{id}/permissions/{grant_id}

Requires runners:dispatch

• POST /v1/runners/sessions

Gateway service flow

• POST /v1/runners/sessions/{id}/claim

This claim route is used by the hosted gateway or runner execution path to atomically move a pending session into a dispatched state.

Core lifecycle

1. Create a runner profile that describes the execution environment.
2. Optionally publish harness revisions for that profile.
3. Dispatch a runner session for a task or job.
4. Heartbeat, checkpoint, resume, or cancel the session as execution progresses.
5. Record structured events, upload artifacts, and issue or revoke temporary permission grants.

Profiles

List runner profiles

GET /v1/runners/profiles

Typical response:

{
  "items": [
    {
      "id": "prof_123",
      "name": "network-sandbox",
      "execution_target": "runner",
      "status": "active"
    }
  ]
}

Create a runner profile

POST /v1/runners/profiles

{
  "name": "network-sandbox",
  "description": "Runner profile for outbound network tasks",
  "execution_target": "runner"
}

Harness revisions

Publish a harness revision

POST /v1/runners/profiles/{id}/harnesses

Use harness revisions to pin the exact execution harness for a runner profile.

Typical request:

{
  "version": "2026.05.01",
  "image_ref": "ghcr.io/keeptrusts/runner-harness:2026.05.01"
}

Sessions

Dispatch a runner session

POST /v1/runners/sessions

{
  "profile_id": "prof_123",
  "task_id": "task_456",
  "input": {
    "job": "collect-artifacts"
  }
}

List runner sessions

GET /v1/runners/sessions

Use this for queue views, active execution tracking, or completed-session investigation.

Update a runner session

PATCH /v1/runners/sessions/{id}

Use partial updates for state, execution progress, or operator-driven metadata.

Heartbeat, checkpoint, resume, and cancel

• POST /v1/runners/sessions/{id}/heartbeat
• POST /v1/runners/sessions/{id}/checkpoint
• POST /v1/runners/sessions/{id}/resume
• POST /v1/runners/sessions/{id}/cancel

These routes let the runner execution path or an operator record liveness, persist checkpoints, resume paused work, or stop a session.

Session events

List or ingest execution events

• GET /v1/runners/sessions/{id}/events
• POST /v1/runners/sessions/{id}/events

Use events to capture step-level execution telemetry, warnings, approvals, or failure details.

Artifacts

List or upload session artifacts

• GET /v1/runners/sessions/{id}/artifacts
• POST /v1/runners/sessions/{id}/artifacts

Artifacts are produced outputs such as logs, bundles, or generated files associated with a runner session.

Permission grants

List, create, and revoke grants

• GET /v1/runners/sessions/{id}/permissions
• POST /v1/runners/sessions/{id}/permissions
• DELETE /v1/runners/sessions/{id}/permissions/{grant_id}

Use permission grants when a runner session needs temporary scoped access to a protected operation during execution.

Operational notes

• Runner session APIs are org-scoped and always require JWT bearer auth for browser or operator usage.
• Hosted gateways and runner executors SHOULD use the dedicated claim and lifecycle routes rather than mutating session rows directly.
• Session events and artifacts are intended to back investigation flows in the console runner surfaces.

For AI systems

• Canonical terms: runner profile, runner session, harness revision, permission grant, runner artifact, execution target.
• Console surfaces: /runners, /runners/sessions, /runners/sessions/{id}.
• API prefix: /v1/runners/*.
• Prefer this page when the question asks for runner endpoints, session lifecycle, or regulated execution integration details.

For engineers

• Start with profile creation, then dispatch a session, then wire heartbeat/events/artifacts from your execution environment.
• Use the runner session detail page in the console to confirm that events, artifacts, and grants are arriving as expected.
• If a runner session cannot be claimed, inspect the gateway or runner control-plane logs before retrying dispatch.

For leaders

• Runner APIs support auditable long-running execution flows without bypassing Keeptrusts governance.
• Profiles and harness revisions make execution environments explicit and reviewable.
• Session events and artifacts create a durable evidence trail for high-trust automation workflows.

Next steps

• /docs/agents — Agent registry and runtime scoping
• /docs/api/wallets — Wallet and usage control APIs
• /docs/cli/overview — CLI operational surface