Takes a new version of one set.

POST /v1/reference/refresh

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


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

Takes a new version of one set. SuperAdmin only.

It is platform work, not tenant work: it writes the shared baseline every organisation reads, so it is gated to the platform's own identity. Nothing here can write an organisation's overrides, and nothing an organisation sends can reach this route.

Idempotent. A version is the content digest of what was taken, so refreshing an unchanged publisher writes no rows and reports unchanged. Resumable: a run that died half-way is continued from where it stopped rather than restarted.

A set whose source needs a licence we do not hold is refused with the reason, rather than being quietly skipped.

Request

8 fields, body application/json (required).

Field	In	Type	Required	Description
`force`	body	boolean	—	Force accepts a take whose size moved past the change bound.
`receipts`	body	ReferenceReceipt[]	—	Receipts are supplied by the component that holds the membership, for a set of kind attest.
`receipts[].asOf`	body	string	—	AsOf is when the load happened, RFC 3339.
`receipts[].keys`	body	integer	—	Keys is how many designations that load carried.
`receipts[].refusal`	body	string	—	Refusal is why the load failed, when it did.
`receipts[].source`	body	string	—	Source is the publisher this receipt is for.
`receipts[].version`	body	string	—	Version is the digest of what that publisher supplied, so a refresh that changed nothing can be told from a refresh that did not run.
`set`	body	string	—	Set is the set to refresh.

Response

Status	Body	Meaning
`200`	RefreshReferenceOut	ok

200 body — 11 fields.

Field	In	Type	Always	Description
`set`	body	string	—	Set is the set refreshed.
`stale`	body	boolean	—	Stale is whether it is STILL past its freshness bound after the refresh, which is what a publisher that has stopped answering looks like.
`took`	body	ReferenceTaken[]	—	Took is what each publisher contributed.
`took[].keys`	body	integer	—	Keys is how many members it carries.
`took[].refusal`	body	string	—	Refusal is why this publisher contributed nothing, if it did not.
`took[].resumed`	body	boolean	—	Resumed is true when this run continued a version a previous run left half-landed.
`took[].source`	body	string	—	Source is the publisher.
`took[].unchanged`	body	boolean	—	Unchanged is true when the publisher's data was byte-for-byte the set we already held.
`took[].version`	body	string	—	Version is the content digest that landed.
`took[].wrote`	body	integer	—	Wrote is how many rows this run actually wrote.
`version`	body	string	—	Version is the set's new composed version.

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.riskRefreshReference({ force: false, receipts: [{"asOf":"<asOf>","keys":0,"refusal":"<refusal>","source":"<source>"}] });

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_refresh_reference(force=False, receipts=[{"asOf":"<asOf>","keys":0,"refusal":"<refusal>","source":"<source>"}])

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

resp, _, err := client.ReferenceAPI.RiskRefreshReference(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_refresh_reference(&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).riskRefreshReference();

curl -X POST https://api.hanzo.ai/v1/reference/refresh \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "force": false,
       "receipts": [
         {
           "asOf": "<asOf>",
           "keys": 0,
           "refusal": "<refusal>",
           "source": "<source>"
         }
       ]
     }'

Tool reference, op riskRefreshReference — 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": "riskRefreshReference",
           "input": {
             "force": false,
             "receipts": [
               {
                 "asOf": "<asOf>",
                 "keys": 0,
                 "refusal": "<refusal>",
                 "source": "<source>"
               }
             ]
           }
         }
       }
     }'

Reference API · All Hanzo APIs · Interactive reference

Takes a new version of one set.

Request

Response

Examples

On this page