Resolve the label in force for named events, as of each event's own horizon

Answers, for each named event, which assertion was in force AS OF that event's own horizon — and what disagreed with it.

POST /v1/label/resolve

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


Address	`https://api.hanzo.ai/v1/label/resolve`
Method	`POST`
Operation	`riskResolveLabels`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Answers, for each named event, which assertion was in force AS OF that event's own horizon — and what disagreed with it.

This is the join surface: the dataset materialiser calls it to attach ground truth to training rows, and the evaluator calls it to score a past decision against what was knowable when the decision had to be made. One mechanism for both, so a model can never be trained under one leakage rule and scored under another.

Three answers are distinct and all three are honest: a resolved label, an event that has not matured, and a matured event nobody has judged. The last is never reported as unproductive.

Request

6 fields, body application/json (required).

Field	In	Type	Required	Description
`horizon`	body	integer	—	Horizon is how many days an event must age before it may be resolved at all, and it is the whole of the no-leakage rule.
`now`	body	string	—	Now moves the observation instant BACKWARDS, RFC 3339.
`subjects`	body	riskLabelEvent[]	—	Subjects are the exact events being judged.
`subjects[].at`	body	string	—	At is the event's own instant, RFC 3339. It is part of the event's IDENTITY and not a filter: it is matched exactly, to the second, against the `at` the…
`subjects[].kind`	body	string	—	Kind is the judged entity's type, from the closed set: account, agent, merchant, payout, person, session or transaction.
`subjects[].subject`	body	string	—	Subject is the entity id in the tenant's own namespace, at most 512 bytes.

Response

Status	Body	Meaning
`200`	riskResolveOut	ok

200 body — 30 fields.

Field	In	Type	Always	Description
`horizon`	body	integer	—	Horizon is the maturity horizon this answer was computed under, IN DAYS — the caller's, or 120 when it stated none.
`labels`	body	riskResolved[]	—	Labels is one entry per named event that BOTH matured and had at least one assertion knowable by its own as-of, in the order the events were named.
`labels[].asOf`	body	string	—	AsOf is the instant this answer was true at: the event time plus the horizon.
`labels[].at`	body	string	—	At is the event's instant, RFC 3339, echoed.
`labels[].by`	body	string	—	By is the identity that filed the WINNING assertion, `<home org>/<user>`, stamped server-side from the validated principal at the write and never taken from a…
`labels[].confidence`	body	number	—	Confidence is the winning assertion's own confidence in [0,1], zero when its filer stated none.
`labels[].conflicts`	body	riskLabelRecord[]	—	Conflicts is every other visible assertion, strongest first, whole.
`labels[].conflicts[].at`	body	string	—	At is when the judged EVENT happened, RFC 3339 in UTC, truncated to the second.
`labels[].conflicts[].by`	body	string	—	By is the identity that asserted, stamped server-side at the write.
`labels[].conflicts[].confidence`	body	number	—	Confidence is the filer's own confidence in [0,1] — 1 for a processor chargeback, less for an analyst's hunch.
`labels[].conflicts[].disposition`	body	string	—	Disposition is what was concluded, from the closed set: `productive` — the event led somewhere, escalated, reported or charged back; `unproductive` — judged…
`labels[].conflicts[].evidence`	body	string	—	Evidence is the pointer to the record this conclusion came from: a dispute id, a case id, a decision id.
`labels[].conflicts[].hold`	body	boolean	—	Hold is true while a litigation hold is on this record: retention will not dispose of it, at any age.
`labels[].conflicts[].id`	body	string	—	ID is the assertion's content digest — SHA-256 over every semantic field, rendered hex — computed server-side and never supplied.
`labels[].conflicts[].kind`	body	string	—	Kind is what the subject IS, from the closed set: account, agent, merchant, payout, person, session or transaction.
`labels[].conflicts[].knowable`	body	string	—	Knowable is when THIS PLANE could first have answered with the assertion: the later of Seen and the server clock at the write, derived server-side.
`labels[].conflicts[].seen`	body	string	—	Seen is when the FILER said the assertion became knowable.
`labels[].conflicts[].source`	body	string	—	Source is WHO asserted, from the closed set: chargeoff, dispute, case, refund, review or sample.
`labels[].conflicts[].subject`	body	string	—	Subject is the entity that was judged, named in the TENANT'S OWN namespace and at most 512 bytes.
`labels[].conflicts[].wrote`	body	string	—	Wrote is the server clock at the write.
`labels[].contested`	body	boolean	—	Contested is true when a visible assertion claimed a DIFFERENT disposition.
`labels[].disposition`	body	string	—	Disposition is the claim IN FORCE at AsOf: productive, unproductive, or the empty string for an explicit unjudged.
`labels[].evidence`	body	string	—	Evidence is the winning assertion's pointer to the record behind it — the dispute, case or decision id it was filed with, opaque and verbatim.
`labels[].id`	body	string	—	ID is the winning assertion's content digest, so this answer traces to the exact record it came from — and that record can be placed under litigation hold by…
`labels[].kind`	body	string	—	Kind is the judged entity's type, echoed from the event that was named.
`labels[].source`	body	string	—	Source is who filed the winning assertion, and it is the PRIMARY term of the rule that picked it.
`labels[].subject`	body	string	—	Subject is the entity id, echoed from the event that was named — the tenant's own key, returned verbatim.
`now`	body	string	—	Now and Horizon echo the observation this answer was computed under.
`unlabelled`	body	integer	—	Unlabelled is how many matured events had no assertion knowable by their own as-of.
`unmatured`	body	integer	—	Unmatured is how many named events had not aged past the horizon.

Failure carries the platform error shape — see Errors.

Examples

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

import { Configuration, LabelApi } from 'hanzoai';

const api = new LabelApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.riskResolveLabels({ horizon: 0, now: "<now>" });

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = LabelApi(client).risk_resolve_labels(horizon=0, now="<now>")

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

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

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

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

let result = label_api::risk_resolve_labels(&cfg, Default::default()).await?;

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

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

var result = new LabelApi(client).riskResolveLabels();

curl -X POST https://api.hanzo.ai/v1/label/resolve \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "horizon": 0,
       "now": "<now>"
     }'

Tool label, op riskResolveLabels — 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": "label",
         "arguments": {
           "op": "riskResolveLabels",
           "input": {
             "horizon": 0,
             "now": "<now>"
           }
         }
       }
     }'

Label API · All Hanzo APIs · Interactive reference

Resolve the label in force for named events, as of each event's own horizon

Request

Response

Examples

On this page