Lists every set this plane publishes, with its version and how fresh it is.
Lists every set this plane publishes, with its version and how fresh it is.
GET /v1/reference
| Address | https://api.hanzo.ai/v1/reference |
| Method | GET |
| Operation | riskReferenceSets |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Lists every set this plane publishes, with its version and how fresh it is.
Read the Stale and Refused lists first: they are the two ways this plane can be quietly wrong, and they are reported rather than inferred. A set in Refused answers nothing — it has never loaded, it is held by another component, or it names a source we hold no licence for.
Request
GET /v1/reference takes no parameters and no body — the credential is the whole request.
Response
| Status | Body | Meaning |
|---|---|---|
200 | ReferenceSetsOut | ok |
200 body — 24 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
refused | body | string[] | — | Refused names the sets that cannot be consulted at all. |
sets | body | ReferenceSet[] | — | Sets is the whole catalog, in a stable order. |
sets[].age | body | string | — | Age is how long ago that was. |
sets[].asOf | body | string | — | AsOf is when the OLDEST contributing publisher was current, RFC 3339. |
sets[].keys | body | integer | — | Keys is how many members the baseline carries. |
sets[].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,… |
sets[].match | body | string | — | Match is how a key is tested: exact, domain, net, digits, pattern or range. |
sets[].maxAge | body | string | — | MaxAge is how old this set may be before it is stale. |
sets[].overrides | body | integer | — | Overrides is how many entries YOUR org has laid over this baseline. |
sets[].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. |
sets[].set | body | string | — | Set is the name this set is addressed by. |
sets[].sources | body | ReferenceSource[] | — | Sources is each contributing publisher, its licence and its own freshness. |
sets[].sources[].asOf | body | string | — | AsOf is when this publisher was current, RFC 3339. |
sets[].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… |
sets[].sources[].keys | body | integer | — | Keys is how many members this publisher contributed. |
sets[].sources[].origin | body | string | — | Origin is exactly where it was taken from, so it can be taken again. |
sets[].sources[].refusal | body | string | — | Refusal is why this publisher's last take failed, if it did. |
sets[].sources[].source | body | string | — | Source is the publisher. |
sets[].sources[].terms | body | string | — | Terms is the CITATION that basis points at — the licence identifier, the registry, or the operator publication. |
sets[].sources[].version | body | string | — | Version is the content digest of what this publisher last supplied. |
sets[].stale | body | boolean | — | Stale is whether it is past that bound. |
sets[].version | body | string | — | Version is the exact baseline consulted — every contributing publisher and its content digest. |
sets[].what | body | string | — | What the set holds, in one sentence. |
stale | body | string[] | — | Stale names the sets past their freshness bound — the list to alarm on. |
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, ReferenceApi } from 'hanzoai';
const api = new ReferenceApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.riskReferenceSets();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_sets()cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.ReferenceAPI.RiskReferenceSets(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::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_sets(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.ReferenceApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new ReferenceApi(client).riskReferenceSets();curl https://api.hanzo.ai/v1/reference \
-H "Authorization: Bearer $HANZO_API_KEY"Tool reference, op riskReferenceSets — 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": "riskReferenceSets",
"input": {}
}
}
}'How is this guide?