Resolve reference

Looks keys up against the reference plane.

POST /v1/reference/resolve

Reference → · All API references → · Get started →

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

Looks keys up against the reference plane.

Your organisation's own overrides are consulted FIRST and win outright; the shared baseline answers everything they do not cover. Every answer names the version that produced it, when that version was current and whether it is stale, so a decision can record exactly what it consulted.

Read Refusal before reading Hit. A set that has never loaded, one held by the component that screens against it, and one whose source needs a licence we do not hold all answer with a refusal — and a miss on a refusing set means nothing is known, not that the key is clean.

Request

2 fields, body application/json (required).

Field	In	Type	Required	Description
`keys`	body	string[]	—	Keys are the values to look up, at most 100 per call: email addresses or domains, IP addresses, card prefixes, user-agent strings, autonomous system numbers, device digests.
`sets`	body	string[]	—	Sets narrows which sets to consult.

Response

Status	Body	Meaning
`200`	reference.ResolveReferenceOut	ok
`default`	problem-details	refused

200 body — 23 fields.

Field	In	Type	Always	Description
`answers`	body	reference.ReferenceAnswer[]	—	Answers is one entry per (set, key) consulted.
`answers[].age`	body	string	—	Age is how old that is, as a duration.
`answers[].asOf`	body	string	—	AsOf is when the oldest contributing publisher was current, RFC 3339.
`answers[].from`	body	string	—	From is override or baseline — which plane answered.
`answers[].hit`	body	boolean	—	Hit is whether the key is a member.
`answers[].key`	body	string	—	Key is the key as asked.
`answers[].matched`	body	string	—	Matched is the member that covered the key, which for a domain or a network is the enclosing entry rather than the key itself.
`answers[].refusal`	body	string	—	Refusal is why the set could not be consulted, when it could not: never loaded, held elsewhere, or a source we hold no licence for.
`answers[].score`	body	number (double)	—	Score is the published risk weight where the source expresses one.
`answers[].set`	body	string	—	Set is the set consulted.
`answers[].stale`	body	boolean	—	Stale is whether the set is past its freshness bound.
`answers[].value`	body	object	—	Value is what the publisher says about the member — class, operator, scheme, region.
`answers[].value.*`	body	string	—
`answers[].verdict`	body	string	—	Verdict is the tenant's own allow or deny, present only for an override.
`answers[].version`	body	string	—	Version is the exact baseline version consulted, composed of each contributing publisher and its content digest.
`consulted`	body	reference.ReferenceVersion[]	—	Consulted names the version of every set that took part, so a decision can record precisely what it leaned on.
`consulted[].asOf`	body	string	—	AsOf is when the oldest of them was current, RFC 3339.
`consulted[].refusal`	body	string	—	Refusal is why it could not be consulted, when it could not.
`consulted[].set`	body	string	—	Set is the name the consulted set is addressed by.
`consulted[].stale`	body	boolean	—	Stale is whether it is past its freshness bound.
`consulted[].version`	body	string	—	Version is every contributing publisher and its content digest.
`refused`	body	string[]	—	Refused names the consulted sets that could not answer at all.
`stale`	body	string[]	—	Stale names the consulted sets past their freshness bound.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo reference resolve

.ts

.py

.go

.rs

.java

import { Configuration, ReferenceApi } from 'hanzoai';

const api = new ReferenceApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.riskResolveReference({ keys: ["<keys>"], sets: ["<sets>"] });

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ReferenceApi(client).risk_resolve_reference(keys=["<keys>"], sets=["<sets>"])

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

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

use hanzo_client::apis::{configuration::Configuration, reference_api};

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

let result = reference_api::risk_resolve_reference(&cfg, Default::default()).await?;

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

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new ReferenceApi(client).riskResolveReference();

curl -X POST https://api.hanzo.ai/v1/reference/resolve \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "keys": [
         "<keys>"
       ],
       "sets": [
         "<sets>"
       ]
     }'

Tool reference, op riskResolveReference — 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": "reference",
         "arguments": {
           "op": "riskResolveReference",
           "input": {
             "keys": [
               "<keys>"
             ],
             "sets": [
               "<sets>"
             ]
           }
         }
       }
     }'

Reference API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList reference NextReplace reference