Runtime Integration Contract

Concise public contract for SDK authors and integrators. Machine-readable request/response schemas live in bobsentry-runtime/packages/contracts (Zod). This page does not duplicate the full schema.

Runtime endpoint

POST /v1/runtime/evaluate

Production host: https://runtime.bobsentry.com

Authentication

Header: x-api-key: <tenant or agent credential>
Do not use Authorization: Bearer for runtime evaluate.
If the key is Agent-bound (boundAgentId), body agent_id must match or the request is rejected (403).
Tenant is derived from the API key. Caller-supplied tenant fields are rejected.

Required request fields

action (string)
agent_id (string)

Optional (see Zod contract): action_category, action_environment (DEVELOPMENT | STAGING | PRODUCTION | UNKNOWN), payload, context, metadata, correlation_id, nonce, schema_version.

Current schema version: 2026-06

Canonical example

curl -X POST https://runtime.bobsentry.com/v1/runtime/evaluate \
  -H "x-api-key: $BOBSENTRY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "action": "deploy_production",
    "agent_id": "infra-agent",
    "action_environment": "PRODUCTION",
    "schema_version": "2026-06",
    "metadata": { "system": "payments" }
  }'

Decision enum

ALLOW — BobSentry authorizes the integrator to proceed, subject to the integrator's own execution logic.
REQUIRE_APPROVAL — the downstream mutation must not happen yet; human authorization is required.
BLOCK — the downstream mutation must not happen.

Trust boundary

BobSentry returns the authorization decision. Your integration is responsible for honoring that decision and performing or withholding the downstream action. BobSentry does not execute the downstream operation. Authorization is not execution and is not an execution outcome.

Customer agent modes are COOPERATIVE and OBSERVE. There is no customer-selectable ENFORCED mode.

Approval semantics

evaluate returns decision / decision_id (and related fields such as approval_required, approval_status).
On REQUIRE_APPROVAL, the integrator does not execute the downstream mutation.
A human reviews and resolves the approval in the BobSentry console (authorized human/admin identity).
The integrator polls the decision with GET /v1/runtime/decisions/:decisionId (same x-api-key). Check approval_status (for example PENDING, APPROVED, DENIED, EXPIRED).
Only when authorized may the integrator proceed. Evaluation credentials cannot self-approve.

Approval authorizes the integrator to proceed. Approval is not proof that the downstream action executed.