Evaluate an action

Use Actera’s evaluate operation at a trusted enforcement boundary before an AI agent performs a real side effect. It creates one authoritative decision and returns the ALLOW, REQUIRE_APPROVAL, or BLOCK effect that the integration must enforce.

POST/v1/evaluate

Configuration and parameters

Use ACTERA_BASE_URL, ACTERA_ACCESS_TOKEN, and ACTERA_WORKSPACE_ID as described in API conventions.

Parameter	Location	Required	Description
Actera-Workspace-Id	Header	Yes	Workspace UUID selected by the authenticated principal.

Request fields

Field	Required	Description
idempotency_key	Yes	Stable key for this logical action.
agent.id	Yes	Configured agent identity.
action.type	Yes	Stable operation name used for applicability.
action.attributes	No	Domain values required by policy.
context	No	Additional immutable facts required by policy.
intended_call	No	Call envelope for supported managed-resume integrations.

Request

curl --request POST "$ACTERA_BASE_URL/v1/evaluate" \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $ACTERA_ACCESS_TOKEN" \
  --header "Actera-Workspace-Id: $ACTERA_WORKSPACE_ID" \
  --data '{
    "idempotency_key": "refund-request-01842",
    "agent": { "id": "refund-agent" },
    "action": { "type": "refund.create", "attributes": { "amount": 80, "currency": "GBP" } },
    "context": { "customer": { "previous_refunds": 0, "fraud_flagged": false } }
  }'

const decision = await actera.authorizeAction({
  agent: { id: 'refund-agent' },
  action: { type: 'refund.create', attributes: { amount: 80, currency: 'GBP' } },
  context: { customer: { previous_refunds: 0, fraud_flagged: false } },
  idempotencyKey: 'refund-request-01842',
})

if (decision.effect === 'ALLOW') await performAction()
else if (decision.effect === 'REQUIRE_APPROVAL') await pauseForApproval(decision.id)
else throw new Error(decision.explanation || 'Actera blocked the action')

Response excerpt

{
  "id": "dec_7f26",
  "agent_id": "refund-agent",
  "action_type": "refund.create",
  "effect": "ALLOW",
  "status": "ALLOWED",
  "policy_bundle_version": "12",
  "matched_policy_ids": ["pol_refund_small"],
  "matched_rules": ["small-refund-allow"],
  "explanation": "Low-value refund is allowed",
  "version": "4"
}

The response contains additional evidence. Enforce effect, retain id, and retrieve the decision later. See Actions and context for input semantics and Decisions and approvals for lifecycle states.

Errors and retries

Missing required identity or idempotency fields returns 400. Reusing a key for different input returns 409. Retry temporary failures with the same key; never create a new key merely because a response was lost. See API conventions for the error model and the TypeScript integration for the complete boundary pattern.