API Reference

Retrieval-governance endpoints are mounted under /recall/*, with the versioned audit-log read at /v1/recall/audit-log. The base URL is https://api.visiqlabs.com. Action governance and retrieval governance share a single rule engine — each rule declares which facets it applies to. The endpoints on this page are the retrieval facet: they govern what your agents can see (retrieved documents, tool results, rendered prompts), with decisions allow, deny, redact, and escalate.

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. On the retrieval surface the operational allowlist covers exactly POST /recall/evaluate and GET /recall/rules/bundle — calling any other endpoint on this page with a harness key 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 requires rules:evaluate (or the legacy recall:write); reads require rules:read (or the legacy recall:read); rule mutations require rules:write (or the legacy recall:write); 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. Both accept a harness key. The SDK evaluates most retrievals locally from the cached rule bundle — the server and the SDK run the same policy interpreter over the same rule source, so local and remote decisions agree by construction.

POST /recall/evaluate

Evaluate a retrieval against your suppression rules and return a decision. Scope: rules:evaluate or recall:write Request body:

{
  "agent_id": "research-bot",
  "operation": "retrieve",
  "resource_type": "document",
  "resource_metadata": {
    "classification": "confidential",
    "department": "finance"
  },
  "surface": "public_channel",
  "query": "quarterly revenue figures"
}

Field	Type	Required	Description
`agent_id`	`string`	Yes	Identifier of the agent making the retrieval (1–255 chars)
`operation`	`retrieve` \| `tool_call` \| `prompt_render`	Yes	Which hook produced the content: a retriever, a tool result, or prompt assembly
`resource_type`	`string`	No	Resource type being accessed. Default `document` (1–255 chars)
`resource_metadata`	`object`	No	Metadata about the resource (classification, department, …). Default `{}`
`trust_tier`	`string`	No	Fallback trust tier — see the note below (max 50 chars)
`surface`	`string`	No	Delivery surface for the output, matched exactly against surface-scoped rules (max 100 chars)
`query`	`string`	No	The retrieval query string (max 2000 chars)
`telemetry`	`object`	No	Opaque client telemetry, attached to the decision’s signed record envelope

Agent attributes are server-authoritative. The platform looks up agent_id in the agent registry and hydrates its assigned trust tier, categories, and business function into rule input (input.agent.*). An assigned trust tier overrides the request’s trust_tier — the body value is only a fallback for agents with no assigned tier, so varying it in a request cannot spoof a tier-gated rule. Unlike the action facet’s evaluate endpoint, this endpoint does not auto-provision unknown agents.

For an agent in monitor mode, a non-allow decision is normalized to allow before it is recorded and returned, with reason_code: "MONITOR_MODE" and the engine’s original reason preserved behind a Monitor: prefix.

Response:

{
  "decision_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "redact",
  "reason_code": "POLICY_DENY",
  "reason": "Matched rule: Mask account numbers for support agents",
  "redaction_rules": [
    { "field": "ssn", "mode": "full", "replacement": "[REDACTED]" },
    { "field": "account_number", "mode": "partial", "keepLast": 4, "maskChar": "*" }
  ]
}

Field	Type	Description
`decision_id`	`string` (UUID)	Unique ID for this decision — used for audit and the retained-original reveal
`decision`	`allow` \| `deny` \| `redact` \| `escalate`	The suppression outcome
`reason_code`	`string`	Machine-readable reason — see the table below
`reason`	`string`	Human-readable explanation
`redaction_rules`	`array`	Present on a `redact` decision (and on an `escalate` whose fallback is `mask`) — see below
`hitl_fallback`	`deny` \| `mask`	Present on an `escalate` decision — see below

Decision semantics:

allow — the content passes to the agent unchanged.
deny — the content is suppressed; the agent never sees it.
redact — the content proceeds with the accompanying redaction_rules applied.
escalate — hold the content for human review; if no human approves in time, fall back per hitl_fallback.

Redaction directives. Each entry in redaction_rules may include field, pattern, replacement, mode (full | partial | email | custom), keepFirst, keepLast, maskChar, and keepPattern. full replaces the whole match (the default); partial keeps the first/last characters; email keeps the first character of the local part plus the domain; custom keeps every keepPattern match and masks the rest. A redact decision from a rule whose directives resolve to nothing passes content through unchanged — unless the rule is flagged fail-closed, in which case the decision is downgraded to deny server-side. The escalate decision tells your harness to hold the content for human review — this endpoint does not itself notify approvers; register the approval through the human-in-the-loop flow (see Human-in-the-Loop). hitl_fallback tells the harness what to do when no human responds in time: deny (the default, fail-closed) or mask (proceed with the accompanying redaction_rules applied). Reason codes:

Code	Meaning
`POLICY_ALLOW`	A matched rule’s conditions evaluated to allow
`POLICY_DENY`	A matched rule’s conditions produced a non-allow outcome (deny, redact, or escalate)
`TIER_MISMATCH`	The agent’s trust tier is below the minimum required by the rule or resource
`PRINCIPAL_EXCLUDED`	The agent is on the rule’s (or resource’s) principal exclusion list
`SURFACE_RESTRICTION`	A surface-scoped rule applied to this delivery surface and did not allow it
`AUDIENCE_EXPANSION`	Reserved — defined in the decision vocabulary but not currently emitted by the engine
`DEFAULT_DENY`	No rule matched — the retrieval facet fails closed
`EMERGENCY_BYPASS`	An active emergency bypass on the matched rule allowed the request
`MONITOR_MODE`	The agent runs in monitor mode — a non-allow decision was recorded but returned as `allow`

The response carries no receipt ID — tamper evidence is asynchronous. For organizations with artifact signing enabled, each decision emits a record envelope that receives an Ed25519 receipt off the request path, is Merkle-batched under a KMS-signed root with an RFC 3161 timestamp, and lands in a hash-chained checkpoint log. Verify a decision’s record envelope server-side via GET /record/envelopes/:id/verify (:id is the record envelope’s UUID, not the decision_id returned here).

Minimum-necessary at rest: the decision is evaluated against the real values, but the persisted copies of resource_metadata and query are masked — first by the matched rule’s redaction directives, then by an always-on value-shape redaction floor. The raw original is discarded by default; organizations can opt in to retaining it encrypted, revealable only via the retained-original endpoint.

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

curl -X POST https://api.visiqlabs.com/recall/evaluate \
  -H "Authorization: Bearer $VISIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "research-bot",
    "operation": "retrieve",
    "resource_type": "document",
    "resource_metadata": { "classification": "confidential" }
  }'

GET /recall/rules/bundle

Fetch your enabled retrieval rules as one bundle for local evaluation. Clients can cache this bundle and revalidate it with If-None-Match, so retrieval decisions on the hot path never wait on the network. (The VisIQ SDK consumes the unified GET /rules/bundle, which carries both facets.) 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...",
  "rules": [
    {
      "id": "rule-uuid",
      "name": "Deny tier3 from confidential",
      "rego_source": "package recall.rules.tier3_guard\n\ndefault decision = \"deny\"\n...",
      "trust_tier": "tier3",
      "surface": null,
      "principal_exclusions": [],
      "priority": 50
    }
  ]
}

Field	Description
`version`	SHA-256 hash of the serialized rules array — changes whenever any included rule changes
`rules`	Enabled retrieval rules, sorted by priority descending. Each carries its full `rego_source` for local evaluation. Rules without policy source are excluded from the bundle (they are not yet enforceable)

Response headers:

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

Status codes: 200 OK, 304 Not Modified, 401 Unauthorized, 403 Forbidden (insufficient scope), 500 Internal Server Error

Rules

Rule management. These are management endpoints — a harness key receives 403 harness_key_not_permitted here. 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 /recall/rules

List retrieval 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": "Deny tier3 from confidential",
      "description": "Prevent low-trust agents from accessing sensitive data",
      "natural_language": "Deny tier3 agents from internal, confidential, or restricted data",
      "priority": 50,
      "enabled": true,
      "trust_tier": "tier3",
      "surface": null,
      "principal_exclusions": null,
      "bypass_active": false,
      "bypass_reason": null,
      "bypass_activated_by": null,
      "bypass_activated_at": null,
      "bypass_expires_at": null,
      "created_at": "2026-07-03T10:00:00Z",
      "updated_at": "2026-07-03T10:00:00Z"
    }
  ],
  "total": 8,
  "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 /recall/rules

Create a retrieval rule. Request body:

{
  "name": "Deny tier3 from confidential",
  "description": "Prevent low-trust agents from accessing sensitive data",
  "rego_source": "package recall.rules.tier3_guard\n\ndefault decision = \"deny\"\n\ndecision = \"deny\" if {\n  input.resource_metadata.classification in [\"internal\", \"confidential\", \"restricted\"]\n}",
  "natural_language": "Deny tier3 agents from accessing internal, confidential, or restricted data",
  "priority": 50,
  "enabled": true,
  "trust_tier": "tier3"
}

Field	Type	Required	Description
`name`	`string`	Yes	Rule name (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`
`trust_tier`	`string`	No	Minimum trust tier this rule requires (`tier1` is highest trust, `tier3` lowest). Agents below the minimum are denied with `TIER_MISMATCH` (max 50 chars)
`surface`	`string`	No	Exact-match surface restriction — the rule applies only to retrievals delivered to this surface (max 100 chars)
`principal_exclusions`	`string[]`	No	Agent IDs this rule excludes — an excluded agent is denied with `PRINCIPAL_EXCLUDED`

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 decision (allow, deny, redact, escalate) is derived from the policy body. Prefer POST /recall/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, 500 Internal Server Error

POST /recall/rules/compile

Compile a natural-language description into a retrieval 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": "Deny tier3 agents from accessing any document classified as internal, confidential, or restricted"
}

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 recall.rules.tier3_guard\n\ndefault decision = \"deny\"\n...",
  "natural_language": "This rule denies tier3 agents access to internal, confidential, or restricted documents...",
  "name": "Compiled retrieval rule",
  "description": "AI-compiled suppression rule",
  "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, 503 Service Unavailable (rule compilation is not configured in this environment)

GET /recall/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 /recall/rules/:id

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

DELETE /recall/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

Emergency Bypass

Temporarily suspend one rule’s enforcement during an incident — see Emergency Bypass for when and why. Bypasses auto-expire; expiry is checked at evaluation time, so there is no revocation lag. Both activation and deactivation are written to the audit log with reason code EMERGENCY_BYPASS.

POST /recall/rules/:id/bypass

Activate an emergency bypass on a rule. While active, any request that reaches the bypassed rule in the priority cascade returns allow with reason code EMERGENCY_BYPASS — even requests the rule’s conditions would not have matched — and lower-priority rules never run for it. Higher-priority rules keep enforcing. Request body:

{
  "reason": "Incident INC-2041: unblocking on-call diagnosis",
  "duration_minutes": 30
}

Field	Type	Required	Description
`reason`	`string`	Yes	Why the bypass is needed (min 10 chars) — recorded in the audit log
`duration_minutes`	`number`	Yes	One of `15`, `30`, `60`, `120`. The bypass expires automatically

Response: the full rule object with the bypass fields populated:

{
  "id": "rule-uuid",
  "name": "Deny tier3 from confidential",
  "bypass_active": true,
  "bypass_reason": "Incident INC-2041: unblocking on-call diagnosis",
  "bypass_activated_by": "user-uuid",
  "bypass_activated_at": "2026-07-03T10:30:00Z",
  "bypass_expires_at": "2026-07-03T11:00:00Z",
  "...": "..."
}

Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 409 Conflict (a bypass is already active on this rule), 500 Internal Server Error

DELETE /recall/rules/:id/bypass

Deactivate an active bypass before it expires. Response: the full rule object with the bypass fields cleared. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 409 Conflict (no active bypass on this rule), 500 Internal Server Error

Audit Log

GET /v1/recall/audit-log

Query the retrieval decision audit log. Every decision made through this endpoint — allow and deny, including monitor-mode observations and bypass activations — is recorded. (Locally evaluated SDK decisions surface through the runtime telemetry pipeline instead.) The log is append-only; no writes are accepted via this API.

Tamper evidence comes from the signed record pipeline, not from the query API: for organizations with artifact signing enabled, 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 a decision’s record envelope server-side via GET /record/envelopes/:id/verify.

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

Parameter	Type	Description
`agent_id`	`string`	Filter by agent logical ID
`operation`	`string`	`retrieve` \| `tool_call` \| `prompt_render` \| `emergency_bypass_activate` \| `emergency_bypass_deactivate`
`decision`	`string`	`allow` \| `deny` \| `redact` \| `escalate`
`reason_code`	`string`	`TIER_MISMATCH` \| `PRINCIPAL_EXCLUDED` \| `POLICY_DENY` \| `AUDIENCE_EXPANSION` \| `SURFACE_RESTRICTION` \| `POLICY_ALLOW` \| `DEFAULT_DENY` \| `EMERGENCY_BYPASS`
`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`)

Rows recorded under monitor mode carry reason_code: "MONITOR_MODE"; it is not yet accepted as a filter value. Response:

{
  "data": [
    {
      "id": "audit-entry-uuid",
      "agent_id": "research-bot",
      "operation": "retrieve",
      "resource_type": "document",
      "decision": "deny",
      "reason_code": "TIER_MISMATCH",
      "reason": "agent trust tier 'tier3' (level 1) is below the required minimum 'tier2' (level 2)",
      "rule_id": "rule-uuid",
      "receipt_id": null,
      "metadata": {
        "surface": "public_channel",
        "trust_tier": "tier3",
        "query": "quarterly revenue",
        "resource_metadata": { "classification": "confidential" },
        "floor_detectors": [],
        "decision_id": "decision-uuid"
      },
      "created_at": "2026-07-03T10:30:00Z"
    }
  ],
  "total": 1247,
  "page": 1,
  "pageSize": 50
}

metadata.query and metadata.resource_metadata are the masked persisted copies (rule directives plus the always-on redaction floor); metadata.floor_detectors names any floor detectors that fired, and metadata.decision_id is the underlying decision’s ID for the retained-original reveal below. receipt_id is a legacy column and is null on new rows — receipts flow through the record pipeline instead. Status codes: 200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden (insufficient scope), 429 Too Many Requests, 500 Internal Server Error

Retained Originals

GET /recall/decisions/:id/unmask

Reveal the retained, encrypted original payload for one retrieval decision. Persisted copies are masked at rest; when your organization has enabled retained-original storage (off by default), the raw resource_metadata and query are additionally stored AES-256-GCM-encrypted, and this endpoint decrypts them. This is a management endpoint gated on the payloads:unmask permission — only explicitly-authorized roles can ever see the original values, and every reveal is logged with who requested it. Harness keys receive 403. Path parameter: :id — the decision UUID (decision_id from POST /recall/evaluate, or metadata.decision_id on an audit-log row) Response:

{
  "decision_id": "decision-uuid",
  "original": {
    "resource_metadata": { "classification": "confidential", "account_number": "4111111111111111" },
    "query": "quarterly revenue figures"
  }
}

Status codes: 200 OK, 400 Bad Request (invalid UUID), 401 Unauthorized, 403 Forbidden, 404 Not Found (unknown decision, or retention is disabled for your organization), 500 Internal Server Error

Quickstart

Action Governance

Retrieval Governance

Audit Trail

Discovery

API Examples

Platform Automation

Partners

API Reference

Authentication

Rate limiting

List responses

Evaluation

POST /recall/evaluate

GET /recall/rules/bundle

Rules

GET /recall/rules

POST /recall/rules

POST /recall/rules/compile

GET /recall/rules/:id

PUT /recall/rules/:id

DELETE /recall/rules/:id

Emergency Bypass

POST /recall/rules/:id/bypass

DELETE /recall/rules/:id/bypass

Audit Log

GET /v1/recall/audit-log

Retained Originals

GET /recall/decisions/:id/unmask

​Authentication

​Rate limiting

​List responses

​Evaluation

​POST /recall/evaluate

​GET /recall/rules/bundle

​Rules

​GET /recall/rules

​POST /recall/rules

​POST /recall/rules/compile

​GET /recall/rules/:id

​PUT /recall/rules/:id

​DELETE /recall/rules/:id

​Emergency Bypass

​POST /recall/rules/:id/bypass

​DELETE /recall/rules/:id/bypass

​Audit Log

​GET /v1/recall/audit-log

​Retained Originals

​GET /recall/decisions/:id/unmask

Authentication

Rate limiting

List responses

Evaluation

POST /recall/evaluate

GET /recall/rules/bundle

Rules

GET /recall/rules

POST /recall/rules

POST /recall/rules/compile

GET /recall/rules/:id

PUT /recall/rules/:id

DELETE /recall/rules/:id

Emergency Bypass

POST /recall/rules/:id/bypass

DELETE /recall/rules/:id/bypass

Audit Log

GET /v1/recall/audit-log

Retained Originals

GET /recall/decisions/:id/unmask