Get reference

Describes one set and lists your org's overrides in it.

GET /v1/reference/{set}

Reference → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/reference/{set}`
Method	`GET`
Operation	`riskReference`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Describes one set and lists your org's overrides in it.

The set half is public data about a published list — its version, its publishers, their licences and how current each one is. The overrides half is yours alone: it is read from your organisation's own store, and no other organisation's entries can appear in it.

Request

3 fields.

Field	In	Type	Required	Description
`set`	path	string	yes
`after`	query	string	—	After pages the override listing: the last key of the previous page.
`limit`	query	integer	—	Limit caps the override listing: default 200, maximum 1000.

Response

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

200 body — 29 fields.

Field	In	Type	Always	Description
`next`	body	string	—	Next is the key to page from, empty when this is the last page.
`overrides`	body	reference.ReferenceOverride[]	—	Overrides is YOUR org's entries over that baseline, in key order.
`overrides[].at`	body	string	—	At is when it was written, RFC 3339.
`overrides[].by`	body	string	—	By is who wrote it.
`overrides[].key`	body	string	—	Key is the member this organisation is speaking about.
`overrides[].note`	body	string	—	Note is why, in the operator's own words.
`overrides[].verdict`	body	string	—	Verdict is allow or deny.
`set`	body	reference.ReferenceSet	—
`set.age`	body	string	—	Age is how long ago that was.
`set.asOf`	body	string	—	AsOf is when the OLDEST contributing publisher was current, RFC 3339.
`set.keys`	body	integer (int64)	—	Keys is how many members the baseline carries.
`set.kind`	body	string	—	Kind is how the baseline comes to exist: fetch (downloaded from a publisher), local (computed here), attest (held by the component that screens against it, freshness reported), or gap (declared and NOT held, because the source needs a licence we do not have).
`set.match`	body	string	—	Match is how a key is tested: exact, domain, net, digits, pattern or range.
`set.maxAge`	body	string	—	MaxAge is how old this set may be before it is stale.
`set.overrides`	body	integer (int64)	—	Overrides is how many entries YOUR org has laid over this baseline.
`set.refusal`	body	string	—	Refusal names why the set cannot be relied on, when it cannot: never loaded, held elsewhere, or a licence we do not hold.
`set.set`	body	string	—	Set is the name this set is addressed by.
`set.sources`	body	reference.ReferenceSource[]	—	Sources is each contributing publisher, its licence and its own freshness.
`set.sources[].asOf`	body	string	—	AsOf is when this publisher was current, RFC 3339.
`set.sources[].basis`	body	string	—	Basis is the KIND of permission this publisher's data reaches you under: licence (an explicit grant), registry (the registry of record publishing for anyone to consult), operator (an operator's own machine-readable statement about its own network, published for third parties to filter by — not a licence, and not claimed as one), own (computed here), or none (nothing reaches you: the membership is held by the component that screens against it).
`set.sources[].keys`	body	integer (int64)	—	Keys is how many members this publisher contributed.
`set.sources[].origin`	body	string	—	Origin is exactly where it was taken from, so it can be taken again.
`set.sources[].refusal`	body	string	—	Refusal is why this publisher's last take failed, if it did.
`set.sources[].source`	body	string	—	Source is the publisher.
`set.sources[].terms`	body	string	—	Terms is the CITATION that basis points at — the licence identifier, the registry, or the operator publication.
`set.sources[].version`	body	string	—	Version is the content digest of what this publisher last supplied.
`set.stale`	body	boolean	—	Stale is whether it is past that bound.
`set.version`	body	string	—	Version is the exact baseline consulted — every contributing publisher and its content digest.
`set.what`	body	string	—	What the set holds, in one sentence.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo reference get <set>

.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.riskReference({ set: 'set' });

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_reference(set='set')

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

resp, _, err := client.ReferenceAPI.RiskReference(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_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).riskReference();

curl https://api.hanzo.ai/v1/reference/<set> \
  -H "Authorization: Bearer $HANZO_API_KEY"

Tool reference, op riskReference — 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": "riskReference",
           "input": {
             "set": "<set>"
           }
         }
       }
     }'

Reference API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousDelete reference NextList reference