ZeroDB · Knowledge Graph API
Entities, edges, SPARQL & GraphRAG
Model people, orgs, technologies, and concepts. Connect them with typed directional edges. Traverse N hops, run SPARQL 1.1 queries, and blend graph proximity with vector similarity for GraphRAG — all under one REST API, one key.
Looking for concepts and terminology first? Explore the knowledge graph concepts overview →
Entities & typed edges
Nodes carry a type — person, org, tech, or concept. Directional edges carry a predicate and confidence score (0–1). Entities de-duplicate on (name, type), so creating the same node twice merges it.
Temporal versioning
When a fact changes, ZeroDB supersedes the old edge instead of deleting it. Every edge has valid_from, valid_until, and superseded_by. Pass "as_of" to any traverse call to query the graph at any point in time.
GraphRAG — graph + vectors
graph_weight blends vector similarity with graph proximity. A value of 0.3 means 70% semantic + 30% structural. Use it when connection in the graph matters as much as text meaning.
Quickstart — get a key
Provision an Instant DB in one POST — no signup form, credentials returned immediately.
# 1. Provision an Instant DB
curl -X POST https://api.ainative.studio/api/v1/public/instant-db \
-H "Content-Type: application/json" \
-d '{"agree_terms": true, "on_behalf_of": "<your-user-id>"}'
# Response includes your X-API-Key — use it in every graph call belowCreate an entity
Entities de-duplicate on (canonical_name, entity_type). POSTing the same name and type a second time merges the records.
Request
POST /api/v1/public/memory/v2/graph/entity
X-API-Key: <your-key>
{
"canonical_name": "Alice Johnson",
"entity_type": "person",
"aliases": ["alice", "AJ"],
"properties": { "title": "CTO" }
}Response
{
"id": "...",
"canonical_name": "Alice Johnson",
"entity_type": "person",
"aliases": ["alice", "AJ"],
"properties": { "title": "CTO" },
"memory_count": 0,
"status": "created"
}Create a typed edge
Edges are directional: source → predicate → target. Set confidence between 0 and 1 to express certainty. Edges are versioned — when a fact changes, the old edge gets valid_until set automatically.
Request
POST /api/v1/public/memory/v2/graph/edge
X-API-Key: <your-key>
{
"source_name": "Alice Johnson",
"target_name": "OpenAI",
"predicate": "works_at",
"confidence": 0.9,
"properties": { "start_date": "2026-01-15" }
}Response
{
"id": "...",
"source_id": "...",
"target_id": "...",
"predicate": "works_at",
"confidence": 0.9
}List neighbors
Fetch all edges connected to an entity. URL-encode the entity name.
Request
GET /api/v1/public/memory/v2/graph/neighbors/Alice%20Johnson?limit=25 X-API-Key: <your-key>
Response
{
"edges": [{
"source_name": "Alice Johnson",
"source_type": "person",
"target_name": "OpenAI",
"target_type": "org",
"predicate": "works_at",
"confidence": 0.9,
"valid_from": "2026-01-15T00:00:00Z",
"valid_until": null,
"superseded_by": null
}]
}Traverse the graph
Walk up to max_hops hops from a starting entity, filtering by predicate and minimum confidence. Add as_of to query historical state.
POST /api/v1/public/memory/v2/graph/traverse
X-API-Key: <your-key>
{
"entity": "Alice Johnson",
"max_hops": 3,
"predicates": ["works_at", "received_grant_from"],
"min_confidence": 0.5,
"as_of": "2026-06-01T00:00:00Z" // optional — historical query
}Entity resolution & merge
Fuzzy-search for entities by name to detect duplicates, then merge aliases into a canonical record.
# Find candidates
GET /api/v1/public/memory/v2/graph/resolve?q=alice&limit=5
X-API-Key: <your-key>
# Merge duplicates into the canonical record
POST /api/v1/public/memory/v2/graph/entity/merge
X-API-Key: <your-key>
{
"canonical": "Alice Johnson",
"merge": ["Alice", "AJ Johnson"]
}Define or infer an ontology
Declare which entity types and predicates are valid for your project — or let ZeroDB infer an ontology from the edges you have already created.
Define
POST /api/v1/public/memory/v2/graph/ontology
X-API-Key: <your-key>
{
"project_id": "{project_id}",
"entity_types": ["person", "org", "tech"],
"predicates": {
"works_at": {
"source": "person",
"target": "org"
},
"received_grant_from": {
"source": "org",
"target": "org"
}
}
}Infer from existing graph
POST /api/v1/public/memory/v2/graph/ontology/infer ?min_entity_count=3 &min_predicate_count=2 X-API-Key: <your-key>
ZeroDB scans existing edges and derives the ontology automatically — useful when you want to validate a graph that was built incrementally.
GraphRAG — graph + vector search
Blend semantic similarity with graph proximity. graph_weight: 0.0 = pure vector, 1.0 = pure graph, 0.3 = balanced.
POST /api/v1/public/memory/v2/graph/graphrag
X-API-Key: <your-key>
{
"query": "AI companies building developer tools",
"limit": 10,
"graph_weight": 0.3,
"max_hops": 2
}Results are ranked by a weighted sum of cosine similarity and inverse graph distance from the nearest matching entity. Ideal for "find contacts connected to this topic" and similar agent memory retrieval patterns.
SPARQL 1.1 queries
Run SELECT, ASK, or CONSTRUCT queries directly against the knowledge graph.
POST /api/v1/public/memory/v2/graph/sparql
X-API-Key: <your-key>
Content-Type: application/sparql-query
SELECT ?person ?org WHERE {
?person a <entity:person> .
?org a <entity:org> .
?person <predicate:works_at> ?org .
}Export, stats & centrality
Export the full graph for use in Gephi, D3, or RDF tools. Inspect structure with stats and centrality rankings.
# Export as D3/Cytoscape JSON or Gephi GEXF GET /api/v1/public/memory/v2/graph/export?format=json GET /api/v1/public/memory/v2/graph/export?format=gexf # RDF / linked-data interchange GET /api/v1/public/memory/v2/graph/export/vault-ld # Graph statistics (node count, edge count, density, …) GET /api/v1/public/memory/v2/graph/stats # Centrality rankings (degree, betweenness, pagerank) GET /api/v1/public/memory/v2/graph/centrality
Get the ZeroDB Knowledge Graph Step-by-Step Guide
Free PDF workbook: model entities and edges, define an ontology, traverse the graph, and run GraphRAG — step by step.
Frequently asked questions
What is the ZeroDB Knowledge Graph API?
It is a REST API for modeling entities (people, orgs, technologies, concepts) and the typed, directional relationships between them. You POST entities and edges, traverse N hops, filter by predicate and confidence, and run SPARQL 1.1 queries — all under /api/v1/public/memory/v2/graph/...
What are entity types and predicates?
Entity types are person, org, tech, or concept. A predicate is the label on a directed edge — for example works_at (person → org) or received_grant_from (org → org). You define allowed predicates in an ontology to keep the graph consistent, or let ZeroDB infer one from the graph you have already built.
How does temporal versioning work?
Every edge has valid_from and valid_until timestamps plus a superseded_by pointer. When you add an edge whose source+predicate combination already points at a different target, ZeroDB records a contradiction and supersedes the old edge — the old edge keeps its history. Add "as_of" to any traverse call to query the graph as it was at a point in time.
What is GraphRAG and when should I use it?
GraphRAG blends vector similarity (semantic meaning) with graph proximity (structural connection). A graph_weight of 0.3 means results are scored as 70% vector similarity plus 30% graph centrality. Use it when you want results that are both semantically similar to the query AND structurally connected in your knowledge graph — e.g. finding AI companies connected to CRM contacts.
Does the Knowledge Graph API support SPARQL?
Yes. POST /api/v1/public/memory/v2/graph/sparql accepts SPARQL 1.1 SELECT, ASK, and CONSTRUCT queries. You can also export the full graph as D3/Cytoscape JSON, Gephi GEXF, or RDF Vault-LD for interoperability with external graph tools.
