---
title: "Context Graph API"
description: "Multi-hop knowledge graph traversal, GraphRAG hybrid search, ontology management, and edge versioning"
canonical: "https://docs.ainative.studio/docs/api/context-graph"
last-updated: "2026-10-03T21:47:10.764Z"
---

# Context Graph API

Source: https://docs.ainative.studio/docs/api/context-graph

> Multi-hop knowledge graph traversal, GraphRAG hybrid search, ontology management, and edge versioning

# Context Graph API

The Context Graph extends ZeroMemory with a knowledge graph layer. Entities, edges, and multi-hop traversal power contextual reasoning beyond vector similarity.

**Base URL:** `https://api.ainative.studio/api/v1/public/memory/v2/graph`

All endpoints require `Authorization: Bearer <token>`.

---

## Core Graph

### POST /entity

Create or update an entity. If the entity exists, aliases are merged and memory_count is incremented.

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/entity \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "canonical_name": "Alice Johnson",
    "entity_type": "person",
    "aliases": ["alice", "AJ"],
    "properties": {"title": "CTO", "company": "AINative"}
  }'
```

**Response:**
```json
{
  "id": "c002751b-...",
  "canonical_name": "Alice Johnson",
  "entity_type": "person",
  "aliases": ["alice", "AJ"],
  "properties": {"title": "CTO", "company": "AINative"},
  "memory_count": 1,
  "status": "created"
}
```

### POST /edge

Create a directed edge between two entities. If an active edge with the same source + predicate exists but different target, the old edge is auto-superseded (contradiction detection).

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/edge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_name": "Alice Johnson",
    "target_name": "AINative Studio",
    "predicate": "works_at",
    "confidence": 0.95
  }'
```

### POST /traverse

Multi-hop graph traversal via recursive CTE. Returns all reachable nodes and edges up to `max_hops` depth.

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/traverse \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "Alice Johnson",
    "max_hops": 3,
    "predicates": ["works_at", "knows"],
    "min_confidence": 0.5
  }'
```

**Response:**
```json
{
  "nodes": [
    {"id": "...", "label": "Alice Johnson", "type": "person", "properties": {}},
    {"id": "...", "label": "AINative Studio", "type": "org", "properties": {}}
  ],
  "edges": [
    {"id": "...", "source": "...", "target": "...", "predicate": "works_at", "confidence": 0.95, "depth": 1}
  ],
  "paths": []
}
```

Optional `as_of` parameter for historical graph state (edge versioning).

### GET /neighbors/\{entity_name\}

Direct connections for an entity (1-hop).

### GET /stats

Graph analytics: node count, edge count, density, top entities.

### GET /entities

List entities with optional type filter and pagination.

```
GET /entities?entity_type=person&limit=50&offset=0
```

### POST /entity/merge

Merge duplicate entities. Re-points all edges and consolidates aliases.

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/entity/merge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "canonical": "Alice Johnson",
    "merge": ["alice", "Alice", "AJ"]
  }'
```

---

## GraphRAG

### POST /graphrag

Hybrid search blending vector similarity with graph proximity.

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/graphrag \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "pricing strategy",
    "limit": 10,
    "graph_weight": 0.3,
    "max_hops": 2
  }'
```

| Parameter | Default | Description |
|-----------|---------|-------------|
| `graph_weight` | 0.3 | 0 = pure vector, 1 = pure graph, 0.3 = 70% vector + 30% graph |
| `max_hops` | 2 | How far to traverse from matched entities |

**Response:** Same shape as `/recall` with added `vector_score`, `graph_boost`, and blended `score` fields.

---

## Ontology

### GET /ontology

Get the project's ontology definition.

```
GET /ontology?project_id=<uuid>
```

### POST /ontology

Define or update a project ontology. Version auto-increments on update.

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/ontology \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<uuid>",
    "entity_types": ["customer", "order", "product"],
    "predicates": {
      "customer": {"places": "order", "prefers": "product"},
      "order": {"contains": "product"}
    }
  }'
```

### POST /ontology/infer

Auto-infer an ontology from existing entity/edge patterns.

```
POST /ontology/infer?min_entity_count=5&min_predicate_count=3
```

### POST /ontology/apply

Apply an inferred ontology and retroactively classify entities.

---

## Edge Versioning

### GET /contradictions

List edges that were superseded by newer conflicting edges.

### POST /contradictions/\{edge_id\}/resolve

Resolve a contradiction. Actions: `accept_new`, `keep_both`, `reject_new`.

---

## Templates

### GET /templates

List 5 pre-built semantic data product templates.

```json
[
  {"name": "customer-support", "description": "Ontology for customer support workflows", "entity_types": ["customer", "ticket", "product", "agent", "knowledge_article"]},
  {"name": "research", "description": "Ontology for academic/research workflows", ...},
  {"name": "code-review", "description": "Ontology for software development", ...},
  {"name": "sales", "description": "Ontology for sales and CRM", ...},
  {"name": "knowledge-base", "description": "Ontology for documentation and Q&A", ...}
]
```

### POST /templates/\{name\}/apply

Apply a template to a project: creates ontology + seeds entities.

```
POST /templates/customer-support/apply?project_id=<uuid>
```