List ontology

Lists the entity classes, predicates, classifier features and kinship scorecard columns of the personal knowledge graph ontology.

GET /v1/graph/ontology

Graph → · All API references → · Get started →

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

Lists the entity classes, predicates, classifier features and kinship scorecard columns of the personal knowledge graph ontology.

Every code graph.db and entityTagging.db write on macOS and iOS is here with its plain-language reading and the canonical relation key graphApple maps it to. Filter by group or by substring q.

Time: it takes no as_of or as_known; the shipped catalog is static.

Request

2 fields.

Field	In	Type	Required	Description
`group`	query	string	—	Group narrows classes or features to one group, such as core, person, activity, edge, identity, communication or photos.
`q`	query	string	—	Q narrows classes, predicates and features to entries whose code, label, canonical relation or source contains this substring, case-insensitively.

Response

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

200 body — 19 fields.

Field	In	Type	Always	Description
`classes`	body	graph.graphOntologyClass[]	—	Classes is the matching entity classes (181 in the unfiltered catalog).
`classes[].edge`	body	boolean	—	Edge is true for the relationship-type classes (CS* and nm_*RelationshipType) that reify a two-row edge sharing a relationshipId in stable_graph.
`classes[].group`	body	string	—	Group is the class family: core, person, attribute, place, event, activity, activity type, transport, media, animal, commerce or edge.
`classes[].id`	body	string	—	ID is the raw code stored in graph.db, such as SB104, CS165 or nm_walletOrder.
`classes[].label`	body	string	—	Label is the human-readable class name, such as person or employment relationship type.
`classes[].mechanism`	body	string	—	Mechanism records whether the daemon mechanism populating the class is implemented, unverified or unlocated.
`features`	body	graph.graphOntologyFeature[]	—	Features is the matching EntityTagging classifier features (144 in the unfiltered catalog).
`features[].group`	body	string	—	Group is the feature block: identity (0..19), communication (20..59) or photos (60..143).
`features[].index`	body	integer (int64)	—	Index is the feature's 0-based position (0..143) in metadata.json.
`features[].name`	body	string	—	Name is Apple's feature identifier, such as sameLastName or photosPersonPosteriorProbabilityGivenSaturdayNight.
`predicates`	body	graph.graphOntologyPredicate[]	—	Predicates is the matching predicates (278 in the unfiltered catalog).
`predicates[].id`	body	string	—	ID is the raw predicate code stored in graph.db, such as PS1, PS500 or nm_isCurrentUser.
`predicates[].label`	body	string	—	Label is the plain-language reading of what the predicate records.
`predicates[].mechanism`	body	string	—	Mechanism records whether the daemon mechanism is implemented, unverified or unlocated.
`predicates[].method`	body	string	—	Method names how the daemon obtains the value: Copied, Joined, Rule, Apple-shipped, Embedding model, XGBoost, Face clustering or Local LLM.
`predicates[].names`	body	boolean	—	Names is true when the predicate links its subject to another entity rather than a scalar literal.
`predicates[].relation`	body	string	—	Relation is the canonical snake_case relation key this plane files the predicate under when ingesting an Apple graph.
`predicates[].source`	body	string	—	Source names the OS store or subsystem the daemon reads the predicate from.
`score_columns`	body	string[]	—	ScoreColumns is the 17 relationship columns of entityTagging.db's kinship scorecard.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo graph ontology

.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.graphOntology();

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_ontology()

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

resp, _, err := client.GraphAPI.GraphOntology(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_ontology(&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).graphOntology();

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 https://api.hanzo.ai/v1/graph/ontology \
  -H "Authorization: Bearer $HANZO_API_KEY"

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

Graph API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousCreate neighbors NextCreate path