Quickstart

Record governed state, evaluate an action and read the decision history in three calls.

1. Record a fact as governed state

Send the facts your agent relies on. Each item has a key, a value, a type and a source. Cogna8 classifies, versions and checks it for conflicts.

POST /v1/state/items
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "session_id": "sess_abc123",
  "key": "project.budget",
  "value": "$4.2M",
  "type": "fact",
  "source": "user_input"
}

2. Ask before acting

Call the gate with the action your agent wants to take. The response tells you whether it may proceed, and why.

POST /v1/gates/evaluate
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "session_id": "sess_abc123",
  "action": "send_invoice"
}

3. Read the history

Every state change and decision is in the append-only history. Use the decision ID to trace an outcome.

GET /v1/history/events?session_id=sess_abc123&type=gate_evaluation&limit=10
Authorization: Bearer sk_live_...

What next

Verdicts at a glance: Allow Warn Block See Decisions and verdicts. Keys such as project.budget are explained in Canonical keys.