API Reference
Vault API endpoints and operations
Create a Vault
Create a new vault to store related documents.
Endpoint
/vaultcurl -X POST https://api.case.dev/vault \
-H "Authorization: Bearer sk_case_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Smith v. Hospital Case 2024",
"description": "All discovery, depositions, and medical records for the Smith case"
}'Example Request
Example Response
What Happens Behind the Scenes
When you create a vault, we automatically:
- Create two S3 buckets:
- Files bucket: Stores your actual documents
- Vector bucket: Stores embeddings for semantic search
- Set up encryption: KMS encryption on both buckets
- Create vector index: 1536-dimension index (OpenAI embeddings)
- Configure for semantic search: Cosine similarity, optimized for text
Request Parameters
Required:
name(string): Vault name (e.g., case name, matter number)
Optional:
description(string): What's stored in this vault
Response Fields
id: Vault ID - use this in all subsequent requestsfilesBucket: S3 bucket name for documentsvectorBucket: S3 bucket name for embeddingsindexName: Vector index name (always "embeddings")region: AWS region where vault is storedcreatedAt: When the vault was created
Get Vault Information
Retrieve detailed information about a specific vault including bucket names, configuration, and usage statistics.
Endpoint
/vault/sytp1b5f5j1yuj7uffzzxgw6curl -X GET https://api.case.dev/vault/sytp1b5f5j1yuj7uffzzxgw6 \
-H "Authorization: Bearer sk_case_your_api_key_here" \
-H "Content-Type: application/json"Example Request
Example Response
Response Fields
Basic Information:
id: Unique vault identifiername: Vault name (your case or matter name)description: Vault description
Storage Configuration:
filesBucket: S3 bucket storing actual documentsvectorBucket: S3 bucket storing embeddings for semantic searchindexName: Vector index name (always "embeddings")region: AWS region where vault is storedkmsKeyId: KMS key ARN used for encryption
Processing Configuration:
chunkStrategy: How documents are split for processingmethod: Chunking algorithm (semanticrespects paragraphs/sentences)chunkSize: Target chunk size in tokens (512 tokens ≈ 380 words)overlap: Token overlap between chunks for context preservationminChunkSize: Minimum chunk size (prevents tiny fragments)
Features:
enableGraph: Whether knowledge graph extraction is enabled
Usage Statistics:
totalObjects: Number of documents stored in vaulttotalBytes: Total storage used (in bytes)totalVectors: Total number of embeddings generated
Metadata:
metadata: Additional vault configuration and settingscreatedAt: When vault was createdupdatedAt: Last modification time
Use Cases
Check Storage Usage:
Verify Configuration:
Get Bucket Names for Direct S3 Access:
Upload Document
Get a presigned upload URL to securely upload a document to your vault.
Endpoint
/vault/sytp1b5f5j1yuj7uffzzxgw6/uploadcurl -X POST https://api.case.dev/vault/sytp1b5f5j1yuj7uffzzxgw6/upload \
-H "Authorization: Bearer sk_case_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"filename": "deposition-transcript.pdf",
"contentType": "application/pdf",
"metadata": {
"case_id": "2024-1234",
"document_type": "deposition",
"witness": "Dr. Sarah Johnson",
"date": "2024-11-04"
}
}'Example Request
Example Response
Request Parameters
Required:
filename(string): Name of the filecontentType(string): MIME type- PDF:
application/pdf - Word:
application/vnd.openxmlformats-officedocument.wordprocessingml.document - Text:
text/plain - Image:
image/jpeg,image/png
- PDF:
Optional:
metadata(object): Custom metadata about this document- Searchable key-value pairs
- Add case IDs, dates, parties, document types, etc.
- Used to filter search results later
How to Upload
Step 1: Get the presigned upload URL (above)
Step 2: Upload your file using PUT request:
Step 3: The file is now stored! Proceed to ingestion for semantic search.
Complete Upload Example
List Vault Objects
See all documents stored in a vault.
Endpoint
/vault/sytp1b5f5j1yuj7uffzzxgw6/objectscurl -X GET https://api.case.dev/vault/sytp1b5f5j1yuj7uffzzxgw6/objects \
-H "Authorization: Bearer sk_case_your_api_key_here" \
-H "Content-Type: application/json"Example Request
Example Response
Response Fields
Per Object:
id: Object ID (use for downloads/ingestion)filename: Original filenamecontentType: MIME typesizeBytes: File size in bytesingestionStatus: Search readinesspending: Not yet processedprocessing: OCR/embedding in progresscompleted: Fully searchablefailed: Processing failed
pageCount: Number of pages (PDFs only)textLength: Characters of extracted textchunkCount: Document split into chunksvectorCount: Number of embeddings createdmetadata: Your custom metadatatags: Auto-detected or manual tags
Download Document
Get a presigned URL to download a specific document from your vault.
Endpoint
/vault/sytp1b5f5j1yuj7uffzzxgw6/objects/i5ar122d3h11a1802a3mogobcurl -X GET https://api.case.dev/vault/sytp1b5f5j1yuj7uffzzxgw6/objects/i5ar122d3h11a1802a3mogob \
-H "Authorization: Bearer sk_case_your_api_key_here" \
-H "Content-Type: application/json"Example Request
Example Response
Download the File
Use the downloadUrl directly:
Note: Download URLs expire in 1 hour. Generate a new one if expired.
Generate Custom Presigned URL
Generate presigned URLs for S3 operations with custom expiry times and operation types. This gives you more control than the basic download endpoint.
Endpoint
/vault/sytp1b5f5j1yuj7uffzzxgw6/objects/i5ar122d3h11a1802a3mogob/presigned-urlcurl -X POST https://api.case.dev/vault/sytp1b5f5j1yuj7uffzzxgw6/objects/i5ar122d3h11a1802a3mogob/presigned-url \
-H "Authorization: Bearer sk_case_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"operation": "GET",
"expiresIn": 7200
}'Example Request
Example Response
Request Parameters
Optional:
operation(string): S3 operation type (default:GET)GET- Download/read the filePUT- Upload/replace the fileDELETE- Delete the file from S3HEAD- Get file metadata without downloading
expiresIn(number): URL expiry in seconds (default: 3600)- Minimum: 60 seconds (1 minute)
- Maximum: 604800 seconds (7 days)
contentType(string): Content type for PUT operations- Only needed for
PUToperations - Defaults to the object's stored content type
- Only needed for
Use Cases
Long-lived Download Links (7 days):
Replace/Update a Document:
Then upload using the presigned URL:
Delete a Document:
Check File Metadata:
Security Notes
- Presigned URLs bypass normal authentication - anyone with the URL can perform the operation
- Choose appropriate expiry times based on your security requirements
- DELETE operations are permanent - the file is removed from S3 (database record remains)
- PUT operations will replace existing files completely
Trigger Document Ingestion
Process a document for semantic search. This extracts text (via OCR if needed), chunks it, generates embeddings, and stores vectors for fast similarity search.
Endpoint
/vault/sytp1b5f5j1yuj7uffzzxgw6/ingest/i5ar122d3h11a1802a3mogobcurl -X POST https://api.case.dev/vault/sytp1b5f5j1yuj7uffzzxgw6/ingest/i5ar122d3h11a1802a3mogob \
-H "Authorization: Bearer sk_case_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{}'Example Request
Example Response
What Happens During Ingestion
This kicks off a Vercel Workflow that:
- Submits document to Vision OCR API
- Extracts all text
- Preserves layout and structure
- Returns page count and text
- Chunks the text (when OCR completes)
- Semantic chunking (512 tokens per chunk)
- 50 token overlap between chunks
- Preserves context across boundaries
- Generates embeddings
- Uses OpenAI text-embedding-3-small
- 1536 dimensions per chunk
- Stores in vector bucket
- Updates object metadata
- Sets
ingestionStatustocompleted - Records
pageCount,textLength,chunkCount,vectorCount
- Sets
Processing Times
| Document Type | Pages | OCR Time | Total Time |
|---|---|---|---|
| Clean PDF | 10 | 0s (no OCR needed) | ~10s |
| Scanned PDF | 50 | ~2 min | ~2.5 min |
| Large discovery | 300 | ~12 min | ~13 min |
The workflow runs asynchronously - you get an immediate response, processing happens in the background.
Semantic Search
Search your vault documents using natural language. Multiple search methods available based on your needs.
Endpoint
/vault/sytp1b5f5j1yuj7uffzzxgw6/searchcurl -X POST https://api.case.dev/vault/sytp1b5f5j1yuj7uffzzxgw6/search \
-H "Authorization: Bearer sk_case_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"query": "testimony about post-operative care and monitoring",
"method": "hybrid",
"topK": 10
}'Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Your search query in natural language |
method | string | Yes | Search method: fast, hybrid, entity, global, or local |
topK | number | No | Number of results to return (default: 10) |
Search Methods
Fast Search (method: "fast") ⚡ Recommended
Instant semantic similarity search using S3 Vectors
- Speed: < 500ms
- Setup: Works immediately after document upload (no GraphRAG needed!)
- How: Semantic embedding similarity using OpenAI text-embedding-3-small
- Best for: Quick searches, real-time applications, chatbots
Response:
Hybrid Search (method: "hybrid") 🎯 Best Accuracy
Combines semantic similarity (70%) with keyword matching (30%) using BM25
- Speed: < 1 second
- Setup: Works immediately after document upload (no GraphRAG needed!)
- How: S3 Vectors similarity + BM25 keyword scoring with normalized fusion
- Best for: When you need both semantic understanding AND exact keyword matches
Response:
How hybrid scoring works:
- Get 2x candidates using vector similarity
- Score candidates with BM25 keyword algorithm
- Normalize both scores to 0-1 range
- Combine:
0.7 * vectorScore + 0.3 * bm25Score - Return top K by hybrid score
Entity Search (method: "entity")
GraphRAG entity-based keyword search
- Speed: 2-3 seconds
- Setup: Requires
POST /vault/:id/graphrag/initfirst - How: Keyword matching on GraphRAG extracted entity names/descriptions
- Best for: Finding specific entities, people, organizations
Global Search (method: "global")
Comprehensive knowledge graph analysis
- Speed: 15-20 seconds
- Setup: Requires GraphRAG indexing
- How: Analyzes community summaries across entire graph
- Best for: "What are the main themes?", "Summarize key points"
Local Search (method: "local")
Entity-focused graph search
- Speed: 5-10 seconds
- Setup: Requires GraphRAG indexing
- How: Focuses on specific entities and their relationships
- Best for: "Tell me about X", "Who is connected to Y?"
Vault Architecture
How It Works
Chunking Strategy
Documents are split intelligently:
- Chunk size: 512 tokens (~380 words)
- Overlap: 50 tokens to preserve context
- Min chunk: 100 tokens (no tiny fragments)
- Method: Semantic (respects sentences/paragraphs)
This means:
- ~2 chunks per page (standard deposition)
- 150-page deposition = ~300 chunks
- Each chunk is searchable independently