Skip to main content

​
List your vaults

See all vaults in your organization.
Endpoint
GET /vault

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

for (const vault of vaults) {
  console.log(`${vault.name}: ${vault.totalObjects} documents`);
}
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

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'}`);
FieldDescription
enableIndexingWhether vector search is enabled. false for storage-only vaults
enableGraphWhether 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

// 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 });
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

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

for (const obj of objects) {
  console.log(`${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

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

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

​
Get extracted text

Get the OCR’d or transcribed text from a document.
Endpoint
GET /vault/:vaultId/objects/:objectId/text

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

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

​
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
await client.vault.objects.update(vaultId, objectId, {
  metadata: {
    category: 'legal_filing',
    tags: ['contract', 'employment', '2024'],
    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
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' }
});

​
Request body

FieldTypeDescription
filenamestringNew display name for the document
pathstringVirtual folder path (e.g., /Discovery/Depositions)
metadataobjectCustom 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.

​
Delete a document

Remove a single file and all its search data.
Endpoint
DELETE /vault/:vaultId/objects/:objectId

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

​
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
await client.vault.objects.delete(vaultId, objectId, { force: true });
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

await client.vault.delete(vaultId);
For large vaults (100+ documents), use async deletion: 
await client.vault.delete(vaultId, { async: true });
Permanent. This deletes all documents, search indexes, knowledge graphs, and storage. Cannot be undone.