Observability administration API

The observability administration API manages organization defaults, Workspace overrides, and deployment-wide capture policy. These operations run on the registry admin listener, separate from the public Managed Agents API and internal workload resolvers. They are not Cloud extension routes.

Authentication

Set ORCA_ADMIN_URL to the admin origin with no path suffix. For self-hosted deployments the default admin port is 8082; keep this listener restricted to authorized administrators.

Platform credentials cannot call organization routes; organization credentials cannot call platform routes. Public Workspace keys and internal service tokens authenticate neither. Organization identity comes from the principal, never an organization ID supplied in the request.

Organization API keys can delegate observability:read, observability:write, and observability:rotate. Organization OIDC currently requires org:admin, not those narrower roles. An invalid presented x-api-key does not fall back to OIDC. Send one credential type per request.

Operations and permissions

Paths below are relative to the admin origin. The generated Organization observability, Workspace observability, and Platform observability sidebar groups contain the exact request/response schemas for these ten operations. Canonical action suffixes contain a literal colon, not a path parameter.

org:admin also satisfies each organization/Workspace observability scope. The existing /api/v1 admin aliases have the same authorization; use the canonical /v1 paths in new clients. Internal context and secret-resolution routes are workload-only and are not part of this reference.

Read settings

For the Bash examples, export ORCA_ADMIN_URL, ORCA_ORG_ADMIN_KEY, and WORKSPACE_ID. The Workspace must belong to the key's organization. Install curl, jq, and uuidgen. This helper loads the current representation and strong ETag before each Workspace mutation:

read_workspace_state() {
  local headers
  headers=$(mktemp)
  STATE=$(curl -fsS -D "$headers" \
    "$ORCA_ADMIN_URL/v1/organizations/workspaces/$WORKSPACE_ID/agent_observability" \
    -H "x-api-key: $ORCA_ORG_ADMIN_KEY") || { rm -f "$headers"; return 1; }
  ETAG=$(awk 'tolower($1) == "etag:" { sub(/\r$/, "", $2); print $2 }' "$headers")
  rm -f "$headers"
}

read_workspace_state
jq '{type, scope, configured, effective}' <<< "$STATE"

Both organization and Workspace GET return type: agent_observability and a scope discriminator. configured contains the selected settings; effective contains resolved source/status/capture and a non-secret binding view. Credential metadata includes configured state, version, hint, and rotation time, but no secret bytes or references. Missing, archived, and foreign Workspaces all return 404.

GET responses have ETag and Cache-Control: private, no-store. Do not share cached organization responses between credentials: the organization URL itself has no tenant selector.

Replacement and concurrency

All mutation examples use Content-Type: application/json and a new Idempotency-Key for each new operation. Keys are trimmed, nonempty, and at most 255 characters. Preserve the original body, key, and precondition when retrying the same request. Do not generate a fresh key for an uncertain retry.

Use one exact strong ETag including its quotes. Weak tags, wildcard, lists, and malformed tags are invalid. After an organization/Workspace mutation, GET again for the current ETag. Successful platform PUT returns the ETag of its returned representation; an idempotent replay returns the original representation and ETag, not today's policy.

For a new binding or changed target identity, include write-only credentials. For a same-active-target policy replacement, omit credentials and use rotation for key changes. Never send a GET response directly to PUT: remove response-only IDs, lifecycle fields, config/version metadata, and credential views.

The Litefuse walkthrough shows the full custom creation body. The configuration reference lists fields and inheritance rules.

Change a custom binding's sample rate

This example preserves all other mutable configuration, changes sampling to 0.5 for new sessions, and refuses to convert an inherited or disabled Workspace into a custom binding.

read_workspace_state
replacement=$(jq -e '
  if .configured.mode != "custom" then error("an active custom binding is required")
  else {
    mode: "custom", capture_ceiling: .configured.capture_ceiling,
    target: .configured.binding.target,
    config: (.configured.binding.config | {
      semantic_profile, protocol, compression, timeout_ms, environment, release,
      capture_mode, sample_rate: 0.5
    })
  } end' <<< "$STATE")
IDEMPOTENCY_KEY=$(uuidgen)
curl -fsS -X PUT \
  "$ORCA_ADMIN_URL/v1/organizations/workspaces/$WORKSPACE_ID/agent_observability" \
  -H "x-api-key: $ORCA_ORG_ADMIN_KEY" -H "Content-Type: application/json" \
  -H "If-Match: $ETAG" -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary "$replacement"

Rotate Workspace credentials

Export LITEFUSE_NEW_PUBLIC_KEY and LITEFUSE_NEW_SECRET_KEY for the same project. The key used for this operation needs observability:rotate or org:admin. It changes the credential head of the current active custom binding, not its target/config or session pins. Inherited, disabled, and otherwise ineligible custom states return 409.

read_workspace_state
IDEMPOTENCY_KEY=$(uuidgen)
jq -n '{credentials: {type: "basic", username: env.LITEFUSE_NEW_PUBLIC_KEY,
  password: env.LITEFUSE_NEW_SECRET_KEY}}' |
  curl -fsS -X POST \
    "$ORCA_ADMIN_URL/v1/organizations/workspaces/$WORKSPACE_ID/agent_observability:rotate_credentials" \
    -H "x-api-key: $ORCA_ORG_ADMIN_KEY" -H "Content-Type: application/json" \
    -H "If-Match: $ETAG" -H "Idempotency-Key: $IDEMPOTENCY_KEY" --data-binary @-

Disable a Workspace

Explicit Workspace disable stops that Workspace, including a custom binding. It is distinct from organization-default disable, which does not revoke Workspace custom bindings.

read_workspace_state
IDEMPOTENCY_KEY=$(uuidgen)
curl -fsS -X PUT \
  "$ORCA_ADMIN_URL/v1/organizations/workspaces/$WORKSPACE_ID/agent_observability" \
  -H "x-api-key: $ORCA_ORG_ADMIN_KEY" -H "Content-Type: application/json" \
  -H "If-Match: $ETAG" -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"mode":"disabled","capture_ceiling":"metadata_only"}'

Platform policy and capture ceilings

Platform GET returns type: agent_observability_platform_policy, the three policy fields, capture_restriction_epoch, and timestamps. PUT accepts only the three policy fields. Allowlists are nonempty, duplicate-free sets returned in canonical order. They are permission ceilings, not a catalog of working exporter adapters. Missing or corrupt policy returns 503, not a newly seeded default.

Use the explicit raw-capture procedure to change capture policy. Raising the platform ceiling can authorize eligible new sessions in other organizations. The organization ceiling-only PUT requires org:admin and does not create a default binding or rotate credentials. Never modify server-owned epochs to undo a restriction.

Errors and retries

The generated operations list their exact response schemas and status sets. Do not assume a shared Claude-compatible public error envelope: these admin routes return JSON objects with error.

Platform requests use a 24-hour replay cache scoped to the platform principal. Changing the body or original precondition under the same key conflicts. All mutation responses are no-store; platform responses are private/no-store. State reads and configuration writes do not prove external ingest.

Source contract

Download the standalone OpenAPI document. It is generated from agent-observability.contract.ts and platform-agent-observability.contract.ts in orca-managed-agents at revision 03b25db3. This reference keeps organization and platform security schemes separate and does not add these routes to managed-agents.yaml or the public/Cloud render bundle.

What's next