Search

This is why vaults exist. Ask questions in plain English and get relevant passages—even when documents use different words than your query.

Basic search

Endpoint

POST /vault/:id/search

curl -X POST "https://api.case.dev/vault/$VAULT_ID/search" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What did the witness say about post-operative care?"}'

casedev vault search \
  --id $VAULT_ID \
  --query "What did the witness say about post-operative care?"

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}`);
  }
  // Media timing for transcript navigation (undefined if unavailable)
  if (chunk.start_ms !== undefined) {
    console.log(`Media range: ${chunk.start_ms}ms-${chunk.end_ms}ms`);
  }
}

import casedev

client = casedev.Casedev(api_key='sk_case_YOUR_API_KEY')

results = client.vault.search(vault_id,
    query='What did the witness say about post-operative care?'
)

for chunk in results.chunks:
    print(chunk.text)
    # Page info for citation navigation (None if unavailable)
    if chunk.page_start:
        page_range = f'p. {chunk.page_start}' if chunk.page_start == chunk.page_end else f'pp. {chunk.page_start}-{chunk.page_end}'
        print(f'Document: {chunk.object_id}, {page_range}')
    # Media timing for transcript navigation (None if unavailable)
    if chunk.start_ms is not None:
        print(f'Media range: {chunk.start_ms}ms-{chunk.end_ms}ms')

results, _ := client.Vault.Search(ctx, vaultID, casedev.VaultSearchParams{
	Query: casedev.F("What did the witness say about post-operative care?"),
})
for _, chunk := range results.Chunks {
	fmt.Println(chunk.Text)
}

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,
      "word_start_index": 5544,
      "word_end_index": 6055,
      "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.

For media-backed transcripts, search chunks can include source audio/video timing when real word timing is available:

Media transcript search chunk

{
  "text": "Good morning. Could you please state your full name for the record?...",
  "object_id": "obj_audio123",
  "chunk_index": 0,
  "page_start": null,
  "page_end": null,
  "word_start_index": 0,
  "word_end_index": 181,
  "start_ms": 100,
  "end_ms": 75291,
  "distance": 0.77
}

Media transcript timing: For audio/video-backed transcript chunks, start_ms and end_ms are the source media timestamps for the first and last word in the chunk. These fields are returned only when real word timing exists and are omitted for normal documents and text-only transcripts.

Understanding search methods

Vaults support different search methods for different needs:

Method	What it does	Best for
`hybrid`	Combines meaning + keywords	Default. Best for most queries.
`fast`	Meaning only (vector search)	Speed-critical applications
`vector`	Legacy fallback: lists matching documents without ranking	Kept for compatibility. Prefer `hybrid` or `fast`.

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).

casedev vault search \
  --id $VAULT_ID \
  --query "timeline of events" \
  --method hybrid

const results = await client.vault.search(vaultId, {
  query: 'timeline of events',
  method: 'hybrid'  // This is the default
});

results = client.vault.search(vault_id,
    query='timeline of events',
    method='hybrid'  # This is the default
)

results, _ := client.Vault.Search(ctx, vaultID, casedev.VaultSearchParams{
    Query:  casedev.F("timeline of events"),
    Method: casedev.F(casedev.VaultSearchParamsMethodHybrid),
})

Fast search

Pure vector similarity—faster but misses exact keyword matches.

casedev vault search \
  --id $VAULT_ID \
  --query "medical negligence" \
  --method fast

const results = await client.vault.search(vaultId, {
  query: 'medical negligence',
  method: 'fast'
});

results = client.vault.search(vault_id,
    query='medical negligence',
    method='fast'
)

results, _ := client.Vault.Search(ctx, vaultID, casedev.VaultSearchParams{
    Query:  casedev.F("medical negligence"),
    Method: casedev.F(casedev.VaultSearchParamsMethodFast),
})

When to use what

Your question	Method	Why
”Find testimony about medication”	`hybrid`	Finding specific passages; matches meaning and exact keywords
”What did Dr. Smith say about X?”	`hybrid`	Names and terms benefit from keyword matching
Speed-critical search	`fast`	Pure vector, faster

Filtering results

Narrow results by metadata you added during upload:

casedev vault search \
  --id $VAULT_ID \
  --query "post-operative complications" \
  --filters '{"document_type": "medical_record", "date": {"after": "2024-01-01"}}'

const results = await client.vault.search(vaultId, {
  query: 'post-operative complications',
  filters: {
    document_type: 'medical_record',
    date: { after: '2024-01-01' }
  }
});

results = client.vault.search(vault_id,
    query='post-operative complications',
    filters={
        'document_type': 'medical_record',
        'date': {'after': '2024-01-01'}
    }
)

results, _ := client.Vault.Search(ctx, vaultID, casedev.VaultSearchParams{
    Query: casedev.F("post-operative complications"),
    Filters: casedev.F(map[string]interface{}{
        "document_type": "medical_record",
        "date":          map[string]interface{}{"after": "2024-01-01"},
    }),
})

Parameters

Parameter	Type	Default	Description
`query`	string	required	Your question in natural language
`method`	string	`hybrid`	`hybrid`, `fast`, or the legacy `vector` fallback
`topK`	number	10	How many results to return
`filters`	object	`{}`	Filter by metadata fields

Response fields

Each chunk in the response includes:

Field	Type	Description
`text`	string	Preview of the chunk text (up to 500 characters)
`object_id`	string	ID of the source document
`chunk_index`	number	Position of this chunk in the document (0-based)
`page_start`	number \| null	PDF page where chunk begins (1-indexed)
`page_end`	number \| null	PDF page where chunk ends (1-indexed)
`distance`	number	Vector 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:

# Response includes score for each chunk
curl -X POST "https://api.case.dev/vault/$VAULT_ID/search" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "your search query"}'
# Each chunk in response has "score": 0.0–1.0

# CLI outputs scores in the results table automatically
casedev vault search \
  --id $VAULT_ID \
  --query "your search query"

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
}

for chunk in results.chunks:
    print(f'{chunk.filename}: {chunk.score}')
    # deposition.pdf: 0.92  ← Very relevant
    # contract.pdf: 0.71    ← Somewhat relevant
    # memo.pdf: 0.45        ← Weakly relevant

for _, chunk := range results.Chunks {
    fmt.Printf("%s: %.2f\n", 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.

Get Started

Platform

Resources

Basic search

Understanding search methods

Hybrid search (default)

Fast search

When to use what

Filtering results

Parameters

Response fields

Understanding scores

​Basic search

​Understanding search methods

​Hybrid search (default)

​Fast search

​When to use what

​Filtering results

​Parameters

​Response fields

​Understanding scores

Basic search

Understanding search methods

Hybrid search (default)

Fast search

When to use what

Filtering results

Parameters

Response fields

Understanding scores