Skip to main content
This is why vaults exist. Ask questions in plain English and get relevant passages—even when documents use different words than your query.
Endpoint
POST /vault/:id/search

import Casedev from 'casedev';

const client = new Casedev({ apiKey: 'sk_case_YOUR_API_KEY' });

const results = await client.vault.search(vaultId, {
  query: 'What did the witness say about post-operative care?'
});

for (const chunk of results.chunks) {
  console.log(chunk.text);
  // Page info for citation navigation (null if unavailable)
  if (chunk.page_start) {
    const pageRange = chunk.page_start === chunk.page_end 
      ? `p. ${chunk.page_start}` 
      : `pp. ${chunk.page_start}-${chunk.page_end}`;
    console.log(`Document: ${chunk.object_id}, ${pageRange}`);
  }
}
Response
{
  "chunks": [
    {
      "text": "Q: Can you describe the monitoring protocol?\nA: Standard protocol requires vital signs every 15 minutes for the first hour...",
      "object_id": "obj_abc123",
      "chunk_index": 12,
      "page_start": 45,
      "page_end": 46,
      "distance": 0.11
    }
  ],
  "sources": [
    {
      "id": "obj_abc123",
      "filename": "deposition-johnson.pdf",
      "pageCount": 120
    }
  ]
}
Page citations: The page_start and page_end fields tell you exactly which PDF pages the chunk spans. This enables “jump to page” functionality in document viewers. For documents without page information (TXT, DOCX, or older documents), these fields will be null.

​
Understanding search methods

Vaults support different search methods for different needs:
MethodWhat it doesBest for
hybridCombines meaning + keywordsDefault. Best for most queries.
fastMeaning only (vector search)Speed-critical applications
localGraphRAG entity search”What did [person] say about [topic]?”
globalGraphRAG corpus-wide”What are the main themes across all documents?”

​
Hybrid search (default)

Combines semantic understanding with keyword matching. If you search “timeline” it will find documents that say “timeline” AND documents that say “schedule” (similar meaning).
TypeScript
const results = await client.vault.search(vaultId, {
  query: 'timeline of events',
  method: 'hybrid'  // This is the default
});
Pure vector similarity—faster but misses exact keyword matches.
TypeScript
const results = await client.vault.search(vaultId, {
  query: 'medical negligence',
  method: 'fast'
});

​
GraphRAG: When basic search isn’t enough

Basic search finds individual passages. But some questions need to understand your entire document collection:
  • “What are the main contradictions between witnesses?”
  • “Summarize all the expert testimony”
  • “What did Dr. Johnson say about the defendant?”
This is what GraphRAG does. It builds a knowledge graph—a map of people, organizations, concepts, and how they connect—across all your documents.

​
How GraphRAG works

┌─────────────────────────────────────────────────────────────────┐
│  STANDARD RAG                                                    │
│                                                                  │
│  Query: "What are the main issues?"                             │
│                    ↓                                             │
│  Finds similar chunks → Returns them                            │
│                    ↓                                             │
│  Problem: Random chunks, no synthesis                           │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│  GRAPHRAG                                                        │
│                                                                  │
│  Step 1: Build a knowledge graph                                │
│    • Extract entities (people, orgs, concepts)                  │
│    • Map relationships between them                             │
│    • Cluster into "communities" (themes)                        │
│                                                                  │
│  Step 2: Query the graph                                        │
│    • "Global" queries → summarize communities                   │
│    • "Local" queries → find specific entity info               │
│                    ↓                                             │
│  Result: Synthesized answer across all documents                │
└─────────────────────────────────────────────────────────────────┘

​
Enable GraphRAG

GraphRAG requires a one-time initialization to build the knowledge graph:
Endpoint
POST /vault/:id/graphrag/init

// Initialize the knowledge graph (one-time)
await client.vault.graphrag.init(vaultId);

// Check progress
const stats = await client.vault.graphrag.stats(vaultId);
console.log(`Entities: ${stats.entities}`);
console.log(`Relationships: ${stats.relationships}`);
console.log(`Status: ${stats.status}`);
One-time setup. You only initialize GraphRAG once. New documents are automatically added to the graph when ingested.

​
Global search: Corpus-wide questions

Ask questions that span your entire document collection:
TypeScript
const results = await client.vault.search(vaultId, {
  query: 'What are the key disputed facts in this case?',
  method: 'global'
});

// Returns a synthesized answer, not just chunks
console.log(results.response);
Good for:
  • “What are the main themes across all depositions?”
  • “Summarize the expert witness testimony”
  • “What patterns appear in these contracts?”

​
Local search: Entity-focused questions

Ask about specific people, organizations, or concepts:
TypeScript
const results = await client.vault.search(vaultId, {
  query: 'What did Dr. Johnson testify about the monitoring protocol?',
  method: 'local'
});

console.log(results.response);
Good for:
  • “What did [person] say about [topic]?”
  • “What is [company]‘s position on [issue]?”
  • “Find everything about [entity]“

​
When to use what

Your questionMethodWhy
”Find testimony about medication”hybridFinding specific passages
”What are the main themes?”globalNeeds corpus-wide synthesis
”What did Dr. Smith say about X?”localEntity-focused
”Contradictions between witnesses?”globalCross-document analysis
Speed-critical searchfastPure vector, faster

​
Filtering results

Narrow results by metadata you added during upload:
TypeScript
const results = await client.vault.search(vaultId, {
  query: 'post-operative complications',
  filters: {
    document_type: 'medical_record',
    date: { after: '2024-01-01' }
  }
});

​
Parameters

ParameterTypeDefaultDescription
querystringrequiredYour question in natural language
methodstringhybridhybrid, fast, local, or global
topKnumber10How many results to return
filtersobject{}Filter by metadata fields

​
Response fields

Each chunk in the response includes:
FieldTypeDescription
textstringPreview of the chunk text (up to 500 characters)
object_idstringID of the source document
chunk_indexnumberPosition of this chunk in the document (0-based)
page_startnumber | nullPDF page where chunk begins (1-indexed)
page_endnumber | nullPDF page where chunk ends (1-indexed)
distancenumberVector similarity distance (lower = more similar)
Page fields may be null for: non-PDF documents (TXT, DOCX), documents ingested before page tracking was added, or OCR results that don’t include page boundaries.

​
Understanding scores

Each result has a relevance score from 0 to 1:
TypeScript
for (const chunk of results.chunks) {
  console.log(`${chunk.filename}: ${chunk.score}`);
  // deposition.pdf: 0.92  ← Very relevant
  // contract.pdf: 0.71    ← Somewhat relevant
  // memo.pdf: 0.45        ← Weakly relevant
}
Higher score = more relevant to your query.