API Reference

Action-governance endpoints are mounted under /allow/*, with versioned read endpoints under /v1/allow/*. The base URL is https://api.visiqlabs.com.

Authentication

All endpoints require a Bearer credential: Authorization: Bearer <key>. Requests without a valid credential receive 401 Unauthorized. Two credential audiences exist:

Harness keys — the operational credential your SDK or harness runs with. Either a vq_prod_... / vq_test_... key minted in the dashboard under Settings → Harness Keys, or the allow_... key returned once by POST /allow/agents. Harness keys are full-power on the operational endpoints (evaluate, bundle, telemetry, execution events, decision polling, agent self-registration, the mode stream) and route-confined: calling any management endpoint with one returns 403 {"error": "harness_key_not_permitted"}.
Management keys — general automation credentials governed by explicit permission grants. They can call every endpoint on this page. Management keys are launching soon: they are visible in the dashboard under Settings → API Keys, but creating one is not yet enabled. Until then, drive the management endpoints from the dashboard, which authenticates with your session.

Scoped keys are additionally checked against their granted scopes. Evaluation endpoints require rules:evaluate (or the legacy allow:write); read endpoints require rules:read (or the legacy allow:read); full_access satisfies everything. A key without the required scope receives 403 {"error": "insufficient_scope"} listing the required and granted scopes.

Rate limiting

Every API-key request passes a per-key sliding-window rate limit (default 600 requests per 60 seconds). Responses carry X-RateLimit-Limit and X-RateLimit-Remaining headers; exceeding the window returns 429 with a Retry-After header and body {"error": "rate_limited", "detail": "API key rate limit exceeded.", "retryAfter": <seconds>}.

List responses

Every list endpoint on this page returns the same envelope:

{
  "data": [ ... ],
  "total": 128,
  "page": 1,
  "pageSize": 50
}

Pagination is controlled by page (default 1) and limit (default 50, max 100) query parameters.

Evaluation

The endpoints your SDK or harness calls at runtime. All of them accept a harness key.

POST /allow/evaluate

Evaluate an action against your rule set and return an authorization decision. The SDK evaluates most actions locally from the cached rule bundle — this endpoint handles human-approval flows, uncovered-scenario fallback, and remote evaluation. Scope: rules:evaluate or allow:write Request body:

{
  "agent_id": "billing-agent",
  "target_app": "stripe.com",
  "action": "POST /v1/charges",
  "context": {
    "amount": 5000,
    "currency": "usd"
  }
}

Field	Type	Required	Description
`agent_id`	`string`	Yes	Identifier of the agent making the request (1–255 chars)
`target_app`	`string`	Yes	Hostname or app identifier being called (1–255 chars)
`action`	`string`	Yes	The action string — typically HTTP method + path or a tool name (1–255 chars)
`context`	`object`	No	Key-value context for rule matching. Default `{}`
`telemetry`	`object`	No	Opaque client telemetry, attached to the decision’s signed record envelope

An agent_id the platform has never seen is auto-provisioned in monitor mode (observe-only) and the evaluation proceeds — there is no 404 for unregistered agents. The new agent appears on the dashboard Agents page, ready to be promoted to enforce.

Response:

{
  "decision_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "permit",
  "reason": "Matched rule: Allow Stripe reads",
  "rule_code": "R-1042",
  "enforced": true,
  "agent_mode": "enforce",
  "plane": "action",
  "operation": "write",
  "is_retrieval": false
}

Field	Type	Description
`decision_id`	`string` (UUID)	Unique ID for this decision — used for approval polling, execution events, and audit
`decision`	`permit` \| `deny` \| `approval_required` \| `mask`	The authorization outcome
`reason`	`string`	Human-readable explanation
`rule_code`	`string` \| `null`	The matched rule’s `R-####` code, or a synthetic default-policy code (`D-READ-ALLOW`, `D-WRITE-DENY`, `D-DELETE-ASK`, …) when a no-coverage default decided
`enforced`	`boolean`	`true` when the agent runs in enforce mode. `false` means the decision is observational (“would have blocked”)
`agent_mode`	`enforce` \| `monitor` \| `off`	The agent’s server-authoritative mode at decision time
`plane`	`string` \| `null`	Classification of the action’s schema (`action`, `retrieval`, …); `null` until the schema is mapped
`operation`	`string` \| `null`	Canonical operation verb from the schema mapping, when available
`is_retrieval`	`boolean`	Whether the event classifies as a retrieval
`arg_redaction_rules`	`array`	Present on a `mask` decision — see below
`hitl_fallback`	`deny` \| `mask`	Present on an `approval_required` decision when a matched rule routed the action to approval; absent on gates raised by the no-coverage `ask` default (treat absence as `deny`) — see below

The mask decision is allow-with-transform: the action proceeds, but the harness must first redact the named arguments. The response carries the directives to apply:

{
  "decision_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "decision": "mask",
  "reason": "Card numbers are masked for this agent",
  "rule_code": "R-1077",
  "enforced": true,
  "agent_mode": "enforce",
  "plane": "action",
  "operation": null,
  "is_retrieval": false,
  "arg_redaction_rules": [
    { "field": "card_number", "mode": "partial", "keepLast": 4, "maskChar": "*" }
  ]
}

Each redaction directive may include field, pattern, replacement, mode (full | partial | email | custom), keepFirst, keepLast, maskChar, and keepPattern. A mask decision whose rule resolves to no usable directives is downgraded to deny server-side — the platform never returns a mask that masks nothing. The approval_required decision holds the action while a human approves or rejects it (see Human-in-the-Loop). The approval window is capped at 120 seconds — an agent never blocks longer than 2 minutes. hitl_fallback tells the harness what to do if no human responds in time: deny (the default, fail-closed) or mask (proceed with the accompanying arg_redaction_rules applied). Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden (insufficient scope), 429 Too Many Requests, 500 Internal Server Error

GET /allow/rules/bundle

Fetch the compiled rule bundle for local evaluation. The SDK caches this bundle and revalidates it in the background, so decisions on the hot path never wait on the network. Query parameters:

Parameter	Required	Description
`agent_id`	Yes	The agent the bundle is compiled for — the bundle carries that agent’s mode

agent_id is required — calling this endpoint without it returns 400 Invalid query parameters. A first bundle pull for an unknown agent_id auto-provisions the agent in monitor mode, exactly like POST /allow/evaluate.

Request headers:

Header	Description
`If-None-Match`	ETag from a previous response. The server returns `304 Not Modified` if the bundle is unchanged

Response:

{
  "version": "a3b4c5d6e7f8...",
  "agent_mode": "enforce",
  "rules": [
    {
      "id": "rule-uuid",
      "rule_code": "R-1042",
      "name": "Allow Stripe reads",
      "description": "Permit read-only Stripe API calls",
      "effect": "allow",
      "rego_source": "package allow\n\ndefault allow = false\n...",
      "resource_type": "stripe.com",
      "target_app": "stripe.com",
      "action_pattern": "GET *",
      "conditions": [
        { "field": "resource_type", "operator": "equals", "value": "stripe.com" },
        { "field": "action", "operator": "glob", "value": "GET *" }
      ],
      "priority": 10
    }
  ],
  "no_coverage": {
    "no_coverage_defaults": { "read": "approve", "write": "approve", "delete": "approve", "admin": "approve" },
    "autopilot_enabled": false,
    "enduser_hitl_enabled": true,
    "hitl_timeout_seconds": 120
  }
}

Field	Description
`version`	SHA-256 hash of the serialized payload. Changes whenever a rule, the agent’s mode, or the no-coverage settings change
`agent_mode`	The agent’s current mode, so the SDK branches on enforce / monitor / off without an extra round-trip
`rules`	Enabled action rules, sorted by priority descending. The SDK evaluates `rego_source` directly (with `target_app` / `action_pattern` as pre-filters) — the identical match loop the server runs. `conditions[]` is deprecated back-compat
`no_coverage`	Your organization’s no-coverage policy, so the SDK resolves uncovered actions locally too — no round-trip for anything

Response headers:

Header	Value
`ETag`	`"<sha256-version>"` (quoted, per RFC 7232)
`Cache-Control`	`private, max-age=60`

Status codes: 200 OK, 304 Not Modified, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

GET /v1/allow/decisions/:id

Poll the status of a decision by its ID. The SDK polls this every 2 seconds while a human approval is pending, until the decision resolves or the 120-second window lapses. Scope: rules:read or allow:read Path parameter: :id — UUID of the decision (from a POST /allow/evaluate response) Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "vendor_id": "vendor-uuid",
  "agent_id": "billing-agent",
  "target_app": "stripe.com",
  "action": "POST /v1/charges",
  "context": { "amount": 5000 },
  "decision": "approval_required",
  "reason": "High-value charge requires approval",
  "rule_id": "rule-uuid",
  "hitl_result": "approved",
  "hitl_responded_at": "2026-07-03T10:35:00Z",
  "hitl_responded_by": "reviewer@example.com",
  "created_at": "2026-07-03T10:30:00Z",
  "execution_result": null,
  "execution_completed_at": null,
  "execution_details": null,
  "hitl": {
    "id": "hitl-uuid",
    "status": "approved",
    "category": "enduser",
    "expires_at": "2026-07-03T10:32:00Z",
    "responded_at": "2026-07-03T10:31:12Z",
    "responded_by": "reviewer@example.com",
    "created_at": "2026-07-03T10:30:00Z"
  }
}

The hitl field is null for decisions that did not require approval. Status codes: 200 OK, 400 Bad Request (invalid UUID), 401 Unauthorized, 404 Not Found, 500 Internal Server Error

POST /allow/telemetry

Submit a batch of locally-evaluated decisions. The SDK calls this after local bundle evaluation so every decision — local or remote — lands in the audit trail, and uncovered scenarios surface for review. Request body:

{
  "decisions": [
    {
      "decision_id": "c1a7e2f0-3b4d-4c5e-8f90-123456789abc",
      "agent_id": "billing-agent",
      "target_app": "stripe.com",
      "action": "GET /v1/customers",
      "decision": "permit",
      "reason": "Matched rule: Allow Stripe reads",
      "evaluated_at": "2026-07-03T10:30:00.000Z",
      "rule_id": "rule-uuid",
      "rule_code": "R-1042",
      "enforced": true,
      "agent_mode": "enforce",
      "evaluation_mode": "local",
      "latency_ms": 1
    }
  ]
}

1–100 decisions per request. Required per-item fields: decision_id (UUID, client-generated), agent_id, target_app, action, decision (permit | deny | approval_required | mask), reason, and evaluated_at (ISO 8601). Optional: rule_id, rule_code, enforced, agent_mode, raw_event, evaluation_mode (local | remote), latency_ms, and context (max 32 KB serialized). Decisions without a rule_id are uncovered scenarios and create engineer-category review items. Items are validated individually: valid items are ingested, malformed ones are rejected per-item and reported back — one bad item never discards the rest of the batch. Only a batch where every item is invalid returns 400. Response (202):

{
  "received": 5,
  "uncovered": 1,
  "new_schemas": 0,
  "rejected": [
    { "index": 3, "issues": [ { "path": ["evaluated_at"], "message": "Invalid datetime" } ] }
  ]
}

Status codes: 202 Accepted, 400 Bad Request (envelope invalid or all items rejected), 401 Unauthorized, 500 Internal Server Error

POST /allow/execution-events

Record the post-decision execution outcome for a permitted action, closing the feedback loop on the audit trail. Idempotent: a second submission for the same decision_id returns 409 Conflict. Request body:

{
  "decision_id": "550e8400-e29b-41d4-a716-446655440000",
  "result": "success",
  "details": "Stripe charge created (ch_1234)"
}

Field	Type	Required	Description
`decision_id`	`string` (UUID)	Yes	ID of the decision (from `POST /allow/evaluate` or client-generated telemetry)
`result`	`success` \| `failure` \| `error`	Yes	Execution outcome
`details`	`string`	No	Free-text details (max 2000 chars)

Response: { "updated": true } Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found (decision not found), 409 Conflict (already recorded), 500 Internal Server Error

POST /allow/agents/register

Registration handshake: the SDK calls this once at startup (fire-and-forget) to report the agent’s captured environment. Idempotent — it provisions the agent if this arrives before the first evaluate call. Scope: rules:evaluate or allow:write (harness keys); management keys additionally need the agent-management permission Request body:

{
  "agent_id": "billing-agent",
  "os": "linux",
  "hostname": "worker-7",
  "ip": "10.0.4.12",
  "username": "svc-agents",
  "kind": "sdk"
}

All fields except agent_id are optional. kind is sdk (framework harness, the default) or cli_harness (CLI harness). When ip is omitted, the server records the request’s source IP. Owner and approval-routing fields are deliberately not accepted here — those are set by humans via the dashboard or the agent management API. Response: { "ok": true, "agent_id": "billing-agent" } Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

GET /allow/agents/me/stream

Server-Sent Events stream of mode changes for one agent, so the SDK flips enforcement instantly when you toggle a mode in the dashboard — no waiting for the next bundle poll. Query parameters: agent_id (required) Events:

mode_snapshot — sent immediately on connect: { "agent_mode": "enforce" | "monitor" | "off" }
mode_changed — sent whenever the agent’s mode changes: same payload
ping — heartbeat every 25 seconds to keep idle proxies from closing the connection

Status codes: 200 OK (stream), 400 Bad Request, 401 Unauthorized, 404 Not Found (unknown agent), 500 Internal Server Error

Agents

Manage the agent registry. These are management endpoints — a harness key receives 403 harness_key_not_permitted here.

GET /allow/agents

List registered agents, newest first. Query parameters: page (default 1), limit (default 50, max 100) Response:

{
  "data": [
    {
      "id": "agent-row-uuid",
      "agent_id": "billing-agent",
      "name": "Billing Agent",
      "description": "Handles subscription billing operations",
      "mode": "enforce",
      "owner_email": "owner@example.com",
      "hitl_pathway": "slack",
      "trust_tier": "tier2",
      "categories": ["transactional", "internal"],
      "business_function": "finance_accounting",
      "business_function_source": "ai",
      "no_coverage": null,
      "created_at": "2026-07-03T10:00:00Z",
      "updated_at": "2026-07-03T10:00:00Z"
    }
  ],
  "total": 3,
  "page": 1,
  "pageSize": 50
}

Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

POST /allow/agents

Register a new agent. Returns the plaintext API key exactly once — store it securely; it cannot be retrieved again. Request body:

{
  "agent_id": "billing-agent",
  "name": "Billing Agent",
  "description": "Handles subscription billing operations",
  "mode": "monitor",
  "owner_email": "owner@example.com",
  "hitl_pathway": "slack",
  "trust_tier": "tier2",
  "categories": ["transactional", "internal"]
}

Field	Type	Required	Description
`agent_id`	`string`	Yes	Logical identifier used in SDK config (max 255 chars)
`name`	`string`	Yes	Display name (max 255 chars)
`description`	`string`	No	Description (max 1000 chars)
`mode`	`enforce` \| `monitor` \| `off`	No	Evaluation mode. Default `monitor` (observe-only)
`api_key`	`string`	No	Custom API key (16–256 chars). Auto-generated (`allow_` + 64 hex chars) if omitted
`owner_email`	`string`	No	The agent’s human owner — receives approval requests for this agent
`agent_type`	`string`	No	The framework the agent runs on — a supported framework identifier such as `langchain`, `openclaw`, `llamaindex`, `autogen`, `crewai`, `vercel_ai`, `mastra`, `voltagent`, `openai_agents`, or `unknown`
`hitl_pathway`	`slack` \| `teams` \| `email`	No	Channel the owner is messaged through for approvals
`trust_tier`	`tier1` \| `tier2` \| `tier3`	No	Ordinal trust level (`tier1` = highest trust). Rules condition on it as `input.agent.trust_tier`
`categories`	`string[]`	No	Controlled multi-label vocabulary: capability labels (`read_only`, `transactional`, `data_processor`, `external_comms`, `code_exec`, `privileged`) and exposure labels (`internal`, `customer_facing`, `experimental`, `third_party`)
`no_coverage`	`open` \| `closed` \| `null`	No	Per-agent fail-safe when no rule matches an action (enforce mode). `open` permits every uncovered operation class; `closed` denies them all — an explicit lockdown that also takes precedence over autopilot; `null`/omitted inherits the org-level no-match defaults. Takes precedence over the org setting

Response (201): the agent object (as in the list response) plus api_key:

{
  "id": "agent-row-uuid",
  "agent_id": "billing-agent",
  "name": "Billing Agent",
  "description": "Handles subscription billing operations",
  "mode": "monitor",
  "owner_email": "owner@example.com",
  "hitl_pathway": "slack",
  "trust_tier": "tier2",
  "categories": ["transactional", "internal"],
  "business_function": null,
  "no_coverage": null,
  "created_at": "2026-07-03T10:00:00Z",
  "updated_at": "2026-07-03T10:00:00Z",
  "api_key": "allow_a1b2c3d4e5f6..."
}

The api_key field is only present in this response. Subsequent reads omit it entirely.

Status codes: 201 Created, 400 Bad Request, 401 Unauthorized, 409 Conflict (agent_id already registered), 500 Internal Server Error

GET /allow/agents/:id

Get a single agent by its row UUID. The response includes the machine-reported environment (agent_os, agent_hostname, agent_ip, agent_username) captured via POST /allow/agents/register, and never includes key material. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error

PUT /allow/agents/:id

Update an agent. Only provided fields change; at least one field is required. Request body: any subset of name, description, mode, owner_email (nullable), hitl_pathway (nullable), trust_tier (nullable), categories, no_coverage (open | closed, or null to clear — see the POST field table), and business_function — one of the twelve business-function identifiers (finance_accounting, hr, engineering, it_security, legal, privacy_compliance, sales, marketing, operations, customer_support, procurement, generic), or null to clear.

{
  "mode": "enforce",
  "trust_tier": "tier1"
}

Setting name or business_function pins it as human-owned — the platform’s AI naming and classification never overwrite a value you set. A mode change is broadcast immediately to any live GET /allow/agents/me/stream subscriber. Response: the updated agent object. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error

POST /allow/agents/:id/regenerate-naming

Re-run AI naming for one agent now, from its observed and normalized action schemas. An explicit opt-in: it hands name ownership back to the AI even if the name was previously user-set. A naming failure returns 200 with status: "skipped" — it never errors the agent. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error

DELETE /allow/agents/:id

Delete an agent from the registry. Response: { "deleted": true }

Deleting an agent does not revoke API keys. Revoke the agent’s key separately under Settings → Harness Keys.

Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error

Rules

Rule management. The recommended authoring path is the dashboard’s rule editor (natural-language compile, visual condition builder, and a Simulate panel that checks a new rule against your recent traffic — rules projected to inhibit more than 5% of it are blocked). These endpoints are the programmatic equivalent.

GET /allow/rules

List action rules, sorted by priority descending — the same order the engine evaluates them in (first match wins). Query parameters: page (default 1), limit (default 50, max 100) Response:

{
  "data": [
    {
      "id": "rule-uuid",
      "name": "Allow Stripe reads",
      "description": "Permit read-only Stripe API calls",
      "natural_language": "Allow my billing agent to read from Stripe",
      "priority": 10,
      "enabled": true,
      "created_at": "2026-07-03T10:00:00Z",
      "updated_at": "2026-07-03T10:00:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "pageSize": 50
}

The list omits rego_source; fetch a single rule to read the policy source. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

POST /allow/rules

Create a rule. Request body:

{
  "name": "Allow Stripe reads",
  "description": "Permit read-only Stripe API calls",
  "rego_source": "package allow\n\ndefault allow = false\n\nallow { input.action == \"GET /v1/customers\" }",
  "natural_language": "Allow my billing agent to read from Stripe",
  "priority": 10,
  "enabled": true
}

Field	Type	Required	Description
`name`	`string`	Yes	Rule name, unique per organization (max 255 chars)
`description`	`string`	No	Description (max 1000 chars)
`rego_source`	`string`	Yes	Policy source (see note below)
`natural_language`	`string`	No	The plain-English intent the policy was compiled from (max 2000 chars)
`priority`	`number`	No	Evaluation priority — higher runs first. Default `0`
`enabled`	`boolean`	No	Whether the rule is active. Default `true`

rego_source holds the rule’s policy source in the platform’s Rego-subset condition language (equality, inequality, set membership, startswith/endswith/contains, regex, counts, and numeric comparisons). The effect (permit, deny, approval, mask) is derived from the decisions in the policy body. Prefer POST /allow/rules/compile — the compiler drafts and validates the policy against the live evaluation engine.

Response (201): the created rule object, including rego_source. Status codes: 201 Created, 400 Bad Request, 401 Unauthorized, 409 Conflict (a rule with this name already exists), 500 Internal Server Error

POST /allow/rules/compile

Compile a natural-language description into a rule. The compiler reads your existing rules for context, drafts the policy source, and validates it against the live evaluation engine. Rate limit: 10 compile requests per minute per organization — exceeding it returns 429. Query parameters: stream=true — stream the compile over Server-Sent Events instead of a single JSON response (also triggered by Accept: text/event-stream). Request body:

{
  "prompt": "Allow my billing agent to read from Stripe but block all write operations"
}

Field	Type	Required	Description
`prompt`	`string`	Yes	Plain-English rule description (max 4000 chars)
`nodeRef`	`string`	No	Rule-graph node reference for editor context (max 255 chars)

Response:

{
  "rego_source": "package allow\n\ndefault allow = false\n...",
  "natural_language": "This rule permits read operations against stripe.com for the billing agent and denies writes...",
  "name": "Stripe Read-Only Access",
  "description": "Permits Stripe reads, denies Stripe writes",
  "suggested_priority": 50
}

Streaming response (?stream=true): a text/event-stream of JSON events —

data: {"type":"text","content":"Drafting the policy..."}

data: {"type":"done","result":{"rego_source":"...","natural_language":"...","name":"...","description":"...","suggested_priority":50}}

On failure the stream emits {"type":"error","message":"..."} and closes. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 422 Unprocessable Entity (the compiler could not produce a valid policy — refine the prompt), 429 Too Many Requests, 500 Internal Server Error

GET /allow/rules/:id

Get a single rule by UUID, including rego_source. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error

PUT /allow/rules/:id

Update a rule. Same fields as POST /allow/rules, all optional; at least one is required. Only provided fields change. Response: the updated rule object. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error

DELETE /allow/rules/:id

Delete a rule permanently. Response: { "deleted": true } Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error

Human-in-the-Loop Queue

Review items land here in two categories: enduser items are live approval gates (a rule routed the action to a human — the agent is waiting), while engineer and the other categories are coverage-gap reviews (the action was already decided by a no-coverage default; the item asks whether a rule should exist). The two categories take different response bodies. These are management endpoints — approvals normally arrive as Slack, Teams, or email prompts, or through the dashboard’s Escalations page. A harness key receives 403 harness_key_not_permitted here.

GET /allow/hitl/queue

List queue items. Defaults to status=pending, ordered oldest-first (FIFO for approvers); non-pending queries return newest-first. Query parameters:

Parameter	Description
`page`, `limit`	Pagination (defaults `1` / `50`, max `100`)
`status`	`pending` (default) \| `approved` \| `rejected` \| `timeout` \| `expired` \| `dismissed` \| `resolved` \| `all`
`category`	`enduser` \| `engineer` \| `finance` \| `security` \| `compliance` \| `other` \| `all`

Response:

{
  "data": [
    {
      "id": "hitl-uuid",
      "decision_id": "decision-uuid",
      "agent_id": "billing-agent",
      "target_app": "stripe.com",
      "action": "POST /v1/charges",
      "context": { "amount": 5000 },
      "category": "enduser",
      "status": "pending",
      "ai_recommended_rule": null,
      "notified_via": ["slack"],
      "expires_at": "2026-07-03T10:32:00Z",
      "responded_at": null,
      "responded_by": null,
      "created_at": "2026-07-03T10:30:00Z"
    }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 50
}

Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

POST /allow/hitl/queue

Create an approval item directly, for a client that resolved a retrieval escalate decision locally and needs to queue the human gate without re-evaluating. Writes the decision record and the queue item together — never one without the other. Request body:

{
  "agent_id": "billing-agent",
  "action": "read_customer_pii",
  "context": { "record_count": 200 },
  "reason": "Human approval required by retrieval escalate policy",
  "category": "enduser",
  "timeout_seconds": 120
}

Field	Type	Required	Description
`agent_id`	`string`	Yes	Must be a registered agent (unknown → `404`)
`action`	`string`	Yes	The action awaiting approval (max 255 chars)
`target_app`	`string`	No	Default `"openclaw"`
`context`	`object`	No	Default `{}`
`reason`	`string`	No	Why approval is required (max 1000 chars)
`category`	`string`	No	One of the categories above. Default `engineer`
`rule_code`	`string`	No	The rule code that routed this action to approval, recorded on the decision
`timeout_seconds`	`number`	No	10–120. Default `120`

Response (201): the created queue item. Status codes: 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found (unknown agent), 500 Internal Server Error

POST /allow/hitl/queue/:id

Respond to a pending item. The request body depends on the item’s category. enduser items (live approval gates) — approve or reject:

{
  "decision": "approved",
  "responded_by": "reviewer@example.com"
}

Field	Type	Required	Description
`decision`	`approved` \| `rejected`	Yes	The human’s decision
`responded_by`	`string`	Yes	Who responded (email or name, max 255 chars)

All other categories (coverage-gap reviews) — dismiss, or link the rule you created to cover the gap:

{
  "action": "create_rule",
  "responded_by": "reviewer@example.com",
  "linked_rule_id": "rule-uuid"
}

Field	Type	Required	Description
`action`	`dismiss` \| `create_rule`	Yes	Dismiss the gap or record the covering rule
`responded_by`	`string`	Yes	Who responded
`linked_rule_id`	`string` (UUID)	For `create_rule`	The rule that now covers this scenario

Sending the wrong body shape for the item’s category returns 400. Response:

{
  "id": "hitl-uuid",
  "decision_id": "decision-uuid",
  "status": "approved",
  "responded_at": "2026-07-03T10:31:12Z",
  "responded_by": "reviewer@example.com"
}

Every response also emits a signed record envelope, so the human decision itself is part of the verifiable audit trail. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 409 Conflict (item already resolved — the current status is returned), 500 Internal Server Error

Audit Log

GET /v1/allow/audit-log

Query the decision audit log. Every decision — local and remote, permit and deny — is recorded, including monitor-mode observations.

Tamper evidence comes from the signed record pipeline, not from the query API: each decision emits a record envelope that receives an asynchronous Ed25519 receipt, is Merkle-batched under a KMS-signed root with an RFC 3161 timestamp, and lands in a hash-chained checkpoint log. Verify any decision server-side via GET /record/envelopes/:id/verify.

Scope: rules:read or allow:read (management keys / dashboard session — harness keys cannot query the log) Query parameters:

Parameter	Type	Description
`agent_id`	`string`	Filter by agent logical ID
`target_app`	`string`	Filter by target application
`decision`	`permit` \| `deny` \| `approval_required` \| `mask`	Filter by decision outcome
`hitl_result`	`approved` \| `rejected` \| `timeout`	Filter by approval resolution
`start_date`	ISO 8601 datetime	Lower bound on `created_at`
`end_date`	ISO 8601 datetime	Upper bound on `created_at`
`page`	`number`	Page index (default `1`)
`limit`	`number`	Records per page (default `50`, max `100`)

Response:

{
  "data": [
    {
      "id": "decision-uuid",
      "agent_id": "billing-agent",
      "target_app": "stripe.com",
      "action": "POST /v1/charges",
      "context": { "amount": 5000 },
      "decision": "permit",
      "reason": "Matched rule: Allow Stripe reads",
      "rule_id": "rule-uuid",
      "hitl_result": null,
      "hitl_responded_at": null,
      "hitl_responded_by": null,
      "created_at": "2026-07-03T10:30:00Z",
      "execution_result": "success",
      "execution_completed_at": "2026-07-03T10:30:02Z",
      "execution_details": "Stripe charge created (ch_1234)"
    }
  ],
  "total": 843,
  "page": 1,
  "pageSize": 50
}

Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden (insufficient scope), 429 Too Many Requests, 500 Internal Server Error

Settings

GET /allow/settings

Get your organization’s action-governance settings. If none exist yet, a defaults row is created and returned (201) — this endpoint always returns a valid settings object. Response:

{
  "id": "settings-uuid",
  "no_coverage_defaults": { "read": "approve", "write": "approve", "delete": "approve", "admin": "approve" },
  "autopilot_enabled": false,
  "hitl_timeout_seconds": 120,
  "notification_channels": [],
  "enduser_hitl_enabled": true,
  "recall_retain_masked_original": false,
  "auto_disable_high_interference": true,
  "recall_floor_disabled_detectors": [],
  "recall_floor_enabled_optin": [],
  "created_at": "2026-07-03T10:00:00Z",
  "updated_at": "2026-07-03T10:00:00Z"
}

Field	Type	Description
`no_coverage_defaults`	`object`	Per-operation-type default when no rule matches in enforce mode: `read`, `write`, `delete`, `admin`, each `approve` \| `deny` \| `ask`. Defaults to all-`approve` (no default disruption — uncovered actions proceed until you tighten them)
`autopilot_enabled`	`boolean`	AI auto-drafts a rule for uncovered scenarios and permits the request while it awaits review
`hitl_timeout_seconds`	`number`	Approval wait window, 30–120 seconds. Default `120` — the hard ceiling; unapproved requests fall back per `hitl_fallback`
`notification_channels`	`array`	Organization-level approval notification channels (`{type, config}` entries). Configure channels under Integration → Connectors
`enduser_hitl_enabled`	`boolean`	When `false`, `ask` no-coverage defaults resolve without holding the agent (recorded as bypassed)
`recall_retain_masked_original`, `recall_floor_disabled_detectors`, `recall_floor_enabled_optin`	—	Retrieval-governance settings sharing this row; see the retrieval-governance docs
`auto_disable_high_interference`	`boolean`	Automatically disable a rule that inhibits more than 5% of recent evaluations. Default on

Status codes: 200 OK, 201 Created (first access, defaults created), 401 Unauthorized, 500 Internal Server Error

PUT /allow/settings

Update settings. Validated field ranges are as documented above — in particular hitl_timeout_seconds must be 30–120 (a higher value is rejected with 400, and the evaluation path clamps to 120 regardless).

This endpoint replaces the settings row: fields you omit are reset to their defaults, and no_coverage_defaults is stored exactly as sent. Read the current settings first and send the complete object back with your changes.

Request body:

{
  "no_coverage_defaults": { "read": "approve", "write": "ask", "delete": "deny", "admin": "deny" },
  "autopilot_enabled": false,
  "hitl_timeout_seconds": 120,
  "notification_channels": [],
  "enduser_hitl_enabled": true,
  "auto_disable_high_interference": true
}

Response: the updated settings object. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

​Authentication

​Rate limiting

​List responses

​Evaluation

​POST /allow/evaluate

​GET /allow/rules/bundle

​GET /v1/allow/decisions/:id

​POST /allow/telemetry

​POST /allow/execution-events

​POST /allow/agents/register

​GET /allow/agents/me/stream

​Agents

​GET /allow/agents

​POST /allow/agents

​GET /allow/agents/:id

​PUT /allow/agents/:id

​POST /allow/agents/:id/regenerate-naming

​DELETE /allow/agents/:id

​Rules

​GET /allow/rules

​POST /allow/rules

​POST /allow/rules/compile

​GET /allow/rules/:id

​PUT /allow/rules/:id

​DELETE /allow/rules/:id

​Human-in-the-Loop Queue

​GET /allow/hitl/queue

​POST /allow/hitl/queue

​POST /allow/hitl/queue/:id

​Audit Log

​GET /v1/allow/audit-log

​Settings

​GET /allow/settings

​PUT /allow/settings

Authentication

Rate limiting

List responses

Evaluation

POST /allow/evaluate

GET /allow/rules/bundle

GET /v1/allow/decisions/:id

POST /allow/telemetry

POST /allow/execution-events

POST /allow/agents/register

GET /allow/agents/me/stream

Agents

GET /allow/agents

POST /allow/agents

GET /allow/agents/:id

PUT /allow/agents/:id

POST /allow/agents/:id/regenerate-naming

DELETE /allow/agents/:id

Rules

GET /allow/rules

POST /allow/rules

POST /allow/rules/compile

GET /allow/rules/:id

PUT /allow/rules/:id

DELETE /allow/rules/:id

Human-in-the-Loop Queue

GET /allow/hitl/queue

POST /allow/hitl/queue

POST /allow/hitl/queue/:id

Audit Log

GET /v1/allow/audit-log

Settings

GET /allow/settings

PUT /allow/settings