Gate API

Ask whether an action may run.

Evaluate an action#

POST https://api.cognaone.com/api/actions/evaluate
Authorization: Bearer <agent token>
Content-Type: application/json

{
  "threadId": "thr_claims_0142",
  "actionType": "payment.release",
  "clientRequestId": "req_7f3c91",
  "payload": { "amount": 48000, "currency": "AUD" },
  "evaluationMode": "enforce"
}

Request fields#

Field	Required	Description
`threadId`	Yes	The thread whose governed state the action relies on
`actionType`	Yes	The action, for example payment.release; gate policies are set per action type
`clientRequestId`	Recommended	Your ID for this request; reuse it on retries
`payload`	No	The details of the action, as a JSON object
`evaluationMode`	No	`enforce` (default) or `observe`
`runtimeId`	No	A registered runtime of this agent, for telemetry

Decisions#

Decision	Your agent should
Allow	Proceed with the action
Warn	Proceed, and surface the warnings
Defer	Not act yet. An approval or more facts are needed; evaluate again once resolved
Block	Not act. Show the reasons to a person, or fix them and evaluate again

Reason codes explain the decision, for example gate_block_missing_key, gate_block_conflict or gate_warn_policy_violation. See Decisions and verdicts.

Observe, then enforce#

With evaluationMode: "observe", the gate evaluates and records the decision as observed, not enforced, so you can see what would have been blocked before enforcing anything.

Good practice#

01
Call the gate immediately before acting
Not at the start of a long task: state may change in between.
02
Treat errors as a block
If the gate cannot be reached or returns an error, do not act. Fail closed.
03
Reuse the clientRequestId on retries
A retry then returns the original decision rather than a second evaluation.
04
Keep the receipt ID
Log lineage.receiptId with the action so outcomes can be traced to their receipt.

Last reviewed October 2026Suggest a change