Evaluate an action

POST/v1/decisions

Create a decision before dispatching an action. The response tells your integration to Allow, Require approval, or Block. Your integration must apply that result in Enforcing mode.

Request fields

Field	Required	Description
idempotency_key	Yes	Stable key for this logical action.
action.type	Yes	Operation name, such as refund.create.
action.attributes	No	Parameters needed by the policy.
context	No	Trusted business facts needed by the policy.
mode	No	ENFORCING by default, or MONITORING.
agent.id	No for agent keys	Inferred from the key if omitted. If supplied, must match it.
intended_call	No	Captured call for a supported managed execution integration. Use the SDK to construct it.

Monitoring records the effect without creating an approval request or managed call. It cannot be combined with intended_call. Both modes can affect usage counters.

Example

curl --request POST "https://app.actera.dev/v1/decisions" \
  --header "Authorization: Bearer $ACTERA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotency_key": "refund-request-01842",
    "mode": "ENFORCING",
    "action": {
      "type": "refund.create",
      "attributes": { "amount_minor": 8000, "currency": "GBP", "customer_id": "cus_123" }
    },
    "context": { "customer": { "fraud_flagged": false } }
  }'

The key identifies the agent. This request represents £80 using integer minor units.

Response

Returns 200 OK with the decision directly. An example excerpt:

{
  "id": "8a841842-99b2-4c10-8df1-9012e3d45678",
  "agent_id": "agent-from-connection-setup",
  "action_type": "refund.create",
  "mode": "ENFORCING",
  "effect": "ALLOW",
  "status": "ALLOWED",
  "explanation": "Refund is within the agent's authority",
  "idempotency_key": "refund-request-01842",
  "action_intent": null
}

Enforce effect and retain id. action_intent is populated only when a managed call was captured. Full policy investigation is available in Decisions; applications can check decision status.

When no rule matches, the agent’s When no policy matches setting decides. New agents default to Allow, so inspect the reason and policy evidence when verifying coverage.

Retry behavior

Retry temporary failures with the same key and input. An existing resolved decision keeps its original result after policy publication. A changed request under the same key returns 409.

A successful authorization response does not mean the action executed. After a plain request, report the outcome. For managed calls, use the SDK’s execution-reporting flow.