Skip to content
Clasper Core

API Reference

API Reference

Section titled “API Reference”

Trust boundaries: OSS endpoints support local, self-attested approvals. Cloud-only endpoints (e.g. /api/decisions/:id/consume) return 501 in OSS. See OSS vs Cloud.

Authentication headers

Section titled “Authentication headers”
  • Core access (optional): X-Agent-Daemon-Key (required only if AGENT_DAEMON_API_KEY is set)
  • Adapter access (required): X-Adapter-Token: <jwt>
  • Ops Console: Authorization: Bearer <OIDC JWT>

Core (built-in runtime adapter)

Section titled “Core (built-in runtime adapter)”

POST /api/agents/send

Section titled “POST /api/agents/send”

Runs the built-in runtime adapter behind governance and returns:

  • execution_id
  • trace_id

POST /api/agents/stream

Section titled “POST /api/agents/stream”

Streaming (SSE) variant of /api/agents/send.

Adapter contract (external executors)

Section titled “Adapter contract (external executors)”

POST /adapters/register

Section titled “POST /adapters/register”

Register (or update) an adapter registration record.

Requires X-Adapter-Token.

POST /api/execution/request

Section titled “POST /api/execution/request”

Request a pre-execution decision (allow/deny + granted scope).

Requires X-Adapter-Token.

Request body (minimum):

  • execution_id (optional; generated if omitted)
  • adapter_id
  • tenant_id
  • workspace_id
  • requested_capabilities[]

Optional agent identity:

  • agent_id?: string — agent identifier for per-agent policies
  • agent_role?: string — agent role
  • agent_metadata?: object — additional agent context

Optional execution context signals (v2):

  • intent?: string
  • context?: { external_network?: boolean; writes_files?: boolean; elevated_privileges?: boolean; package_manager?: string; targets?: string[] }
  • provenance?: { source?: "marketplace" | "internal" | "git" | "unknown"; publisher?: string; artifact_hash?: string }

Notes:

  • Policy matching supports a subset of these fields today (see Governance). context.targets and provenance.artifact_hash are captured for audit but are not matchable in policy conditions yet.

Async approvals (v2.2)

Section titled “Async approvals (v2.2)”

If the decision requires human gating, POST /api/execution/request returns:

  • decision: "pending"
  • decision_id
  • expires_at
  • required_role

Clasper Core (OSS) supports local, self-attested approvals via the Ops Console.

Polling + resume:

  • Adapter polling:
    • GET /api/execution/:executionId (quick “effect” check), or
    • GET /api/decisions/:decisionId (full decision record)
  • Ops resolution (local/self-attested):
    • POST /ops/api/decisions/:decisionId/resolve (requires Ops auth)
  • Resume:
    • call POST /api/execution/request again with the same execution_id to receive the post-approval allow/deny result

Cloud-only: POST /api/decisions/:decisionId/consume (decision tokens) returns 501 in OSS.

Telemetry ingest

Section titled “Telemetry ingest”

All require X-Adapter-Token:

  • POST /api/ingest/trace
  • POST /api/ingest/audit
  • POST /api/ingest/cost
  • POST /api/ingest/metrics
  • POST /api/ingest/violations

All ingest endpoints accept signed telemetry envelopes in v2.1.

Adapter governance posture

Section titled “Adapter governance posture”

Authenticated adapter posture endpoints:

  • GET /api/adapter/posture (canonical)
  • GET /api/adapter/policy-posture (compatibility alias)
  • GET /api/adapter/policies (effective active policy summary)
  • GET /api/adapter/decisions (adapter-scoped decision history)
  • GET /api/adapter/decisions/:decisionId (single decision detail)
  • GET /api/adapter/decisions/:decisionId/explain (human-readable decision explanation)

Response includes governance mode/status and coverage details:

  • mode: permissive | guarded | strict
  • status: ENFORCED | DEGRADED | DISABLED
  • engine_version
  • fallback_present, fallback_enabled
  • policy_count
  • covered_tools[], uncovered_tools[]

Decision list supports filters:

  • status (pending|approved|denied|expired|allow|deny)
  • decision (allow|deny|require_approval|pending)
  • tool, policy
  • since (10m, 1h, or ISO timestamp)
  • limit, offset (bounded; default 50, max 500)

Tool authorization (v2.1)

Section titled “Tool authorization (v2.1)”
  • POST /api/governance/tool/authorize
  • POST /api/policy/evaluate
  • POST /api/policy/dry-run (ops)

Observability + governance APIs

Section titled “Observability + governance APIs”
  • GET /traces
  • GET /traces/:id
  • GET /audit
  • GET /budget

Ops Console

Section titled “Ops Console”

All Ops endpoints require Authorization: Bearer <OIDC JWT> or X-Ops-Api-Key (when OPS_LOCAL_API_KEY is set).

  • GET /ops
  • GET /ops/api/me
  • GET /ops/api/traces (query: agent_id, agent_role, risk_level, adapter_id, etc.)
  • GET /ops/api/traces/:id
  • POST /ops/api/traces/:id/simulate (re-run policy evaluation with current bundle)
  • POST /ops/api/traces/diff (compare two traces)
  • GET /ops/api/dashboards/cost
  • GET /ops/api/dashboards/risk
  • GET /ops/api/dashboards/governance (approval/denial rates, risk distribution, adapter errors)
  • GET /ops/api/agents (agent inventory from traces)
  • GET /ops/api/adapters (includes certification_tier, tool_capabilities)
  • GET /ops/api/tool-authorizations
  • GET /ops/api/audit-chain/export
  • POST /ops/api/exports (verifiable export bundle; body: trace_id, tenant_id, workspace_id, etc.)
  • GET /ops/api/decisions (pending approvals queue)
  • GET/POST/PATCH/DELETE /ops/api/policies (policy objects)
  • GET /ops/api/adapter-probe-token (short-lived token for synthetic governance verification probes used by prove:governance)
Section titled “Related”