Skip to main content
POST
Evaluate an agent action

Authorizations

Authorization
string
header
required

A VisIQ API key presented as Authorization: Bearer vq_prod_.... Mint harness keys under Settings → Harness Keys and API keys under Settings → API Keys in the dashboard.

Body

application/json
agent_id
string
required
Required string length: 1 - 255
target_app
string
required
Required string length: 1 - 255
action
string
required
Required string length: 1 - 255
context
object

Arbitrary decision inputs (e.g. amount, resource id).

session_id
string
Required string length: 1 - 255
action_schema_id
string

The action-schema identity the SDK computed for this event. When omitted, the server derives it from context.

Required string length: 1 - 128
mcp_server
string

The MCP server the tool call came from. A server your registry marks blocked, or one that drifted from its approved definition, is denied whatever the rule outcome.

Required string length: 1 - 255
identity
object

Identity evidence for the event, read by rules as input.session.identity.*. Put a principal in attested only when it came through a channel the agent cannot author (an IdP assertion, your application's own request context, or a check you performed). A principal the model only read in the conversation goes in claimed, which grants nothing. Unknown keys are refused with 400.

telemetry
object

Response

The enforced decision.

decision_id
string<uuid>
required
decision
enum<string>
required
Available options:
permit,
deny,
approval_required,
mask
reason
string
required
enforced
boolean
required
agent_mode
enum<string>
required
Available options:
off,
monitor,
enforce
rule_code
string | null

The matched rule code (synthetic D-* for defaults; null in off-mode).

plane
enum<string> | null
Available options:
action,
retrieval,
delegation,
null
operation
string | null
is_retrieval
boolean
arg_redaction_rules
object[]

Present only when decision is mask.

hitl_fallback
enum<string>

Present only when decision is approval_required, as the fallback if no human responds.

Available options:
mask,
deny