Search graph

Finds assertions by their words, where read finds them by their keys, best match first.

GET /v1/graph/search

Graph → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/graph/search`
Method	`GET`
Operation	`graphSearch`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Finds assertions by their words, where read finds them by their keys, best match first.

Every word must match, as a prefix. The answer is ordered by bm25, which weighs a word by how rare it is and a row by how much of it the words are, so a limit keeps the best matches rather than the oldest. It resolves nothing, so a match may be a claim later corrected; ask resolve about what it finds.

Time: as_of and as_known bound it exactly as they bound read; either absent is no bound.

Request

5 fields.

Field	In	Type	Required	Description
`q`	query	string	yes	Q is what to look for: words, matched as prefixes, all of them required.
`relation`	query	string	—	Relation narrows to one relation.
`as_of`	query	string	—	AsOf bounds the search to statements begun by an instant of the world, RFC 3339.
`as_known`	query	string	—	AsKnown bounds the search to what this plane had heard by an instant, RFC 3339.
`limit`	query	integer	—	Limit caps how many assertions come back.

Response

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

200 body — 15 fields.

Field	In	Type	Always	Description
`assertions`	body	graph.wireFact[]	—	Assertions are the matching rows: a read's in the order they were written, oldest first; a search's best match first.
`assertions[].at`	body	string	—	At is when the thing was so, RFC 3339, as the asserter gave it.
`assertions[].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.
`assertions[].confidence`	body	number (double)	—	Confidence in [0,1] as the asserter gave it; absent is 0.
`assertions[].entity`	body	string	—	Entity is the thing described, in the organization's own namespace.
`assertions[].evidence`	body	string	—	Evidence points at the record the claim came from.
`assertions[].id`	body	string	—	ID is the assertion's content address, minted by the server from what was asserted.
`assertions[].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.
`assertions[].names`	body	boolean	—	Names true means the assertion is an edge and Value is an entity.
`assertions[].relation`	body	string	—	Relation is what was asserted of it.
`assertions[].seen`	body	string	—	Seen is when the asserter says it became knowable, RFC 3339.
`assertions[].source`	body	string	—	Source names who asserted, as the caller gave it.
`assertions[].until`	body	string	—	Until is when the thing stopped being so, RFC 3339, as the asserter gave it.
`assertions[].value`	body	string	—	Value is what the relation points at: another entity's key when Names is true, otherwise a scalar.
`truncated`	body	boolean	—	Truncated says more assertions matched than came back: the limit, or the ceiling, stopped the read.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo graph search

.ts

.py

.go

.rs

.java

import { Configuration, GraphApi } from 'hanzoai';

const api = new GraphApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.graphSearch({ q: 'q' });

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_search(q='q')

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

resp, _, err := client.GraphAPI.GraphSearch(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_search(&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).graphSearch();

curl https://api.hanzo.ai/v1/graph/search?q=%3Cq%3E \
  -H "Authorization: Bearer $HANZO_API_KEY"

Tool graph, op graphSearch — 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": "graph",
         "arguments": {
           "op": "graphSearch",
           "input": {
             "q": "<q>"
           }
         }
       }
     }'

Graph API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousResolve graph NextList vocabulary