Human approvals

The review lifecycle#

1. An agent checks a proposal.
2. The API returns requires_human and a confirmation ID.
3. Your integration retains the proposal and keeps execution paused.
4. The owner reads its metadata and approves or denies.
5. The agent polls and proceeds only if approved.

Signed webhooks and push notifications are not implemented. Provide your own reviewer notification path and poll for the final result.

Find and inspect pending reviews#

curl --fail-with-body "$KERNALL_BASE_URL/api/confirmations?status=pending&limit=100"

Use GET /api/confirmations/<id> for one record. It includes action type, destination, context, detected category, reason, and timestamps. Raw data is absent; provide any necessary review material through your own appropriately protected workflow.

Resolve a review#

# Use the confirmation_id from your check response.
export KERNALL_CONFIRMATION_ID="paste-the-confirmation-id"

# Local development: the reviewer resolves this specific action.
curl --fail-with-body -X POST \
  "$KERNALL_BASE_URL/api/confirmations/$KERNALL_CONFIRMATION_ID/resolve" \
  -H 'Content-Type: application/json' \
  -d '{"decision":"approved"}'

For denial, send {"decision":"denied"}. Hosted resolution requires the owner’s authenticated identity, not the agent key.

The first resolution wins. Repeating the same outcome returns the resolved record. Changing it returns 409 already_resolved. A changed proposal needs a new check.

Poll from agent code#

curl --fail-with-body \
  "$KERNALL_BASE_URL/api/confirmations/$KERNALL_CONFIRMATION_ID/status" \
  -H "Authorization: Bearer $KERNALL_API_KEY"

{
  "confirmation_id": "<confirmation-id>",
  "status": "pending",
  "decision": "requires_human",
  "resolved_at": null
}

After resolution, both status and decision are approved or denied, with an ISO resolved_at. Use bounded polling; the Python client defaults to a two-second interval and five-minute wait.

A client timeout does not resolve, expire, or delete the server review. No automatic expiry or cancel endpoint exists. Stop the action on timeout and explicitly decide whether to resume waiting later.

Using the dashboard preview#