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, and indexing 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'}`);

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"}')

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

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 PDF vault objects to the end of an existing PDF object. Sync mode accepts up to 20 objects per request; async mode accepts up to 1,000. The target is updated in place: sizeBytes, pageCount, and checksum change, while id, filename, and ingestionStatus stay the same. Appended pages are not searchable. The default sync mode waits for the updated object. Use async for large appendices so the request returns immediately and completion arrives through vault.object.append.completed or vault.object.append.failed. Async acceptance returns 202 after the operation is durably saved, before worker dispatch. The operation has a 15-minute deadline, including dispatch and finalization. Work that cannot finish in that budget fails with APPEND_WORKER_TIMEOUT. Webhook delivery is retried separately if your endpoint is unavailable. Register an active endpoint through POST /webhooks/v1/endpoints with a vault.object.append.* filter before submitting the append. On async completion, newly generated download URLs serve the updated PDF. Download URLs issued before completion continue to refer to the previous PDF version until they expire.

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" \
  -H "Idempotency-Key: matter-123-chronology-append-1" \
  -d '{
    "mode": "async",
    "appendObjectIds": ["obj_exhibit_a", "obj_exhibit_b"],
    "rewriteLinks": true,
    "backLinks": true,
    "backLinksText": "Return to summary",
    "clientReference": "matter-123-chronology"
  }'

202 Response

{
  "objectId": "obj_report_123",
  "vaultId": "vault_abc123",
  "workflowId": "wdk_append_01K4APPEND123",
  "status": "processing",
  "appendedPageStart": 42,
  "clientReference": "matter-123-chronology"
}

Request body

Field	Type	Description
`mode`	`sync \| async`	Optional. Defaults to `sync`. Async mode returns `202` and completes through webhooks.
`appendObjectIds`	string[]	Required. PDF object IDs to append, in order. Must be unique and must not include the target object. Sync mode accepts at most 20; async mode accepts at most 1,000.
`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.
`clientReference`	string	Optional. Caller correlation value returned by async responses and webhooks.

Async mode requires an Idempotency-Key header. Retrying the same key and inputs returns the stored operation; reusing the key with different inputs returns 409. Only one asynchronous append can run against a target at a time, and non-forced deletion returns 409 while it runs. 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 worker runs out of memory while serializing the merged PDF. Sync mode also keeps the client request open for the full operation, so prefer async mode when the source set may take several minutes. 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, 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