API Reference

The unified rule surface is mounted under /rules/*, with the single evaluation call at /evaluate. The base URL is https://api.visiqlabs.com. One rules collection spans every operation. Each rule declares an operations[] array (its stored applies_to) drawn from action, retrieval, and delegation, and the engine evaluates one event against the operations it carries.

The per-facet management endpoints — /allow/rules (action) and /recall/rules (retrieval) — are additive, permanent compatibility aliases over the same rules table, not deprecated surfaces. A rule created here appears there and vice versa; issued keys keep their existing grants. Use whichever surface fits your integration.

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. On this surface a harness key covers exactly GET /rules/bundle and POST /evaluate; calling the rule-management endpoints (GET/POST /rules, GET/PUT/DELETE /rules/:id) 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.

The management CRUD reuses the action-facet permissions (allow_rules:view / :create / :update / :delete), so a key or role that already manages action rules manages unified rules unchanged. Evaluation is scope-gated: POST /evaluate accepts the operation-native rules:evaluate or the legacy allow:write / recall:write; full_access satisfies everything.

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

The list endpoint returns the standard envelope:

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

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

Evaluation

POST /evaluate

The single SDK-facing evaluation call for every governed event. The request declares which operations the event performs, and the response carries the union decision vocabulary — so one contract spans every facet. This is a pure projection onto the same plane handlers the per-facet evaluate endpoints use: there is exactly one decision implementation. Scope: rules:evaluate, allow:write, or recall:write Request body (operation-native form):

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

Field	Type	Required	Description
`operations`	`string[]`	Yes	1–3 of `action`, `retrieval`, `delegation`
`agent_id`	`string`	Yes	The agent making the request (1–255 chars)
`target_app`	`string`	When `operations` include `action`/`delegation`	Hostname or app identifier (1–255 chars)
`action`	`string`	When `operations` include `action`/`delegation`	The action string — HTTP method + path or tool name (1–255 chars)
`context`	`object`	No	Key-value context for action/delegation rule matching. Default `{}`
`operation`	`retrieve` \| `tool_call` \| `prompt_render`	No	Retrieval hook that produced the content. Default `retrieve`
`resource_type`	`string`	When `operations` include `retrieval`	Resource type being accessed (1–255 chars)
`resource_metadata`	`object`	No	Metadata for retrieval rule matching. Default `{}`
`trust_tier`	`string` \| `null`	No	Fallback trust tier for retrieval (an assigned tier overrides it) (max 64 chars)
`surface`	`string` \| `null`	No	Delivery surface for retrieval, matched exactly against surface-scoped rules (max 128 chars)
`query`	`string` \| `null`	No	The retrieval query string (max 4000 chars)
`telemetry`	`object`	No	Opaque client telemetry attached to the decision’s record envelope

A delegation operation projects onto the action facet (it therefore requires target_app and action), which runs the delegation-facet policy check — the orchestrate.delegate authority transfer. This is the stateless policy leg; the grant/token lifecycle lives on the delegation endpoints.

A legacy kind-discriminated form is still accepted and behaves identically: { "kind": "action", ... } or { "kind": "retrieval", ... }. The operations[] form is canonical.

Response (single-operation):

{
  "operations": ["action"],
  "decision": "permit",
  "plane_decision": "permit",
  "decision_id": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "Matched rule: Allow Stripe reads",
  "reason_code": null,
  "rule_code": "R-1042",
  "enforced": true,
  "agent_mode": "enforce"
}

Field	Type	Description
`decision`	`string`	The union outcome — see the table below
`plane_decision`	`string`	The facet handler’s original word (e.g. a retrieval `allow`, before it maps to `permit`)
`decision_id`	`string` (UUID) \| `null`	The underlying decision’s id, for audit and polling
`reason` / `reason_code` / `rule_code`	—	Explanation, machine-readable reason, and the matched rule code
`enforced` / `agent_mode`	—	Whether the decision was enforced, and the agent’s server-authoritative mode
`redaction_rules`	`array`	Present when the outcome carries masking directives
`hitl_fallback`	`deny` \| `mask`	Present on an outcome that can fall back after a human timeout

The union decision vocabulary:

Outcome	Facet	Meaning
`permit`	any	The event proceeds unchanged
`deny`	any	Blocked or suppressed
`approval_required`	action	Pauses for a human decision
`mask`	action	Proceeds with named arguments redacted
`redact`	retrieval	Proceeds with fields/patterns masked
`escalate`	retrieval	Recorded for review; passes through (masked if the rule chooses) rather than pausing

Hybrid events. When operations includes both action and retrieval, both facets are evaluated and the response carries a per-operation results[] plus an overall decision equal to the most restrictive facet outcome (fail-closed combine):

{
  "operations": ["retrieval", "action"],
  "decision": "deny",
  "reason": "...",
  "reason_code": null,
  "rule_code": "R-1099",
  "results": [
    { "operation": "retrieval", "decision": "redact", "plane_decision": "redact", "...": "..." },
    { "operation": "action", "decision": "deny", "plane_decision": "deny", "...": "..." }
  ]
}

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

GET /rules/bundle

Fetch the compiled unified rule bundle for local evaluation — every enabled rule whose applies_to overlaps the action ∪ retrieval facets, plus the agent’s mode and attributes. This is the bundle the tagged SDK runtime pulls; it caches it and revalidates with If-None-Match so decisions on the hot path never wait on the network. Permission: allow_rules:view (a harness key passes the audience gate here) Query parameters:

Parameter	Required	Description
`agent_id`	Yes	The agent the bundle is compiled for — carries that agent’s mode and attributes. An unknown id auto-provisions the agent in monitor mode

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...",
  "dialect_version": 1,
  "min_dialect": 1,
  "agent_mode": "enforce",
  "cognition_capture": false,
  "agent_attributes": {
    "trust_tier": "tier2",
    "categories": ["transactional"],
    "business_functions": ["finance_accounting"],
    "business_function": "finance_accounting",
    "blast_radius_tier": null,
    "no_coverage": null
  },
  "rules": [ { "id": "rule-uuid", "applies_to": ["action"], "...": "..." } ],
  "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 over the serialized payload — changes when any rule, the agent’s mode/attributes, or the no-coverage settings change
`dialect_version` / `min_dialect`	The wire-contract dialect this bundle is compiled for, and the minimum an SDK must speak. A client below `min_dialect` refuses the bundle and fails closed
`agent_mode`	The agent’s resolved mode (`enforce` \| `monitor` \| `off`)
`agent_attributes`	Server-authoritative attributes hydrated into `input.agent.*` for local evaluation
`rules`	Enabled effective rules overlapping the action ∪ retrieval facets, priority-descending, parsed by the SDK with the same parser the server uses
`no_coverage`	Your organization’s no-coverage policy, so the SDK resolves uncovered events locally

A shut-down agent (operator kill-switch) receives a terminal bundle — enforce mode, zero rules, all-deny no-coverage — so an SDK that honours the shutdown flag stops immediately, and one that ignores it still denies everything.

Response headers: ETag (quoted SHA-256), Cache-Control: private, max-age=60 Status codes: 200 OK, 304 Not Modified, 400 Bad Request (missing/invalid agent_id), 401 Unauthorized, 404 Not Found (unknown agent after provisioning), 500 Internal Server Error

Rules

Management endpoints — a harness key receives 403 harness_key_not_permitted here. One collection over every operation; the applies_to array on each rule decides which facets it governs.

GET /rules

List rules, priority-descending, optionally filtered to a facet. Permission: allow_rules:view Query parameters: page (default 1), limit (default 50, max 100), operations (optional CSV of action,retrieval,delegation — returns only rules whose applies_to overlaps the set) Response:

{
  "data": [
    {
      "id": "rule-uuid",
      "rule_code": "R-1042",
      "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,
      "applies_to": ["action"],
      "target_app": "stripe.com",
      "action_pattern": "GET *",
      "trust_tier": null,
      "surface": null,
      "principal_exclusions": null,
      "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 /rules

Create a rule. The operations[] array is stored as the rule’s applies_to. Permission: allow_rules:create Request body:

{
  "operations": ["action"],
  "name": "Allow Stripe reads",
  "description": "Permit read-only Stripe API calls",
  "rego_source": "package rules\n\ndefault decision = \"deny\"\n...",
  "natural_language": "Allow my billing agent to read from Stripe",
  "priority": 10,
  "enabled": true,
  "target_app": "stripe.com",
  "action_pattern": "GET *"
}

Field	Type	Required	Description
`operations`	`string[]`	Yes	1–3 of `action`, `retrieval`, `delegation` — stored (deduped, canonical order) as `applies_to`
`name`	`string`	Yes	Rule name, unique per organization (max 255 chars)
`description`	`string`	No	Description (max 1000 chars)
`rego_source`	`string`	Yes	Policy source (1–100000 chars) in the platform’s Rego-subset condition language
`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`
`target_app`	`string` \| `null`	No	Action-facet: hostname/app the rule scopes to (max 255 chars)
`action_pattern`	`string` \| `null`	No	Action-facet: action glob the rule pre-filters on (max 255 chars)
`trust_tier`	`string` \| `null`	No	Retrieval-facet: minimum trust tier the rule requires (max 64 chars)
`surface`	`string` \| `null`	No	Retrieval-facet: exact-match delivery surface restriction (max 128 chars)
`principal_exclusions`	`string[]` \| `null`	No	Retrieval-facet: agent ids the rule excludes

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

GET /rules/:id

Get a single rule by UUID, including rego_source. Permission: allow_rules:view Status codes: 200 OK, 400 Bad Request (invalid rule ID), 401 Unauthorized, 404 Not Found, 500 Internal Server Error

PUT /rules/:id

Update a rule. Every field from POST /rules is accepted and optional; at least one is required (an empty body returns 400 No fields to update). Only provided fields change; supplying operations rewrites applies_to. Permission: allow_rules:update Response: the updated rule object. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 409 Conflict (duplicate name), 500 Internal Server Error

DELETE /rules/:id

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

Errors & conventions

Every endpoint on this page follows the platform-wide REST conventions — the validation-error body shape, the /v1/ vs unversioned split, and the API stability policy. See REST API conventions.

Quickstart

Action Governance

Retrieval Governance

Delegation Governance

Unified Rules

Audit Trail

Discovery

Connectors

API Examples

Platform Automation

Partners

Reference

API Reference

API Reference

Authentication

Rate limiting

List responses

Evaluation

POST /evaluate

GET /rules/bundle

Rules

GET /rules

POST /rules

GET /rules/:id

PUT /rules/:id

DELETE /rules/:id

Errors & conventions

​Authentication

​Rate limiting

​List responses

​Evaluation

​POST /evaluate

​GET /rules/bundle

​Rules

​GET /rules

​POST /rules

​GET /rules/:id

​PUT /rules/:id

​DELETE /rules/:id

​Errors & conventions

Authentication

Rate limiting

List responses

Evaluation

POST /evaluate

GET /rules/bundle

Rules

GET /rules

POST /rules

GET /rules/:id

PUT /rules/:id

DELETE /rules/:id

Errors & conventions