API Reference

Ingest Documents

Build a knowledge graph from documents in one or more vaults.

Endpoint

POST /graph/v1/ingest

Concept

Provide one or more vault IDs, and we'll extract entities and relationships from all documents to build an interconnected knowledge graph. You can create vault-specific graphs or combine multiple vaults into a unified graph for cross-case analysis.

Use Cases

Single-Vault Graph:

• Build a graph for one case's documents
• All depositions, medical records, and evidence in one vault
• Graph shows relationships within the case

Multi-Vault Graph:

• Combine documents from multiple vaults
• Cross-case pattern analysis
• Find connections across related matters

What Gets Extracted

Entities:

• People (witnesses, parties, attorneys, experts)
• Organizations (companies, hospitals, government agencies)
• Locations (addresses, cities, accident sites)
• Dates and times (key events, timelines)
• Medical terms (diagnoses, procedures, medications)
• Legal concepts (statutes, claims, defenses)

Relationships:

• Employment (worked for, employed by)
• Testimony (testified about, stated that)
• Medical (treated, diagnosed, prescribed)
• Temporal (occurred before, happened after)
• Causal (caused by, resulted in)
• Legal (sued, represented, filed against)

Communities:

• Thematic clusters of related entities
• Example: "COVID Research Community" with Fauci, Daszak, Wuhan Institute, EcoHealth
• Hierarchical organization for multi-level analysis

Search Knowledge Graph

Query the knowledge graph using natural language questions.

Endpoint

POST /vault/{vault_id}/search

Request Body

{
  "query": "Your question in plain English",
  "method": "fast" | "global" | "local" | "graph" | "hybrid",
  "topK": 10
}

Parameters

Search Methods

Fast Search (method: "fast") ⚡ Recommended

Instant semantic search using S3 Vectors - no GraphRAG needed!

Perfect for:

• Any search query on vault documents
• Real-time applications and chatbots
• Works immediately after document upload
• Quick factual lookups

Returns (in < 500ms):

{
  "method": "fast",
  "query": "What medical treatments did the patient receive?",
  "response": "Found 5 relevant chunks across 2 documents.",
  "chunks": [
    {
      "text": "The patient received therapeutic massage therapy...",
      "object_id": "doc-123",
      "chunk_index": 5,
      "distance": 0.18
    }
  ],
  "sources": [
    {
      "id": "doc-123",
      "filename": "medical-records.pdf",
      "chunkCount": 42
    }
  ],
  "vault_id": "abc123"
}

How it works: Semantic embedding similarity using OpenAI text-embedding-3-small and S3 Vectors for sub-second searches.

Response time: < 500ms

Hybrid Search (method: "hybrid") 🎯 Best Accuracy

Combines semantic similarity (70%) with keyword matching (30%)

Perfect for:

• When you need both meaning AND exact keywords
• Legal searches where specific terms matter
• Best overall accuracy for most queries

Returns (in < 1 second):

{
  "method": "hybrid",
  "query": "post-operative care protocols",
  "response": "Found 5 relevant chunks (α=0.7 vector + β=0.3 BM25)",
  "chunks": [
    {
      "text": "The post-operative protocol...",
      "hybridScore": 0.92,
      "vectorScore": 0.89,
      "bm25Score": 1.0
    }
  ]
}

How it works: Gets vector candidates from S3, scores with BM25, normalizes and fuses both scores.

Response time: < 1 second

Entity Search (method: "entity")

GraphRAG entity-based search - requires GraphRAG indexing

Perfect for:

• "Who are the medical practitioners?" (entity names)
• "List all facilities" (entity extraction)
• After you've run GraphRAG indexing

Returns (in ~2-3 seconds):

How it works: Searches GraphRAG's extracted entities using keyword matching.

Response time: ~2-3 seconds Setup required: POST /vault/:id/graphrag/init

Global Search (method: "global")

Perfect for:

• "What are the main themes in this case?"
• "Summarize all medical treatments provided"
• "What patterns emerge across depositions?"

Returns (in ~15-20 seconds):

{
  "method": "global",
  "query": "What are the main medical facilities?",
  "response": "Based on the documents, the primary medical facilities mentioned include Salem Health Medical Center, Benchmark Physical Therapy, and Sacred Heart Riverbend...",
  "vault_id": "abc123"
}

How it works: Analyzes community summaries and high-level patterns across the entire knowledge graph for comprehensive analysis.

Response time: ~15-20 seconds

Local Search (method: "local")

Perfect for:

• "Who is connected to Dr. Smith?"
• "What medications were prescribed?"
• "Tell me about Salem Health"

Returns:

{
  "method": "local",
  "query": "Tell me about Salem Health",
  "response": "Salem Health Medical Center is mentioned as a primary care facility located at 665 Winter St SE, Salem, OR. Dr. Sarah Martinez provided treatment...",
  "sources": [
    {
      "id": "doc123",
      "filename": "salem-health-records.pdf",
      "entities": ["Salem Health", "Dr. Sarah Martinez"],
      "pageCount": 15
    }
  ],
  "vault_id": "abc123"
}

How it works: Focuses on specific entities and their immediate relationships in the graph.

Graph Search (method: "graph")

Perfect for:

• Finding all documents related to a specific entity
• Discovering connections between entities
• Relationship-based queries

Returns:

{
  "method": "graph",
  "query": "hospital",
  "results": [
    {
      "object": {
        "id": "doc123",
        "filename": "medical-record.pdf",
        "entities": [...]
      },
      "relationships": [...]
    }
  ],
  "total": 5,
  "vault_id": "abc123"
}

How it works: Traverses entity relationships to find connections.

Hybrid Search (method: "hybrid")

Combines entity matching with graph traversal for comprehensive results.

Query Examples

# Fast: Quick entity lookup (2-3 seconds)
curl -X POST https://api.case.dev/vault/{vault_id}/search \
  -H "Authorization: Bearer sk_case_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Who are the medical practitioners?",
    "method": "fast",
    "topK": 5
  }'

# Global: Holistic overview (15-20 seconds)
curl -X POST https://api.case.dev/vault/{vault_id}/search \
  -H "Authorization: Bearer sk_case_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the main medical facilities and providers?",
    "method": "global"
  }'

# Local: Specific entity details
curl -X POST https://api.case.dev/vault/{vault_id}/search \
  -H "Authorization: Bearer sk_case_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Tell me about physical therapy treatments",
    "method": "local"
  }'

# Graph: Relationship discovery
curl -X POST https://api.case.dev/vault/{vault_id}/search \
  -H "Authorization: Bearer sk_case_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ambulance",
    "method": "graph",
    "topK": 5
  }'

Source Attribution

Every response includes references to source documents, so you can verify and cite specific passages.

Get Graph Statistics

Get statistics about your vault's knowledge graph.

Endpoint

GET /vault/{vault_id}/graphrag/stats

Response

{
  "vault_id": "abc123",
  "status": "found",
  "entity_count": 157,
  "relationship_count": 342,
  "community_count": 12,
  "document_count": 25
}

Fields

Example

curl -X GET https://api.case.dev/vault/{vault_id}/graphrag/stats \
  -H "Authorization: Bearer sk_case_your_api_key"

Graph Storage

Per-Vault Graphs

Each vault can have its own knowledge graph, stored alongside documents and vectors.

Cross-Vault Graphs

Combine multiple vaults into unified graphs for:

• Multi-matter pattern analysis
• Firm-wide knowledge bases
• Related case analysis

Scalability

• Graphs scale to millions of entities and relationships
• Sub-second query performance
• Incremental updates as new documents are added