Score an event and return a verdict

The one endpoint on the request path. Normalizes the event, scores it against the active policy, and returns allow / challenge / review / deny. Rate-limited per API key (429 with Retry-After after RATE_LIMIT_DECISIONS_PER_MIN, default 600/min); every response carries X-RateLimit-Limit and X-RateLimit-Remaining.

{
  "type": "card.authorize",
  "amount": 3500, "currency": "USD",
  "subject": { "userId": "usr_3f9a", "deviceId": "dev_2b1", "fingerprint": "fp_9c1e77a2b4", "ip": "203.0.113.7", "channel": "visa" },
  "instrument": { "kind": "card", "bin": "411111", "issuerCountry": "US", "threeDS": false }
}

{
  "id": "vd_0mu4…", "eventId": "evt_0mu4…",
  "verdict": "review", "score": 55,
  "reasons": [{ "tag": "takeover", "points": 33 }, { "tag": "no_3ds", "points": 22 }],
  "policyId": "pol_card_authorize", "policyVersion": "v0.4.0",
  "decidedAt": "2026-09-17T10:22:00.000Z"
}

verdict is one of allow · challenge · review · deny. A review verdict opens a case. Send an Idempotency-Key to make retries safe.

Score up to 100 events in one call

Submit an array of events under `events`; each is scored independently and the response preserves order. A malformed event fails only its own entry (ok:false) — the rest still return verdicts. Idempotency is keyed per event by its id.

{ "events": [
  { "type": "card.authorize", "amount": 20, "currency": "USD", "subject": { "userId": "u1" } },
  { "type": "account.login", "subject": { "userId": "u2", "fingerprint": "fp_x" } }
] }

{ "results": [
  { "ok": true, "decision": { "id": "vd_…", "verdict": "allow", "score": 4, "reasons": [] } },
  { "ok": false, "error": { "code": "INGEST_UNKNOWN_TYPE", "message": "unknown event type: …" } }
] }

Counts as one rate-limited request. Cap 100 events per call.

Accept an event and score it off the response path

Returns 202 immediately with the event id; the verdict is computed in the background, written durably, and fanned out on the bus (subscribe a webhook to verdict.reached.v1). Poll GET /v1/decisions/{id} for the result. Idempotency is keyed by the event id.

{ "id": "evt_9f2a", "type": "card.authorize", "amount": 30, "currency": "USD", "subject": { "userId": "u1" } }

{ "accepted": true, "id": "evt_9f2a", "correlationId": "cor_…" }

202 Accepted. The verdict is not in this response — poll GET /v1/decisions/{id}.

Fetch a decision by event id

Returns the verdict for an event id (e.g. one submitted via /async). O(1) lookup. 404 while it is still pending or if the id is unknown.

{ "id": "vd_…", "eventId": "evt_9f2a", "verdict": "allow", "score": 4, "reasons": [], "decidedAt": "2026-01-01T00:00:00.000Z" }

404 with code NOT_FOUND while the async decision is still pending.

Whether an admin exists yet

{ "needsBootstrap": true }

needsBootstrap is true until the first (admin) account is created.

Bootstrap the admin account

Creates the first user as admin. Once any user exists this returns 403 REGISTRATION_CLOSED — further operators are added by an admin.

{ "email": "admin@bank.com", "password": "••••••••" }

{ "token": "eyJ…", "user": { "email": "admin@bank.com", "role": "admin" } }

Exchange credentials for a token

Returns a bearer token valid for 12 hours. Rate-limited per IP (429 with Retry-After after RATE_LIMIT_LOGIN_PER_MIN attempts, default 10/min).

{ "email": "maya@bank.com", "password": "••••••••" }

{ "token": "eyJ…", "user": { "email": "maya@bank.com", "role": "analyst" } }

Send the token as `Authorization: Bearer <token>` on operator endpoints.

List operators

[{ "email": "maya@bank.com", "role": "analyst", "createdAt": "…" }]

Add an operator

{ "email": "ana@bank.com", "password": "••••••••", "role": "analyst" }

{ "email": "ana@bank.com", "role": "analyst", "createdAt": "…" }

Log out (revoke this token)

Revokes the presented bearer token immediately, before it would expire.

{ "ok": true }

Log out everywhere

Revokes every active session for the current user — use after a suspected compromise.

{ "ok": true }

Refresh the token

Exchanges a still-valid token for a fresh one (sliding session). The old token stays valid until it expires.

{ "token": "eyJ…", "user": { "email": "maya@bank.com", "role": "analyst" } }

List the review queue

[{ "id": "cse_…", "eventId": "evt_…", "verdictId": "vd_…", "queue": "risk-ops",
   "verdict": "review", "score": 55, "status": "open",
   "openedAt": "2026-09-17T10:22:00.000Z", "audit": [ … ] }]

Same object shape is returned by GET /v1/cases/:id.

Fetch one case with its audit trail

{ "id": "cse_…", "status": "assigned", "assignedTo": "maya@bank.com", "audit": [ … ] }

404 when the case does not exist.

Assign a case to yourself

{ "id": "cse_…", "status": "assigned", "assignedTo": "maya@bank.com" }

The analyst is taken from your token, not the body.

Resolve a case and emit a label

{ "outcome": "fraud", "note": "confirmed ATO" }

{ "id": "cse_…", "status": "resolved", "resolution": { "outcome": "fraud", … } }

409 if already resolved. Resolving feeds a training label into Feedback.

The active rulesets, rendered as DSL

[{ "eventType": "card.authorize", "version": "seed@v0.4",
   "rules": [{ "id": "r_velocity", "tag": "velocity", "weight": 28, "dsl": "rule r_velocity { … }" }] }]

The active policies and their bands

[{ "eventType": "card.authorize",
   "policy": { "id": "pol_card_authorize", "version": "v0.4.0", "onError": "fail_open",
     "bands": [{ "verdict": "allow", "min": 0, "max": 24 }, … ] } }]

Publish a new policy version

Validated: bands must cover 0–100 with no gaps or overlaps. The new version becomes active immediately; the previous one is retained for rollback.

{ "id": "pol_card_authorize", "version": "v0.4.1", "onError": "fail_closed",
  "bands": [ { "verdict": "allow", "min": 0, "max": 20 }, … ] }

{ "ok": true, "version": "v0.4.1" }

Roll a policy back to an earlier version

{ "toVersion": "v0.4.0" }

{ "ok": true }

A policy's version history

["v0.4.0", "v0.4.1"]

See which verdict a score would get

{ "score": 61 }

{ "verdict": "review", "reviewQueue": "risk-ops" }

Test config changes without sending a real event.

Recent entries from the append-only verdict log

[{ "id": "vd_…", "verdict": "deny", "score": 82, "decidedAt": "…" }]

Replay a candidate rule/policy change over labeled history

Re-runs a candidate policy (and optionally a candidate ruleset) against the stored event + feature snapshots for events that have a fraud/legit label, and reports how it would have performed versus the live policy. Read-only — nothing is published.

{
  "eventType": "card.authorize",
  "policy": { "bands": [
    { "verdict": "allow", "min": 0, "max": 34 },
    { "verdict": "review", "min": 35, "max": 69, "reviewQueue": "risk-ops" },
    { "verdict": "deny", "min": 70, "max": 100 }
  ] }
}

{
  "eventType": "card.authorize",
  "sampleSize": 1240, "labeled": 312,
  "candidate": { "truePositives": 190, "falsePositives": 40, "falseNegatives": 22, "trueNegatives": 60, "precision": 0.83, "recall": 0.9, "falsePositiveRate": 0.19 },
  "baseline": { "truePositives": 170, "falsePositives": 55, "falseNegatives": 42, "trueNegatives": 45 },
  "delta": { "fraudCaught": 20, "falsePositives": -15, "flips": 48 }
}

Powers the dashboard's test-before-you-publish panel. 400 if the candidate policy has gaps.

List service keys

[{ "id": "key_…", "name": "payment-gateway", "prefix": "vk_live_a1b2c3",
   "createdBy": "admin@bank.com", "createdAt": "…", "revoked": false }]

Only the prefix is stored for display — the full key is never retrievable.

Create a service key

Optionally scope the key to specific actions and set an expiry. A key with no scopes grants both.

{ "name": "payment-gateway", "scopes": ["decisions"], "expiresInDays": 90 }

{ "plaintext": "vk_live_a1b2c3…",   // shown ONCE — store it now
  "key": { "id": "key_…", "name": "payment-gateway", "prefix": "vk_live_a1b2c3",
    "scopes": ["decisions"], "expiresAt": "2026-12-16T…", "expired": false,
    "createdBy": "admin@bank.com", "createdAt": "2026-09-17T10:00:00.000Z", "revoked": false } }

Send the plaintext as X-API-Key. A request to an endpoint outside the key's scope is rejected with 403. Only the SHA-256 hash is stored.

Revoke a key immediately

{ "ok": true }

Rollups from the verdict log and resolved cases

A read-model maintained by a projector that consumes verdict + case events — never queried off the write path.

{
  "totals": { "decisions": 1240, "byVerdict": { "allow": 900, "review": 210, "deny": 130 } },
  "scoreBuckets": [ … 11 buckets 0–100 … ],
  "topTags": { "velocity": 320, "takeover": 180 },
  "byDay": { "2026-09-17": { "total": 210, "review": 40, "deny": 22 } },
  "cases": { "resolved": 90, "fraud": 61, "legit": 29 },
  "labels": { "fraud": 74, "legit": 29, "analyst": 90, "chargeback": 13 },
  "falsePositiveRate": 0.32
}

The adaptive model's learned signal weights

Per-tag weights the adaptive scorer learns from labels — how often each signal rode a fraud outcome. Projected even when the weighted scorer is live, so you can see what the learned model would do before switching SCORER=learned.

{
  "active": "weighted",
  "weights": [
    { "tag": "takeover", "fraud": 41, "legit": 3, "weight": 42, "trusted": true },
    { "tag": "velocity", "fraud": 22, "legit": 9, "weight": 32, "trusted": true }
  ]
}

An entity's linked users, devices, IPs and phones, and its cluster size

The entity graph links the identifiers events carry (kind is user, device, ip or phone). ringSize is the connected cluster the entity sits in — the ring signal rules read as graph.ringSize; a shared phone drives graph.usersOnPhone (SIM-box / mobile-money farming). Cards are not nodes: only the issuer BIN is held, which would over-link.

{
  "kind": "device", "id": "dev_ring",
  "users": ["usr_1", "usr_2", "usr_3"],
  "devices": [], "ips": ["203.0.113.7"],
  "ringSize": 8
}

404-safe: an unknown entity returns empty links and ringSize 1.

List webhook endpoints and their delivery status

{
  "events": ["verdict.reached.v1", "case.resolved.v1", "label.recorded.v1"],
  "endpoints": [{ "id": "whk_…", "url": "https://app/hooks", "events": ["verdict.reached.v1"],
    "active": true, "lastStatus": "delivered", "failures": 0 }]
}

Register an endpoint to receive signed events

Each delivery is a POST with headers X-Verdict-Event, X-Verdict-Delivery and X-Verdict-Signature (`sha256=<hmac>` of the raw body with the endpoint secret). Verify the signature before trusting the payload. Deliveries are durable: each is retried with exponential backoff and dead-lettered after 8 failed attempts (inspect and re-drive via the delivery-log endpoints).

{ "url": "https://app/hooks/verdict", "events": ["verdict.reached.v1"] }

{ "id": "whk_…", "url": "https://app/hooks/verdict", "events": ["verdict.reached.v1"],
  "active": true, "failures": 0, "secret": "whsec_…" }

Delivered payload shape: { id, type, occurredAt, correlationId, data }, where data is the event payload.

Deactivate an endpoint

{ "ok": true }

Delivery log (pending & dead-lettered)

Deliveries awaiting a retry, and ones that exhausted their attempts (dead-lettered).

{ "pending": [{ "id": "whd_…", "endpointId": "whk_…", "event": "verdict.reached.v1",
    "status": "pending", "attempts": 2, "nextAttemptAt": "…", "lastError": "fetch failed" }],
  "dead": [] }

Re-drive dead-lettered deliveries

Moves every dead-lettered delivery back to pending for another attempt.

{ "requeued": 3 }

List alert channels and subscribable events

{ "events": ["verdict.reached.v1", "case.resolved.v1", "label.recorded.v1", "alert.dead_letter.v1"],
  "channels": [{ "id": "ntf_…", "type": "slack", "urlHint": "https://hooks.slack.com/…",
    "events": ["verdict.reached.v1"], "minVerdict": "deny", "active": true, "failures": 0 }] }

Add a Slack, Telegram or webhook alert channel

Slack incoming-webhooks, Telegram bots, and generic HTTPS endpoints. For Telegram, set url to https://api.telegram.org/bot<token>/sendMessage and target to the chat id. For verdict.reached, set minVerdict to only alert at or above a severity (allow < challenge < review < deny). Set throttlePerMin to cap alerts per channel per minute (excess is dropped). Delivery is durable — queued, retried with backoff, and dead-lettered — and runs off the decision path.

{ "type": "telegram", "url": "https://api.telegram.org/bot<token>/sendMessage", "target": "-1001234567890", "events": ["verdict.reached.v1"], "minVerdict": "deny", "throttlePerMin": 30 }

{ "id": "ntf_…", "type": "slack", "urlHint": "https://hooks.slack.com/…", "events": ["verdict.reached.v1"], "minVerdict": "deny", "throttlePerMin": 30, "active": true, "failures": 0 }

Send a test alert to a channel

{ "ok": true }

Deactivate a channel

{ "ok": true }

List alert deliveries (pending + dead-lettered)

Durable alert deliveries awaiting a retry, and those that exhausted their retries. Bodies are omitted.

{ "pending": [{ "id": "ntd_…", "channelId": "ntf_…", "event": "alert.anomaly.v1", "status": "pending", "attempts": 2, "nextAttemptAt": "2026-01-01T00:00:04.000Z", "createdAt": "2026-01-01T00:00:00.000Z" }],
  "dead": [] }

Re-drive dead-lettered alerts

Moves every dead-lettered alert delivery back to the queue for another attempt.

{ "requeued": 3 }

Get rate-limit settings

The effective per-minute budgets and whether each is a dashboard override or the env default.

{ "windowMs": 60000, "decisionsPerMin": 600, "loginPerMin": 10,
  "overridden": { "decisionsPerMin": false, "loginPerMin": false } }

Update rate-limit settings

Override the per-minute budgets at runtime — no redeploy. Send a field as null to revert it to the env default; changes apply within ~10s across replicas.

{ "decisionsPerMin": 1200, "loginPerMin": 10 }

{ "windowMs": 60000, "decisionsPerMin": 1200, "loginPerMin": 10,
  "overridden": { "decisionsPerMin": true, "loginPerMin": false } }

Get alert settings

The anomaly z-score threshold at or above which a decision emits alert.anomaly.v1.

{ "anomalyZScore": 3, "overridden": { "anomalyZScore": false } }

Update alert settings

Set the anomaly z-score threshold (send null to revert to the default of 3). Applies within ~10s.

{ "anomalyZScore": 2.5 }

{ "anomalyZScore": 2.5, "overridden": { "anomalyZScore": true } }

Get retention settings

The retention window (in days) for each append-only collection, and whether each is a dashboard override or the env default. 0 means keep forever.

{ "sweepMinutes": 60,
  "days": { "verdicts": 365, "activity": 90, "replay": 90, "idempotency": 7, "deadLetter": 30 },
  "overridden": { "verdicts": false, "activity": false, "replay": false, "idempotency": false, "deadLetter": false } }

Update retention settings

Set the retention window (days) per collection. 0 keeps that collection forever; send a field as null to revert it to the env default. Applies on the next sweep.

{ "activity": 120, "idempotency": 3 }

{ "sweepMinutes": 60,
  "days": { "verdicts": 365, "activity": 120, "replay": 90, "idempotency": 3, "deadLetter": 30 },
  "overridden": { "verdicts": false, "activity": true, "replay": false, "idempotency": true, "deadLetter": false } }

Run the retention prune now

Trigger a retention sweep immediately (the job also runs on a timer) and return how many records were pruned per collection.

{ "ranAt": "2026-01-01T00:00:00.000Z",
  "pruned": { "verdicts": 0, "activity": 4, "replay": 4, "idempotency": 120, "deadLetter": 0 } }

Scoring model status

The active scorer (weighted / learned / ml) and, for the trained ML model, its provenance and per-feature weights. The model's weights can be bundled in the image, or loaded — and refreshed — from a local file (MODEL_PATH), an HTTPS URL (MODEL_URL), or S3-compatible object storage (MODEL_S3_*), so you retrain and roll out without a redeploy.

{ "scorer": "ml",
  "ml": { "active": true, "source": "s3", "provenance": "operator-supplied", "trainedAt": "2026-09-23",
    "metrics": { "auc": 0.843, "accuracy": 0.873, "samples": 20000 }, "bias": -3.857,
    "features": [ { "name": "device.fingerprintDeviceMismatch", "weight": 1.332 },
      { "name": "geo.impossibleTravel", "weight": 1.237 } ] } }

provenance is 'synthetic-demo' while the bundled demonstration weights (trained on synthetic data — not a fraud model) are serving, and 'operator-supplied' once a model is loaded from MODEL_PATH / MODEL_URL / MODEL_S3_*.

Get storage & disk health

The document store's size and per-collection row counts, the health of the filesystems that data lives on (total / free / used — for monitoring Docker volumes), and a per-service breakdown of the space consumed on disk. All are sampled into /metrics each sweep (verdict_storage_*, verdict_disk_total_bytes, verdict_disk_free_bytes, verdict_disk_used_ratio, verdict_disk_component_bytes). Set DISK_HEALTH_PATHS to the volume mounts you want watched; the engine can only see filesystems mounted into its own container.

{ "totalBytes": 48210944,
  "collections": [ { "name": "replay-samples", "rows": 91200 }, { "name": "verdicts", "rows": 91200 },
    { "name": "activity", "rows": 91200 }, { "name": "audit-log", "rows": 312 } ],
  "disks": [ { "path": "/var/lib/postgresql/data", "totalBytes": 53687091200, "freeBytes": 48800000000,
    "usedBytes": 4887091200, "usedPercent": 9 } ],
  "components": [ { "name": "Document store", "kind": "database", "bytes": 48210944 },
    { "name": "ML model file", "kind": "model", "bytes": 2048, "path": "/models/verdict-weights.json" } ] }

List the config-change audit trail

Newest-first, paginated record of every operator mutation — who changed what, when, and the result. Secret-ish request fields (URLs, tokens, passwords) are redacted before storage. Read-only.

{ "total": 42, "entries": [
  { "id": "aud_…", "at": "2026-01-01T00:00:00.000Z", "actor": "admin@bank.com", "role": "admin",
    "action": "PUT /v1/config/rate-limits", "status": 200, "params": { "decisionsPerMin": 1200 } }
] }

Record a chargeback as a fraud label

A PSP/system endpoint — takes a service API key.

{ "eventId": "evt_…" }

{ "recorded": true }

202 Accepted. If the event was seen before, its fired tags are credited to the model.

Erase a user's personal data (right to erasure)

Removes a user's graph identity, learned spending baseline, and stored replay samples (which hold whole events). The append-only verdict log is out of scope by design — it holds only an event id, verdict and tags — and is governed by a retention window.

{ "userId": "usr_3f9a" }

{ "userId": "usr_3f9a", "replaySamplesRemoved": 12, "activityEntriesRemoved": 12,
  "graph": true, "baseline": true }

Liveness probe

The process is up. Use it for the liveness probe only; use /readyz for readiness.

{ "status": "ok", "name": "verdict-engine", "version": "0.7.0" }

Readiness probe

Verifies the datastore is reachable (the query also confirms the schema/migrations are in place) and, when Redis is configured, that Redis answers. Returns 200 when the instance can serve durable decisions, or 503 until then. Point your orchestrator's readiness probe here.

{ "status": "ready", "version": "0.7.0",
  "checks": { "store": "ok", "redis": "skipped" } }

503 with { status: 'not_ready', checks } while a dependency is down. redis is 'skipped' when REDIS_URL is unset.

Prometheus metrics

Operational metrics in Prometheus text format — decision latency & outcomes, 429s, degraded decisions, storage/disk, and outbox/webhook/notification delivery counters and queue depth. Public by default (keep it on a private port); set METRICS_TOKEN to require an Authorization: Bearer token.

# HELP verdict_decisions_total Decisions returned, by verdict
# TYPE verdict_decisions_total counter
verdict_decisions_total{verdict="allow",cached="false"} 128