⭐ GitHub

API Reference

Base URL: http://localhost:8080 — All endpoints accept and return JSON.

Setup

Configure the LLM provider used for embeddings and entity extraction.

POST /api/setup Configure LLM provider

Request Body

  • provider string required — LLM provider enum
  • chatModelName string required — Chat model name
  • embedModelName string required — Embedding model name
  • apiKey string optional — API key for the provider
  • baseUrl string optional — Custom base URL (e.g. Azure endpoint)

Example

curl -X POST http://localhost:8080/api/setup \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "GEMINI",
    "chatModelName": "gemini-2.0-flash",
    "embedModelName": "gemini-embedding-001",
    "apiKey": "YOUR_API_KEY"
  }'

Response — SetupResponse

{
  "message": "LLM configured successfully",
  "success": true,
  "configuredProvider": "GEMINI",
  "configuredChatModel": "gemini-2.0-flash",
  "configuredEmbedModel": "gemini-embedding-001",
  "timestamp": "2025-01-15T10:00:00Z"
}

Ingest

Ingest documents into CortexDB. The content is stored immediately, then processed asynchronously (chunking, embedding, entity/relation extraction).

POST /api/v1/memory/ingest/document Ingest a structured document (PageIndex)

Request Body

  • uid string required — User identifier
  • documentTitle string required — Title of the document
  • documentText string required — Full text content to ingest
  • metadata object optional — Arbitrary key-value metadata

Example

curl -X POST http://localhost:8080/api/v1/memory/ingest/document \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "user-1",
    "documentTitle": "Memory Management in Java",
    "documentText": "Java uses garbage collection for memory management."
  }'

Response — IngestResponse

{
  "knowledgeBase": {
    "id": "a1b2c3d4-...",
    "uid": "user-1",
    "content": "Java uses garbage collection...",
    "createdAt": "2025-01-15T10:00:00Z"
  },
  "status": "SUCCESS",
  "message": "Document ingested successfully",
  "processingTimeMs": 245,
  "embeddingTimeMs": 120
}
POST /api/v1/memory/ingest/prompt Ingest a conversational prompt (SimpleMem)

Request Body

  • uid string required — User identifier
  • converser string required — Role: USER, AGENT, or SYSTEM
  • text string required — Conversational text to ingest
  • metadata object optional — Arbitrary key-value metadata

Example

curl -X POST http://localhost:8080/api/v1/memory/ingest/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "user-1",
    "converser": "USER",
    "text": "What is the capital of France?"
  }'

Response — IngestResponse

{
  "knowledgeBase": {
    "id": "b2c3d4e5-...",
    "uid": "user-1",
    "content": "What is the capital of France?",
    "createdAt": "2025-01-15T10:01:00Z"
  },
  "status": "SUCCESS",
  "message": "Prompt ingested successfully",
  "processingTimeMs": 150,
  "embeddingTimeMs": 85
}
ℹ️ Async Processing:

The response returns immediately. Chunking, embedding, entity extraction, and graph building happen asynchronously via PostgreSQL triggers.

Context Endpoints

Search and retrieve text chunks (contexts) created during document ingestion.

POST /api/v1/memory/query/contexts Semantic search on contexts

Request Body — QueryRequest

  • query string required — Search text
  • limit int optional — Max results (default: 5)
  • minRelevance double optional — Min score 0–1 (default: 0.7)
  • filters object optional — Metadata filters

Example

curl -X POST http://localhost:8080/api/v1/memory/query/contexts \
  -H "Content-Type: application/json" \
  -d '{"query": "memory management", "limit": 5, "minRelevance": 0.7}'
GET /api/v1/memory/query/contexts/kb/{kbId} Get contexts by knowledge base ID

Path Parameters

  • kbId UUID required — Knowledge base ID
curl http://localhost:8080/api/v1/memory/query/contexts/kb/a1b2c3d4-...
GET /api/v1/memory/query/contexts/recent Get recent contexts

Query Parameters

  • days int optional — Lookback period (default: 7)
curl "http://localhost:8080/api/v1/memory/query/contexts/recent?days=7"
GET /api/v1/memory/query/contexts/range Get contexts by date range

Query Parameters

  • startDate string required — ISO-8601 start date
  • endDate string required — ISO-8601 end date
curl "http://localhost:8080/api/v1/memory/query/contexts/range?startDate=2025-01-01&endDate=2025-01-31"
POST /api/v1/memory/query/contexts/recent Search recent contexts with vector similarity

Query Parameters

  • days int optional — Lookback period (default: 7)

Request Body — QueryRequest

Same as POST /api/v1/memory/query/contexts.

curl -X POST "http://localhost:8080/api/v1/memory/query/contexts/recent?days=7" \
  -H "Content-Type: application/json" \
  -d '{"query": "memory", "limit": 5, "minRelevance": 0.7}'
GET /api/v1/memory/query/contexts/siblings/{contextId} Get sibling contexts (same document)

Path Parameters

  • contextId UUID required — Context ID
curl http://localhost:8080/api/v1/memory/query/contexts/siblings/c1d2e3f4-...

Entity Endpoints

Search the extracted entities (concepts, people, technologies, etc.) in the knowledge graph.

POST /api/v1/memory/query/entities Semantic search on entities

Request Body — QueryRequest

Same schema as context search.

curl -X POST http://localhost:8080/api/v1/memory/query/entities \
  -H "Content-Type: application/json" \
  -d '{"query": "Java programming", "limit": 5, "minRelevance": 0.7}'
GET /api/v1/memory/query/entities/name/{name} Find entity by exact name

Returns 404 if not found.

curl http://localhost:8080/api/v1/memory/query/entities/name/Java

Response — RagEntity

{
  "id": "e1...",
  "name": "Java",
  "type": "Technology",
  "description": "A programming language...",
  "vectorEmbedding": [0.31, ...]
}
GET /api/v1/memory/query/entities/name-ignore-case/{name} Find entity by name (case-insensitive) 
curl http://localhost:8080/api/v1/memory/query/entities/name-ignore-case/java
GET /api/v1/memory/query/entities/id/{name} Get entity ID by name 
curl http://localhost:8080/api/v1/memory/query/entities/id/Java

Response

{ "id": "e1a2b3c4-..." }
POST /api/v1/memory/query/entities/disambiguate Disambiguate entity with context

Query Parameters

  • entityName string required — Entity name to disambiguate

Request Body

Plain text (Content-Type: text/plain) providing context for disambiguation.

curl -X POST "http://localhost:8080/api/v1/memory/query/entities/disambiguate?entityName=Apple" \
  -H "Content-Type: text/plain" \
  -d "I was eating a fresh apple from the orchard"
GET /api/v1/memory/query/entities/{entityId}/contexts Get all contexts mentioning an entity 
curl http://localhost:8080/api/v1/memory/query/entities/e1a2b3c4-.../contexts
GET /api/v1/memory/query/contexts/{contextId}/entities Get all entities mentioned in a context 
curl http://localhost:8080/api/v1/memory/query/contexts/c1d2e3f4-.../entities
POST /api/v1/memory/query/entities/merge Merge two entities

Query Parameters

  • sourceEntityId UUID required — Entity to merge from
  • targetEntityId UUID required — Entity to merge into
curl -X POST "http://localhost:8080/api/v1/memory/query/entities/merge?sourceEntityId=e1...&targetEntityId=e2..."
⚠️ Destructive:

This reassigns all context links and relations from the source entity to the target entity.

History Endpoints

Search and retrieve knowledge base entries (the raw ingested documents).

POST /api/v1/memory/query/history Semantic search on history

Request Body — QueryRequest

curl -X POST http://localhost:8080/api/v1/memory/query/history \
  -H "Content-Type: application/json" \
  -d '{"query": "Java memory", "limit": 5}'
GET /api/v1/memory/query/history/user/{uid} Get all history for a user 
curl http://localhost:8080/api/v1/memory/query/history/user/user-1
GET /api/v1/memory/query/history/recent Get recent knowledge bases

Query Parameters

  • hours int optional — Lookback period (default: 24)
curl "http://localhost:8080/api/v1/memory/query/history/recent?hours=24"
GET /api/v1/memory/query/history/since Get knowledge bases since timestamp

Query Parameters

  • since string required — ISO-8601 timestamp
curl "http://localhost:8080/api/v1/memory/query/history/since?since=2025-01-01T00:00:00Z"

User Data

DELETE /api/v1/memory/query/user/{uid} Delete all user data (GDPR)

Deletes all knowledge base entries, contexts, and associated data for the specified user.

curl -X DELETE http://localhost:8080/api/v1/memory/query/user/user-1
⚠️ Irreversible:

This permanently removes all data. Use for GDPR "Right to be Forgotten" compliance.

Graph Endpoints

Traverse the knowledge graph — explore entity relationships, find connections, and discover patterns.

GET /api/v1/memory/query/graph/outgoing/{entityId} Get outgoing relations

What does this entity connect to? (e.g. Java → uses → GC)

curl http://localhost:8080/api/v1/memory/query/graph/outgoing/e1a2b3c4-...
GET /api/v1/memory/query/graph/incoming/{entityId} Get incoming relations

What connects to this entity? (e.g. SpringBoot → uses → Java)

curl http://localhost:8080/api/v1/memory/query/graph/incoming/e1a2b3c4-...
GET /api/v1/memory/query/graph/2hop/{entityId} Get 2-hop connections

"Friends of friends" — entities reachable in exactly 2 hops.

curl http://localhost:8080/api/v1/memory/query/graph/2hop/e1a2b3c4-...
GET /api/v1/memory/query/graph/top Get top/strongest relations

Query Parameters

  • limit int optional — Max results (default: 10)
curl "http://localhost:8080/api/v1/memory/query/graph/top?limit=10"
GET /api/v1/memory/query/graph/source/{sourceId} Get relations by source entity 
curl http://localhost:8080/api/v1/memory/query/graph/source/e1a2b3c4-...

Response — List<Relation>

[
  {
    "id": "r1...",
    "sourceEntity": { "id": "e1...", "name": "Java" },
    "targetEntity": { "id": "e2...", "name": "Garbage Collection" },
    "relationType": "uses",
    "edgeWeight": 3,
    "createdAt": "2025-01-15T10:00:02Z"
  }
]
GET /api/v1/memory/query/graph/target/{targetId} Get relations by target entity 
curl http://localhost:8080/api/v1/memory/query/graph/target/e2b3c4d5-...
GET /api/v1/memory/query/graph/type/{relationType} Get relations by type 
curl http://localhost:8080/api/v1/memory/query/graph/type/uses

Combines vector similarity search with graph-based context for richer results.

POST /api/v1/memory/query/hybrid Hybrid vector + graph search

Request Body — QueryRequest

Same schema as context search.

curl -X POST http://localhost:8080/api/v1/memory/query/hybrid \
  -H "Content-Type: application/json" \
  -d '{"query": "How does Java handle memory?", "limit": 10, "minRelevance": 0.6}'

Query Routing

Automatically classify intent and route the query to the correct retrieval pipeline.

POST /api/v1/memory/query/route Route query (PROMPT vs DOCUMENT)

Request Body — QueryRequest

Same schema as context search.

curl -X POST http://localhost:8080/api/v1/memory/query/route \
  -H "Content-Type: application/json" \
  -d '{"query": "Summarize the document about Java memory.", "limit": 10}'

Request Schemas

QueryRequest

Field Type Required Default Description
query string ✅ — Search text
limit int — 5 Max results
minRelevance double — 0.7 Min similarity score (0–1)
filters object — null Metadata filters

Response Schemas

QueryResponse

Field Type Description
query string Original query text
results SearchResult[] Array of results
processingTimeMs long Total processing time

SearchResult

Field Type Description
id UUID Result ID
content string Text chunk or entity name
score double Similarity score
type string CHUNK, ENTITY, or RELATION
metadata object Additional metadata (JSONB)

Enums

LLMApiProvider

Value Description
GEMINI Google Gemini
OPENAI OpenAI
ANTHROPIC Anthropic Claude
AZURE Azure OpenAI
OPENROUTER OpenRouter (multi-provider gateway)

ConverserRole

Value Description
USER Content from a human user
AGENT Content generated by AI
SYSTEM System-level content