API Reference

Authentication

People sign in to the hosted dashboard with Google or GitHub; agents and services call the API with an API key.

The account your credential belongs to: customer_id, environment and auth_type. customer_id is the Kerneva account id that every decision token binds, and it is the same for test and live keys. A payment layer that verifies decision tokens reads it once and keeps it in its own config.

Evaluation

Evaluate a single action. Inputs: agent_id, session_id, action_type, amount, optional customer_id (end-customer identifier), and metadata. When customer_id is provided, behavioral history is segmented per end-customer. Returns ALLOW / REVIEW / BLOCK plus enforcement metadata when graduated or enforce mode is active.

Evaluate multiple actions in a single request. Useful for batch or replay workflows.

Batch historical analysis over a supplied event list. Alias of /analyze.

Compute detector quality from reviewed history and return quality gates and suppression candidates. Scores the verdict Kerneva would have returned (recommended_decision), so it works on Observation Mode data. Candidates are written to suppressed_signals only when the request sets apply_suppression: true.

Financial Action Contract (v1)

Authorize a proposed financial action described as a versioned FinancialAction (operation, amount, counterparty, workflow, declared purpose, execution target). Idempotent: replaying the same action_id — or the same idempotency_key and execution_target — returns the original DecisionReceipt with replayed set, never a second decision. Counterparty format problems (failed routing-number checksum, invalid IBAN) are surfaced as signals and escalate the verdict rather than rejecting the request.

Close the action lifecycle: executed, failed, canceled, or expired. The server enforces the lifecycle — a blocked action can never be reported as executed, an expired receipt cannot close as executed, and a held action needs its review resolved (human release) first. Transitions are atomic under concurrent reports, and the reporter's identity is recorded. This is what makes the audit trail distinguish a proposed, authorized, held, executed, or failed action.

The published contract: FinancialAction and DecisionReceipt JSON schemas, lifecycle rules, decision-token format, and the availability policy. Receipts carry a decision token (HMAC-signed when the deployment configures a signing secret) that binds an ALLOW to one action and expiry.

Outcome & History

Report whether an evaluated action actually ran: completed, failed, blocked, abandoned, or timed_out, with optional detail. Works with an API key — this is what the SDK's confirm_execution and guard send. Recorded once; completed is refused for a BLOCK, and for a held action until a person releases it.

A person's review of a flagged evaluation: status, resolution, and impact. Signed-in team members only — resolving a review is what releases a held action, so an API key can't do it.

Add operator notes to an evaluation record.

Export evaluation records in CSV format for audit and analysis.

Return the full session trail for a specific workflow, including decisions, signals, and version metadata.

Investigations

List evaluations pending review or requiring attention. Supports query parameters for filtering.

Retrieve operator actions and configuration changes for compliance review.

Kill Switch

Stop agent financial actions immediately — every agent, one agent (agent_id), one action type (action_type), or both. Every matching evaluation returns BLOCK, even in Observation Mode, from the next call on. Any credential can open a halt, including an API key, so an incident script can pull the cord. Safe to repeat.

List active halts, or all of them with include_released=true.

Resume. Admins only, from a signed-in session — an API key can stop money moving but can't restart it.

Payee & Agent Controls

Two policies set with PUT /config. Like every policy they only recommend in Observation Mode and apply once enforcement is on.

New-payee hold (new_counterparty_action_types, default ["invoice_payment"]): the first payment to a payee your account has never paid, or to a bank account a known payee has never been paid at, returns REVIEW. Only payments that actually went through make a payee known, so retrying a held payment never does. Bank accounts are compared by a one-way fingerprint.

Agent allowlist (unregistered_agents: allow, review, or block; default allow): actions from agents an admin hasn't approved are held or blocked. Switching it on approves the agents already running, so nothing stops.

Agents seen in this environment and whether each is approved.

Approve an agent, even before its first action. Admins only — an agent holding an API key can register itself but can never approve itself.

Revoke an approval. Admins only. Under an allowlist, the agent's next action is held or blocked.

Agents & Sessions

Register a new agent for tracking and evaluation.

Retrieve agent details and evaluation history.

Register a new session for an agent. Optional session-level metadata.

Configuration

Retrieve current configuration including thresholds, signals, taxonomy, enforcement mode, and detector registry state.

Update configuration. A partial update: only the fields you send change, and the result is validated before it is saved. Admins only, from a signed-in session. Every change is versioned and audited.

Health & Metrics

Returns version and runtime metadata: service version, runtime / signal / trust-model versions, schema version, and uptime.

Returns service status including version, uptime, database health, connection-pool status, schema version, and authentication configuration.

Kubernetes liveness probe. Returns 200 when the process is alive.

Kubernetes readiness probe. Returns 200 when the service can accept traffic.

Returns a JSON snapshot of current evaluation and signal metrics.

Prometheus-formatted metrics for integration with monitoring stacks.

Dashboard

Aggregated summary statistics for the dashboard UI.

For full request bodies, response shapes, and implementation guidance, use the integration guide.