# Create score URL: https://docs.hanzo.ai/docs/openapi/risk/riskscore > Judges one event against the caller organisation's OWN model and learns nothing from it. `POST /v1/risk/score` > [Risk →](https://docs.hanzo.ai/docs/openapi/risk) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | -------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/risk/score` | | **Method** | `POST` | | **Operation** | `riskScore` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | 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 | risk.riskEvent | — | | | `event.at` | body | string | — | At is when it happened, RFC 3339. | | `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 (int64) | — | Nano is the value moved, in nano-USD. | | `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` | risk.riskScoreOut | ok | | `default` | problem-details | refused | `200` body — 26 fields. | Field | In | Type | Always | Description | | -------------------- | ---- | ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `alert` | body | boolean | — | Alert is whether this would become evidence. | | `causes` | body | risk.riskCause\[] | — | Causes is the per-feature attribution, ordered by contribution. | | `causes[].baseline` | body | number (double) | — | 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 (double) | — | 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 (double) | — | 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 (double) | — | Without is the score the same event would have received with this coordinate at its neutral value — the counterfactual itself. | | `cut` | body | number (double) | — | 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 (int64) | — | 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 (double) | — | 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 inventory in order and the detector's geometry parameters. | | `values` | body | risk.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 (double) | — | 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 (double) | — | 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 (double) | — | X is the coordinate in the model space, always dimensionless. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo risk score ``` **SDK** **.ts** ```ts import { Configuration, RiskApi } from 'hanzoai'; const api = new RiskApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.riskScore({ event: {"at":"","device":"","id":"","kind":""} }); ``` **.py** ```python 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":"","device":"","id":"","kind":""}) ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.RiskAPI.RiskScore(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::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?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.RiskApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new RiskApi(client).riskScore(); ``` **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/risk/score \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "event": { "at": "", "device": "", "id": "", "kind": "" } }' ``` **MCP** Tool `risk`, op `riskScore` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`. ```bash 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": "", "device": "", "id": "", "kind": "" } } } } }' ``` --- [Risk API](https://docs.hanzo.ai/docs/openapi/risk) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)