API Reference
The API is intentionally narrow: authenticate, evaluate, report outcome, inspect history, and trace sessions. For full request and response shapes, see the integration guide.
Authentication
Kerneva also supports WorkOS SSO for team-based access control on hosted deployments.
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, update config with detector registry and suppression state, and return quality gates.
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 the outcome after execution or review. Status, resolution, and optional impact metadata.
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.
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. 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.