Manage

List your vaults

See all vaults in your organization.

Endpoint

GET /vault

curl https://api.case.dev/vault \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

casedev vault list

const { vaults } = await client.vault.list();

for (const vault of vaults) {
  console.log(`${vault.name}: ${vault.totalObjects} documents`);
}

result = client.vault.list()

for vault in result.vaults:
    print(f'{vault.name}: {vault.total_objects} documents')

result, _ := client.Vault.List(ctx)
for _, vault := range result.Vaults {
	fmt.Printf("%s: %d documents\n", vault.Name, vault.TotalObjects)
}

Response

{
  "vaults": [
    {
      "id": "vault_abc123",
      "name": "Smith v. Hospital 2024",
      "totalObjects": 47,
      "totalBytes": 125829120,
      "enableIndexing": true,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Get vault details

Get storage usage, document count, indexing status, and GraphRAG status for a specific vault.

Endpoint

GET /vault/:id

casedev vault retrieve --id $VAULT_ID

const vault = await client.vault.retrieve(vaultId);

console.log(`Name: ${vault.name}`);
console.log(`Documents: ${vault.totalObjects}`);
console.log(`Storage: ${(vault.totalBytes / 1024 / 1024).toFixed(2)} MB`);
console.log(`Indexing: ${vault.enableIndexing ? 'Enabled' : 'Storage-only'}`);
console.log(`GraphRAG: ${vault.enableGraph ? 'Enabled' : 'Disabled'}`);

vault = client.vault.retrieve(vault_id)

print(f'Name: {vault.name}')
print(f'Documents: {vault.total_objects}')
print(f'Storage: {vault.total_bytes / 1024 / 1024:.2f} MB')
print(f'Indexing: {"Enabled" if vault.enable_indexing else "Storage-only"}')
print(f'GraphRAG: {"Enabled" if vault.enable_graph else "Disabled"}')

vault, _ := client.Vault.Get(ctx, vaultID)
fmt.Printf("Name: %s\nDocuments: %d\n", vault.Name, vault.TotalObjects)

Field	Description
`enableIndexing`	Whether vector search is enabled. `false` for storage-only vaults
`enableGraph`	Whether GraphRAG knowledge graph is enabled (requires indexing)

Move vault to a group

Assign a vault to a group, move it between groups, or remove it from a group.

Endpoint

PATCH /vault/:id

curl -X PATCH "https://api.case.dev/vault/$VAULT_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"groupId": "grp_abc123"}'

# Move vault into a group
casedev vault update --id $VAULT_ID --group-id grp_abc123

# Remove vault from its group
casedev vault update --id $VAULT_ID --group-id null

// Move vault into a group
await client.vault.update(vaultId, { groupId: 'grp_abc123' });

// Remove vault from its group
await client.vault.update(vaultId, { groupId: null });

# Move vault into a group
client.vault.update(vault_id, group_id='grp_abc123')

# Remove vault from its group
client.vault.update(vault_id, group_id=None)

client.Vault.Update(ctx, vaultID, casedev.VaultUpdateParams{
	GroupID: casedev.F("grp_abc123"),
})

API keys scoped to specific groups cannot remove a vault from its group (groupId: null returns 403). See Groups → Scoped API keys for details.

List documents in a vault

See all files you’ve uploaded.

Endpoint

GET /vault/:id/objects

curl "https://api.case.dev/vault/$VAULT_ID/objects" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

casedev vault:objects list --id $VAULT_ID

const { objects } = await client.vault.objects.list(vaultId);

for (const obj of objects) {
  console.log(`${obj.filename} - ${obj.ingestionStatus}`);
}

result = client.vault.objects.list(vault_id)

for obj in result.objects:
    print(f'{obj.filename} - {obj.ingestion_status}')

result, _ := client.Vault.Objects.List(ctx, vaultID)
for _, obj := range result.Objects {
	fmt.Printf("%s - %s\n", obj.Filename, obj.IngestionStatus)
}

Response

{
  "objects": [
    {
      "id": "obj_xyz789",
      "filename": "deposition-johnson.pdf",
      "sizeBytes": 2458624,
      "ingestionStatus": "completed",
      "pageCount": 150,
      "createdAt": "2025-01-15T10:35:00Z"
    }
  ],
  "count": 1
}

Download a file

Get the original file you uploaded.

Endpoint

GET /vault/:vaultId/objects/:objectId/download

curl "https://api.case.dev/vault/$VAULT_ID/objects/$OBJECT_ID/download" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -o deposition.pdf

casedev vault:objects download --id $VAULT_ID --object-id $OBJECT_ID -o deposition.pdf

const response = await client.vault.objects.download(vaultId, objectId);
const buffer = await response.arrayBuffer();

fs.writeFileSync('deposition.pdf', Buffer.from(buffer));

content = client.vault.objects.download(vault_id, object_id)

with open('deposition.pdf', 'wb') as f:
    f.write(content)

content, _ := client.Vault.Objects.Download(ctx, vaultID, objectID)
// content is *http.Response with file body

Get extracted text

Get the OCR’d or transcribed text from a document.

Endpoint

GET /vault/:vaultId/objects/:objectId/text

curl "https://api.case.dev/vault/$VAULT_ID/objects/$OBJECT_ID/text" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

casedev vault:objects get-text --id $VAULT_ID --object-id $OBJECT_ID

const result = await client.vault.objects.getText(vaultId, objectId);

console.log(result.text);       // Full extracted text
console.log(result.pageCount);  // Number of pages

result = client.vault.objects.get_text(vault_id, object_id)

print(result.text)        # Full extracted text
print(result.page_count)  # Number of pages

result, _ := client.Vault.Objects.GetText(ctx, vaultID, objectID)
fmt.Println(result.Text)

Get text by page

Get page-level text from a processed PDF or plain text object. Use start and end to request an inclusive 1-indexed page range, up to 500 pages per request.

Endpoint

GET /vault/:vaultId/objects/:objectId/pages

cURL

curl "https://api.case.dev/vault/$VAULT_ID/objects/$OBJECT_ID/pages?start=3&end=5" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Response

{
  "pages": [
    { "page": 3, "text": "Q. Please state your name for the record..." },
    { "page": 4, "text": "A. My name is Jane Doe..." }
  ],
  "metadata": {
    "source": "ocr",
    "page_count": 42,
    "returned_pages": 2
  }
}

PDFs must finish ingestion before pages are available. metadata.source is ocr for PDF OCR text and txt for plain text fallback.

Update a document

Update a document’s filename, folder path, or custom metadata. Use this endpoint to rename files, organize them into virtual folders, or attach custom key-value metadata for filtering and categorization.

Endpoint

PATCH /vault/:vaultId/objects/:objectId

Update custom metadata

Attach custom key-value pairs to documents for filtering, categorization, or integration with your systems. Metadata is merged with existing values—only the fields you specify are updated.

# Add custom metadata to a document
curl -X PATCH "https://api.case.dev/vault/$VAULT_ID/objects/$OBJECT_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "category": "legal_filing",
      "tags": ["contract", "employment", "2024"],
      "priority": "high",
      "client_id": "client_12345"
    }
  }'

casedev vault:objects update --id $VAULT_ID --object-id $OBJECT_ID \
  --metadata '{"category": "legal_filing", "priority": "high"}'

// Add custom metadata to a document
await client.vault.objects.update(vaultId, objectId, {
  metadata: {
    category: 'legal_filing',
    tags: ['contract', 'employment', '2024'],
    priority: 'high',
    client_id: 'client_12345'
  }
});

# Add custom metadata to a document
client.vault.objects.update(vault_id, object_id,
    metadata={
        'category': 'legal_filing',
        'tags': ['contract', 'employment', '2024'],
        'priority': 'high',
        'client_id': 'client_12345'
    }
)

client.Vault.Objects.Update(ctx, vaultID, objectID, casedev.VaultObjectUpdateParams{
	Metadata: casedev.F(map[string]interface{}{
		"category":  "legal_filing",
		"priority":  "high",
		"client_id": "client_12345",
	}),
})

Metadata is merged, not replaced. When you update metadata, your new fields are merged with existing metadata. To remove a field, set it to null.

Rename or move a document

# Rename a file
curl -X PATCH "https://api.case.dev/vault/$VAULT_ID/objects/$OBJECT_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "deposition-smith-final.pdf"}'

# Move to a folder
curl -X PATCH "https://api.case.dev/vault/$VAULT_ID/objects/$OBJECT_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/Discovery/Depositions"}'

# Rename a file
casedev vault:objects update --id $VAULT_ID --object-id $OBJECT_ID \
  --filename "deposition-smith-final.pdf"

# Move to a folder
casedev vault:objects update --id $VAULT_ID --object-id $OBJECT_ID \
  --path "/Discovery/Depositions"

// Rename a file
await client.vault.objects.update(vaultId, objectId, {
  filename: 'deposition-smith-final.pdf'
});

// Move to a folder
await client.vault.objects.update(vaultId, objectId, {
  path: '/Discovery/Depositions'
});

// Rename, move, and add metadata in one call
await client.vault.objects.update(vaultId, objectId, {
  filename: 'deposition-smith-2024.pdf',
  path: '/Discovery/Depositions',
  metadata: { witness: 'John Smith', deposition_date: '2024-01-15' }
});

# Rename a file
client.vault.objects.update(vault_id, object_id,
    filename='deposition-smith-final.pdf'
)

# Move to a folder
client.vault.objects.update(vault_id, object_id,
    path='/Discovery/Depositions'
)

# Rename, move, and add metadata in one call
client.vault.objects.update(vault_id, object_id,
    filename='deposition-smith-2024.pdf',
    path='/Discovery/Depositions',
    metadata={'witness': 'John Smith', 'deposition_date': '2024-01-15'}
)

// Rename a file
client.Vault.Objects.Update(ctx, vaultID, objectID, casedev.VaultObjectUpdateParams{
	Filename: casedev.F("deposition-smith-final.pdf"),
})

// Move to a folder
client.Vault.Objects.Update(ctx, vaultID, objectID, casedev.VaultObjectUpdateParams{
	Path: casedev.F("/Discovery/Depositions"),
})

Request body

Field	Type	Description
`filename`	string	New display name for the document
`path`	string	Virtual folder path (e.g., `/Discovery/Depositions`)
`metadata`	object	Custom key-value pairs to merge with existing metadata

Response

{
  "id": "obj_xyz789",
  "vaultId": "vault_abc123",
  "filename": "deposition-smith-2024.pdf",
  "path": "/Discovery/Depositions",
  "contentType": "application/pdf",
  "sizeBytes": 2458624,
  "ingestionStatus": "completed",
  "metadata": {
    "path": "/Discovery/Depositions",
    "witness": "John Smith",
    "deposition_date": "2024-01-15",
    "category": "legal_filing"
  },
  "updatedAt": "2025-01-15T10:35:00Z"
}

Virtual folders. The path field creates a virtual folder hierarchy stored in metadata. Use this to organize documents without affecting their storage location. Build folder trees by grouping objects with the same path prefix.

Create a merged PDF

POST /vault/:vaultId/objects/merge creates a new PDF from one or more ordered PDF objects. It returns 202 immediately; listen for vault.object.merge.completed or vault.object.merge.failed. Source objects are unchanged.

cURL

curl -X POST "https://api.case.dev/vault/$VAULT_ID/objects/merge" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: matter-123-production-1" \
  -d '{
    "sourceObjectIds": ["source_1", "source_2"],
    "filename": "production.pdf",
    "sourceRendition": "searchable_pdf",
    "clientReference": "matter-123-production-1",
    "bates": { "prefix": "CASE-", "start": 1, "padTo": 6 }
  }'

202 Response

{
  "objectId": "merge_abc123",
  "workflowId": "modal_merge_abc123",
  "status": "processing",
  "clientReference": "matter-123-production-1"
}

Every source must have completed ingestion. Missing searchable renditions are generated on demand (via OCR) before combining; the operation does not fall back to the original file. Set sourceRendition to original to merge stored PDFs without generating OCR renditions; the output is searchable only if those originals already contain text. Requests support 1–20 unique sources, up to 5,000 pages and 1 GiB total. Bates numbering is continuous across every output page. Reusing an idempotency key with different inputs returns 409.

Append PDF objects onto an existing object

Append up to 20 PDF vault objects to the end of an existing PDF object. The target is overwritten in place: sizeBytes, pageCount, and checksum change, while id, filename, and ingestionStatus stay the same. Appended pages are not searchable.

Endpoint

POST /vault/:vaultId/objects/:objectId/append

cURL

curl -X POST "https://api.case.dev/vault/$VAULT_ID/objects/$OBJECT_ID/append" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appendObjectIds": ["obj_exhibit_a", "obj_exhibit_b"],
    "rewriteLinks": true,
    "backLinks": true,
    "backLinksText": "Return to summary"
  }'

Request body

Field	Type	Description
`appendObjectIds`	string[]	Required. PDF object IDs to append, in order. Must be unique and must not include the target object.
`rewriteLinks`	boolean	Optional. Defaults to `false`. Rewrites matching target-PDF links into internal PDF jumps.
`backLinks`	boolean	Optional. Defaults to `false`. Adds internal back links to appended pages.
`backLinksText`	string	Optional. Defaults to `Back to Summary`. Used only when `backLinks` is true.

All inputs must be PDFs. The append operation processes source objects sequentially to reduce peak memory use, but very large merges can still fail if the function runtime runs out of memory while serializing the merged PDF. The request fails while the target object is processing or deleting. When rewriteLinks is true, a link is rewritten only if it contains exactly one appendObjectIds value as a full decoded query parameter value or full decoded path segment, plus a valid page or pageNumber. Substring matches are ignored.

https://example.test/share?object_id=obj_exhibit_a&page=3
https://example.test/s/obj_exhibit_a?page=3

Back links use standard internal PDF destinations, not PDF JavaScript. Pages reached by a rewritten link point back to the citing target page; other appended pages point back to the first target page.

Delete a document

Remove a single file and all its search data.

Endpoint

DELETE /vault/:vaultId/objects/:objectId

curl -X DELETE "https://api.case.dev/vault/$VAULT_ID/objects/$OBJECT_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

casedev vault:objects delete --id $VAULT_ID --object-id $OBJECT_ID

await client.vault.objects.delete(vaultId, objectId);

client.vault.objects.delete(vault_id, object_id)

client.Vault.Objects.Delete(ctx, vaultID, objectID, casedev.VaultObjectDeleteParams{})

Force delete stuck documents

If a document gets stuck in processing status (e.g., due to an OCR timeout), you can force delete it:

# Force delete a stuck document
curl -X DELETE "https://api.case.dev/vault/$VAULT_ID/objects/$OBJECT_ID?force=true" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

casedev vault:objects delete --id $VAULT_ID --object-id $OBJECT_ID --force

// Force delete a stuck document
await client.vault.objects.delete(vaultId, objectId, { force: true });

# Force delete a stuck document
client.vault.objects.delete(vault_id, object_id, force=True)

client.Vault.Objects.Delete(ctx, vaultID, objectID, casedev.VaultObjectDeleteParams{
	Force: casedev.F(casedev.VaultObjectDeleteParamsForceTrue),
})

When to use force delete. Use force=true only when a document is stuck in “processing” status and won’t complete. This can happen in rare cases like OCR timeouts. The force option bypasses the safety check that prevents deletion during active ingestion.

Permanent. This deletes the file, extracted text, and all search vectors. Cannot be undone.

Delete a vault

Remove an entire vault and everything in it.

Endpoint

DELETE /vault/:id

curl -X DELETE "https://api.case.dev/vault/$VAULT_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

casedev vault delete --id $VAULT_ID

await client.vault.delete(vaultId);

client.vault.delete(vault_id)

client.Vault.Delete(ctx, vaultID, casedev.VaultDeleteParams{})

For large vaults (100+ documents), use async deletion:

curl -X DELETE "https://api.case.dev/vault/$VAULT_ID?async=true" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

casedev vault delete --id $VAULT_ID

await client.vault.delete(vaultId, { async: true });

client.vault.delete(vault_id, async_=True)

client.Vault.Delete(ctx, vaultID, casedev.VaultDeleteParams{
	Async: casedev.F(true),
})

Permanent. This deletes all documents, search indexes, knowledge graphs, and storage. Cannot be undone.

Get Started

Platform

Resources

List your vaults

Get vault details

Move vault to a group

List documents in a vault

Download a file

Get extracted text

Get text by page

Update a document

Update custom metadata

Rename or move a document

Request body

Create a merged PDF

Append PDF objects onto an existing object

Request body

Delete a document

Force delete stuck documents

Delete a vault

​List your vaults

​Get vault details

​Move vault to a group

​List documents in a vault

​Download a file

​Get extracted text

​Get text by page

​Update a document

​Update custom metadata

​Rename or move a document

​Request body

​Create a merged PDF

​Append PDF objects onto an existing object

​Request body

​Delete a document

​Force delete stuck documents

​Delete a vault

List your vaults

Get vault details

Move vault to a group

List documents in a vault

Download a file

Get extracted text

Get text by page

Update a document

Update custom metadata

Rename or move a document

Request body

Create a merged PDF

Append PDF objects onto an existing object

Request body

Delete a document

Force delete stuck documents

Delete a vault