Score one event against your organisation's own model

Score judges one event against the caller organisation's OWN model and learns nothing from it.

POST /v1/risk/score

Risk → · All API references → · Six flows, four surfaces →


Address	`https://api.hanzo.ai/v1/risk/score`
Method	`POST`
Operation	`riskScore`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Score judges one event against the caller organisation's OWN model and learns nothing from it. It is how a candidate is tried against real behaviour before anything depends on the answer, and it is the model's analogue of testing a rule.

Because it records nothing, the aggregates it reads do not include the event: the numbers are the organisation's history as it stands. A model still warming declines with a reason rather than answering zero, because silence must never read as a clean result.

Request

8 fields, body application/json (required).

Field	In	Type	Required	Description
`event`	body	riskEvent	—
`event.at`	body	string	—	At is when it happened, RFC 3339. Empty means now.
`event.device`	body	string	—	Device is the device fingerprint, if any.
`event.id`	body	string	—	ID is the caller's own stable identifier for the event.
`event.kind`	body	string	—	Kind is whose behaviour this is: person, session or account.
`event.nano`	body	integer	—	Nano is the value moved, in nano-USD. Omit it for an event that moves no money: the value features then read BLIND rather than being told the amount was zero,…
`event.peer`	body	string	—	Peer is the counterparty, if any.
`event.subject`	body	string	—	Subject is the identifier on that kind.

Response

Status	Body	Meaning
`200`	riskScoreOut	ok

200 body — 26 fields.

Field	In	Type	Always	Description
`alert`	body	boolean	—	Alert is whether this would become evidence.
`causes`	body	riskCause[]	—	Causes is the per-feature attribution, ordered by contribution.
`causes[].baseline`	body	number	—	Baseline is the number it was measured against — always this organisation's own history, never a fixed limit and never another organisation's.
`causes[].citation`	body	string	—	Citation is where those words come from, so the claim is checkable rather than asserted — which is what a chargeback network or a regulator asks for.
`causes[].feature`	body	string	—	Feature is the dimension that contributed.
`causes[].indicator`	body	string	—	Indicator is the supervisor's own words for the thing being looked for.
`causes[].observed`	body	number	—	Observed is the raw number the coordinate was computed from.
`causes[].severity`	body	string	—	Severity is how much weight this dimension carries.
`causes[].share`	body	number	—	Share is this feature's part of the score, in [0,1].
`causes[].typology`	body	string	—	Typology is the laundering or abuse pattern this dimension detects.
`causes[].unit`	body	string	—	Unit is how to read Observed, which is what turns a coordinate into a sentence.
`causes[].without`	body	number	—	Without is the score the same event would have received with this coordinate at its neutral value — the counterfactual itself.
`cut`	body	number	—	Cut is the threshold in force, derived from the stated appetite as a quantile of the scores actually observed rather than fixed at a number.
`policy`	body	integer	—	Policy is the version of your organisation's decision regime this verdict was reached under, from its own policy history (GET /v1/risk/policy).
`refusal`	body	string	—	Refusal names why the model declined, when it did.
`score`	body	number	—	Score is where the event sits in the tenant's own density: 0 where its recent behaviour is densest, 1 where there is none of it.
`scored`	body	boolean	—	Scored is false when the model declined, and Refusal says which refusal it was: warming, unusable or unidentified.
`shadow`	body	boolean	—	Shadow is whether the model is testing rather than deciding — scoring, learning and recording what it WOULD have alerted on, and changing no outcome.
`shape`	body	string	—	Shape is the model space this verdict was reached in, as `<family>:<digest>`: the KIND of model, and that family's own digest over your organisation's feature…
`values`	body	riskValue[]	—	Values is every coordinate, including the ones that contributed nothing, so a reviewer sees what the model read and not only what it concluded.
`values[].baseline`	body	number	—	Baseline is what Observed was measured against: this organisation's own history for this subject.
`values[].blind`	body	boolean	—	Blind marks a coordinate that could not be computed and took its neutral value.
`values[].feature`	body	string	—	Feature is the dimension.
`values[].observed`	body	number	—	Observed is the raw number X was computed from, quoted so the coordinate reads back as a sentence rather than a bare ratio.
`values[].unit`	body	string	—	Unit is how to read Observed.
`values[].x`	body	number	—	X is the coordinate in the model space, always dimensionless.

Failure carries the platform error shape — see Errors.

Examples

hanzo risk score

import { Configuration, RiskApi } from 'hanzoai';

const api = new RiskApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.riskScore({ event: {"at":"<at>","device":"<device>","id":"<id>","kind":"<kind>"} });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import RiskApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = RiskApi(client).risk_score(event={"at":"<at>","device":"<device>","id":"<id>","kind":"<kind>"})

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.RiskAPI.RiskScore(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, risk_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = risk_api::risk_score(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.RiskApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new RiskApi(client).riskScore();

curl -X POST https://api.hanzo.ai/v1/risk/score \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "event": {
         "at": "<at>",
         "device": "<device>",
         "id": "<id>",
         "kind": "<kind>"
       }
     }'

Tool risk, op riskScore — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "risk",
         "arguments": {
           "op": "riskScore",
           "input": {
             "event": {
               "at": "<at>",
               "device": "<device>",
               "id": "<id>",
               "kind": "<kind>"
             }
           }
         }
       }
     }'

Risk API · All Hanzo APIs · Interactive reference

Score one event against your organisation's own model

Request

Response

Examples

On this page