Documentation

API & Integration Guide

Everything you need to connect, query, and build on top of Graffold.

Quick Start

Base URL: http://localhost:8000

Auth: Bearer token via Authorization header (except health endpoints).

All request/response bodies are JSON. Streaming responses use Server-Sent Events.

Sessions

Create a session to configure your database, LLM provider, and agent type. All queries run within a session context.

POST /v1/sessions

{
  "llm_service": "bedrock",
  "database_name": "neo4j",
  "agent_type": "graph_rag_agent",
  "connection_details": {
    "uri": "bolt://localhost:7687",
    "user": "neo4j",
    "password": "..."
  }
}

Returns a session_id for all subsequent queries. Sessions can be shared (view-only or editable) via the Org Panel.

Query

Execute natural language queries against your knowledge graph. Supports mode selection and search depth control.

POST /v1/sessions/{session_id}/query

{
  "question": "Which suppliers have compliance gaps?",
  "mode": "hybrid",
  "search_depth": "balanced",
  "stream": false
}

Query Modes

naive

Direct LLM answer, no graph retrieval

local

Entity neighborhood search

global

Community summary-based retrieval

hybrid

Merges local + global with deduplication

Search Depth

fast

Discovery only, no expansion

balanced

1 expansion round, Cypher fallback if < 3 targets

deep

Up to 3 rounds, always runs Cypher fallback

Streaming (SSE)

Set "stream": true for real-time token-by-token responses.

event: retrieval_started
event: retrieval_complete
event: synthesis_started
event: token → {"text": "Several", "index": 0}
event: token → {"text": " suppliers", "index": 1}
...
event: complete → {"sources": [...], "cost": {...}}

KNN Expansion

Expand query results with k-nearest neighbors to discover connected entities beyond the initial answer.

POST /v1/sessions/{session_id}/expand-knn

{
  "expansion_level": 1,
  "query_index": null
}

Ingestion

Ingest documents via the API. Supports PDF upload (multipart), and any source with an API connector.

POST /v1/ingestion/jobs

Content-Type: multipart/form-data

source=pdf
database=mydb
files=@document.pdf

10MB per file, 50 files per batch. The pipeline handles chunking, entity extraction, consolidation, and embedding generation.

Other Endpoints

GET

/v1/sessions/{session_id}/stats

Node counts, relationship counts, degree distributions

GET

/v1/costs

Aggregated LLM cost data by session and operation type

GET

/v1/metrics

Query latency, cache hit rates, multi-hop success, mode distribution

GET

/health/ready

Readiness probe — checks DB + LLM connectivity (no auth required)

Python Client

import requests

BASE = "http://localhost:8000"
HEADERS = {"Authorization": "Bearer token", "Content-Type": "application/json"}

# Create session
session = requests.post(f"{BASE}/v1/sessions", headers=HEADERS, json={
    "llm_service": "bedrock",
    "database_name": "neo4j",
    "connection_details": {"uri": "bolt://localhost:7687", "user": "neo4j", "password": "..."}
}).json()

# Query
result = requests.post(
    f"{BASE}/v1/sessions/{session['session_id']}/query",
    headers=HEADERS,
    json={"question": "What connects entity A to entity B?", "mode": "hybrid"}
).json()

print(result["answer"])

Questions? Get in Touch