Create diff

Reports what came into force, was superseded and was retracted between two points.

POST /v1/graph/diff

Graph → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/graph/diff`
Method	`POST`
Operation	`graphDiff`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Reports what came into force, was superseded and was retracted between two points.

Each point is resolved as resolve would, never read off the rows in between. A version that loses the order is invisible here as it is there, and one that repeats what held is agreement, not change.

Time: a point is an as_of and an as_known instant, from and from_known against to and to_known. Hold the known instants equal for what happened in the world; hold the valid instants equal for what the record learned. to and to_known default to now, from to to and from_known to to_known, and the two points must differ.

Request

6 fields, body application/json (required).

Field	In	Type	Required	Description
`entity`	body	string	—	Entity narrows the diff to what was asserted about one entity.
`from`	body	string	—	From is the earlier instant of the world, RFC 3339. What held here is the baseline, so a statement beginning exactly at From is part of it and not a change.
`from_known`	body	string	—	FromKnown is how much this plane had heard at the baseline, RFC 3339.
`limit`	body	integer (int64)	—	Limit caps how many (entity, relation) pairs are examined, in key order.
`to`	body	string	—	To is the later instant of the world, RFC 3339, and may not precede From.
`to_known`	body	string	—	ToKnown is how much it had heard at the later point, RFC 3339, and may not precede FromKnown.

Response

Status	Body	Meaning
`200`	graph.graphDiffOut	ok
`default`	problem-details	refused

200 body — 78 fields.

Field	In	Type	Always	Description
`asserted`	body	graph.wireFact[]	—	Asserted is each statement holding at To that did not at From.
`asserted[].at`	body	string	—	At is when the thing was so, RFC 3339, as the asserter gave it.
`asserted[].by`	body	string	—	By is the identity that filed it — `owner` or `owner/user` — stamped from the validated principal at the write, never from the body.
`asserted[].confidence`	body	number (double)	—	Confidence in [0,1] as the asserter gave it; absent is 0.
`asserted[].entity`	body	string	—	Entity is the thing described, in the organization's own namespace.
`asserted[].evidence`	body	string	—	Evidence points at the record the claim came from.
`asserted[].id`	body	string	—	ID is the assertion's content address, minted by the server from what was asserted.
`asserted[].knowable`	body	string	—	Knowable is the first instant this plane could have answered with the assertion, RFC 3339: the later of Seen and the server's clock at the write.
`asserted[].names`	body	boolean	—	Names true means the assertion is an edge and Value is an entity.
`asserted[].relation`	body	string	—	Relation is what was asserted of it.
`asserted[].seen`	body	string	—	Seen is when the asserter says it became knowable, RFC 3339.
`asserted[].source`	body	string	—	Source names who asserted, as the caller gave it.
`asserted[].until`	body	string	—	Until is when the thing stopped being so, RFC 3339, as the asserter gave it.
`asserted[].value`	body	string	—	Value is what the relation points at: another entity's key when Names is true, otherwise a scalar.
`bound`	body	integer (int64)	—	Bound is how many pairs this diff examined at most.
`from`	body	string	—	From is the earlier instant, RFC 3339, echoed.
`from_known`	body	string	—	FromKnown is the knowledge instant of the baseline, RFC 3339.
`retracted`	body	graph.graphChange[]	—	Retracted is each statement that held at From and no longer does at To, with what ended it as Now: the retraction, the later value, or the statement itself…
`retracted[].now`	body	graph.wireFact	—
`retracted[].now.at`	body	string	—	At is when the thing was so, RFC 3339, as the asserter gave it.
`retracted[].now.by`	body	string	—	By is the identity that filed it — `owner` or `owner/user` — stamped from the validated principal at the write, never from the body.
`retracted[].now.confidence`	body	number (double)	—	Confidence in [0,1] as the asserter gave it; absent is 0.
`retracted[].now.entity`	body	string	—	Entity is the thing described, in the organization's own namespace.
`retracted[].now.evidence`	body	string	—	Evidence points at the record the claim came from.
`retracted[].now.id`	body	string	—	ID is the assertion's content address, minted by the server from what was asserted.
`retracted[].now.knowable`	body	string	—	Knowable is the first instant this plane could have answered with the assertion, RFC 3339: the later of Seen and the server's clock at the write.
`retracted[].now.names`	body	boolean	—	Names true means the assertion is an edge and Value is an entity.
`retracted[].now.relation`	body	string	—	Relation is what was asserted of it.
`retracted[].now.seen`	body	string	—	Seen is when the asserter says it became knowable, RFC 3339.
`retracted[].now.source`	body	string	—	Source names who asserted, as the caller gave it.
`retracted[].now.until`	body	string	—	Until is when the thing stopped being so, RFC 3339, as the asserter gave it.
`retracted[].now.value`	body	string	—	Value is what the relation points at: another entity's key when Names is true, otherwise a scalar.
`retracted[].was`	body	graph.wireFact	—
`retracted[].was.at`	body	string	—	At is when the thing was so, RFC 3339, as the asserter gave it.
`retracted[].was.by`	body	string	—	By is the identity that filed it — `owner` or `owner/user` — stamped from the validated principal at the write, never from the body.
`retracted[].was.confidence`	body	number (double)	—	Confidence in [0,1] as the asserter gave it; absent is 0.
`retracted[].was.entity`	body	string	—	Entity is the thing described, in the organization's own namespace.
`retracted[].was.evidence`	body	string	—	Evidence points at the record the claim came from.
`retracted[].was.id`	body	string	—	ID is the assertion's content address, minted by the server from what was asserted.
`retracted[].was.knowable`	body	string	—	Knowable is the first instant this plane could have answered with the assertion, RFC 3339: the later of Seen and the server's clock at the write.
`retracted[].was.names`	body	boolean	—	Names true means the assertion is an edge and Value is an entity.
`retracted[].was.relation`	body	string	—	Relation is what was asserted of it.
`retracted[].was.seen`	body	string	—	Seen is when the asserter says it became knowable, RFC 3339.
`retracted[].was.source`	body	string	—	Source names who asserted, as the caller gave it.
`retracted[].was.until`	body	string	—	Until is when the thing stopped being so, RFC 3339, as the asserter gave it.
`retracted[].was.value`	body	string	—	Value is what the relation points at: another entity's key when Names is true, otherwise a scalar.
`superseded`	body	graph.graphChange[]	—	Superseded is each property whose value at From was replaced by a different one at To, once per pair however many came in between.
`superseded[].now`	body	graph.wireFact	—
`superseded[].now.at`	body	string	—	At is when the thing was so, RFC 3339, as the asserter gave it.
`superseded[].now.by`	body	string	—	By is the identity that filed it — `owner` or `owner/user` — stamped from the validated principal at the write, never from the body.
`superseded[].now.confidence`	body	number (double)	—	Confidence in [0,1] as the asserter gave it; absent is 0.
`superseded[].now.entity`	body	string	—	Entity is the thing described, in the organization's own namespace.
`superseded[].now.evidence`	body	string	—	Evidence points at the record the claim came from.
`superseded[].now.id`	body	string	—	ID is the assertion's content address, minted by the server from what was asserted.
`superseded[].now.knowable`	body	string	—	Knowable is the first instant this plane could have answered with the assertion, RFC 3339: the later of Seen and the server's clock at the write.
`superseded[].now.names`	body	boolean	—	Names true means the assertion is an edge and Value is an entity.
`superseded[].now.relation`	body	string	—	Relation is what was asserted of it.
`superseded[].now.seen`	body	string	—	Seen is when the asserter says it became knowable, RFC 3339.
`superseded[].now.source`	body	string	—	Source names who asserted, as the caller gave it.
`superseded[].now.until`	body	string	—	Until is when the thing stopped being so, RFC 3339, as the asserter gave it.
`superseded[].now.value`	body	string	—	Value is what the relation points at: another entity's key when Names is true, otherwise a scalar.
`superseded[].was`	body	graph.wireFact	—
`superseded[].was.at`	body	string	—	At is when the thing was so, RFC 3339, as the asserter gave it.
`superseded[].was.by`	body	string	—	By is the identity that filed it — `owner` or `owner/user` — stamped from the validated principal at the write, never from the body.
`superseded[].was.confidence`	body	number (double)	—	Confidence in [0,1] as the asserter gave it; absent is 0.
`superseded[].was.entity`	body	string	—	Entity is the thing described, in the organization's own namespace.
`superseded[].was.evidence`	body	string	—	Evidence points at the record the claim came from.
`superseded[].was.id`	body	string	—	ID is the assertion's content address, minted by the server from what was asserted.
`superseded[].was.knowable`	body	string	—	Knowable is the first instant this plane could have answered with the assertion, RFC 3339: the later of Seen and the server's clock at the write.
`superseded[].was.names`	body	boolean	—	Names true means the assertion is an edge and Value is an entity.
`superseded[].was.relation`	body	string	—	Relation is what was asserted of it.
`superseded[].was.seen`	body	string	—	Seen is when the asserter says it became knowable, RFC 3339.
`superseded[].was.source`	body	string	—	Source names who asserted, as the caller gave it.
`superseded[].was.until`	body	string	—	Until is when the thing stopped being so, RFC 3339, as the asserter gave it.
`superseded[].was.value`	body	string	—	Value is what the relation points at: another entity's key when Names is true, otherwise a scalar.
`to`	body	string	—	To is the later instant, RFC 3339: the one asked for, or the server's clock when none was.
`to_known`	body	string	—	ToKnown is the knowledge instant of the later point, RFC 3339.
`truncated`	body	boolean	—	Truncated says more pairs gathered assertions in the interval than Bound, or that one pair holds more than a single read returns.

Failure carries the platform error shape — see Errors.

Examples

hanzo graph diff

import { Configuration, GraphApi } from 'hanzoai';

const api = new GraphApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.graphDiff({ entity: "<entity>", from: "<from>" });

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = GraphApi(client).graph_diff(entity="<entity>", from="<from>")

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

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

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

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

let result = graph_api::graph_diff(&cfg, Default::default()).await?;

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

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

var result = new GraphApi(client).graphDiff();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl -X POST https://api.hanzo.ai/v1/graph/diff \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "entity": "<entity>",
       "from": "<from>"
     }'

MCP declares no tool for graph — tools/list on https://api.hanzo.ai/v1/mcp names the products it does reach. Use HTTP or an SDK.

Graph API · All Hanzo APIs · Interactive reference

Request

Response

Examples

On this page