Vault

Harvey’s Vault APIs enable your systems to programmatically upload, manage, and delete documents within secure Vault projects. These endpoints support integration with DMS systems, document pipelines, and client workflows requiring consistent structure, metadata, and compliance.

The current API request rate limits for Vault API endpoints are 10 requests per minute.

GET /api/v1/vault/workspace/projects
GET /api/v1/vault/workspace/recycle_bin
POST /api/v1/vault/upload_files/{project_id}
GET /api/v1/vault/get_metadata/{project_id}
GET /api/v1/vault/projects/{project_id}/files
GET /api/v1/vault/get_files
DELETE /api/v1/vault/delete_file/{file_id}
DELETE /api/v1/vault/delete_project/{project_id}

Overview

The Vault APIs are designed to streamline how legal teams ingest and manage large volumes of files (and other supported data formats), making them searchable and reviewable by Harvey. Use it to:

Automate Document Ingestion: Upload documents in real-time from your data source of choice (e.g., Document Management System, Contract Lifecycle Management tool, File Storage platform, etc.)
Preserve Folder Structure: Create a custom file library system with clear organization using nested directories
Track and Manage Files: Retrieve metadata or delete obsolete files as needed automatically

Looking to read results from or add rows to a Vault review table? Those endpoints are documented in the Review Tables guide.

Supported File Types

Vault supports the following formats:

PDF
Word (.doc, .docx)
Excel (.xls, .xlsx)
PowerPoint (.ppt, .pptx)
Text (.txt)
Markdown (.md)
HTML (.html)
CSV
RTF
XML
Email (.eml, .msg)
Images (.jpeg, .png, .tiff)
Common code file types (.c, .cpp, .java, .js, .json, .php, .py, .tex, .ts, .xml, .rb, .css)

Use Cases

Use Case 1: List All Workspace Projects

Challenge: Organizations need visibility into all Vault projects within their workspace to manage content effectively. Solution: Use the workspace projects endpoint to retrieve a paginated list of all projects accessible to your API token.

curl -X GET https://api.harvey.ai/api/v1/vault/workspace/projects?page=1&per_page=20 \
  -H "Authorization: Bearer YOUR_API_KEY"

This returns project details including IDs, names, file counts, and whether they’re designated as knowledge bases.

Use Case 2: Secure Document Storage in Vault

Challenge: Managing legal documents across multiple systems can lead to inefficiencies and security risks. Solution: Upload files directly into Vault to ensure secure, up-to-date storage with consistent project-level organization.

curl -X POST https://api.harvey.ai/vault/upload_files/{project_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@/path/to/contract.pdf" \
  -F "files=@/path/to/terms.docx" \
  -F "file_paths=contract.pdf" \
  -F "file_paths=terms.docx"

Use Case 3: Retrieve Project Storage Details

Challenge: Without visibility into stored files, users risk losing track of critical documents. Solution: Use the metadata endpoint to retrieve file IDs, names, sizes, and other details from a Vault project.

curl -X GET https://api.harvey.ai/vault/get_metadata/{project_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Use Case 4: Check File Processing Status

Challenge: After uploading files, organizations need to know when those files have finished processing and are ready to query. Solution: Use the get files endpoint to poll the processing status of one or more files by their IDs. This is useful as a heartbeat check in upload pipelines to confirm files are ready before issuing queries against them.

curl -X GET "https://api.harvey.ai/api/v1/vault/get_files?file_ids=01936a5f-8289-703a-9962-42bf196ae611&file_ids=01936a5f-82a2-708a-9df6-91d72c1cd26d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Each file in the response includes its processing_status (e.g., uploaded, processing, ready_to_query), content_type, and deleted_at timestamp. Files that are not found return an error field instead.

Use Case 5: Remove Outdated or Erroneous Files

Challenge: Projects evolve and occasionally contain outdated or incorrectly uploaded files that must be removed. Solution: Use the file deletion endpoint to remove files by ID. This is especially useful in automated pipelines or when enforcing compliance.

curl -X DELETE https://api.harvey.ai/vault/delete_file/{file_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Use Case 6: Delete Entire Vault Projects

Challenge: Organizations need to completely remove Vault projects that are no longer needed, ensuring complete cleanup of all associated documents and metadata. Solution: Use the project deletion endpoint to remove an entire Vault project by project ID. This action cannot be undone. Deletion continues asynchronously after the API request returns.

curl -X DELETE https://api.harvey.ai/api/v1/vault/delete_project/{project_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

The success response confirms that deletion is in progress:

{ "message": "Project deletion is in progress" }

Use Case 7: List and Filter Files Within a Project

Challenge: For large Vault projects, get_metadata returns flat parallel ID/name arrays that don’t allow filtering. Users have use cases to search and filter for specific files within their vault projects, without enumerating everything. Solution: Use the list project files endpoint to retrieve files with cursor pagination, server-side filtering, and sorting. Filter by name (case-insensitive substring), content_type, processing_status, or uploaded_after / uploaded_before. Sort by name, uploaded_at, or size in either direction.

curl -X GET "https://api.harvey.ai/api/v1/vault/projects/{project_id}/files?name=contract&content_type=application/pdf&processing_status=READY_TO_QUERY&sort_by=uploaded_at&sort_order=desc&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes a pagination block with next_cursor — pass it back as the cursor query parameter to fetch the next page. Continue until has_more is false.

Use Case 8: Review Vaults in the Recycle Bin

Challenge: When a Vault project is deleted it is not purged immediately — it first moves to a workspace recycle bin, where it can be reviewed (and, if needed, restored) before being permanently deleted. Administrators need visibility into which vaults are pending permanent deletion, who deleted them, and when that deletion is scheduled. Solution: Use the workspace recycle-bin endpoint to list every vault currently in the recycle bin for your workspace. This endpoint is restricted to workspace vault admins (the same permission as GET /api/v1/vault/workspace/projects).

curl -X GET "https://api.harvey.ai/api/v1/vault/workspace/recycle_bin?search_text=acme&client_matter_id=11111111-2222-3333-4444-555555555555" \
  -H "Authorization: Bearer YOUR_API_KEY"

Both query parameters are optional:

search_text — case-insensitive substring filter on the vault name.
client_matter_id — restrict results to vaults associated with this client matter (the client matter UUID, not the human-readable matter number).

The response returns an items array ordered by deleted_at descending, plus a total count. Each entry describes the recycle-bin row and embeds the deleted vault under vault_project (the same project shape returned by GET /api/v1/vault/workspace/projects):

{
  "items": [
    {
      "id": "0197a1b2-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
      "resource_id": "abcdef12-3456-7890-abcd-ef1234567890",
      "resource_type": "vault_project",
      "recycle_bin_status": "deleted",
      "deleted_at": "2026-07-15T18:42:10.512000Z",
      "recycle_bin_purged_scheduled_at": "2026-08-14T18:42:10.512000Z",
      "delete_source": "customer_delete",
      "deleted_source_id": "12345678-1234-5678-1234-567812345678",
      "deleted_by_user_email": "user@example.com",
      "vault_project": {
        "id": "abcdef12-3456-7890-abcd-ef1234567890",
        "name": "Acme Contract Repository",
        "created_at": "2026-01-15T10:30:00.000000",
        "creator_email": "user@example.com",
        "files_count": 42,
        "is_knowledge_base_project": false
      }
    }
  ],
  "total": 1
}

Key fields on each entry:

recycle_bin_status — always deleted for entries returned by this endpoint.
deleted_at — when the vault was moved into the recycle bin.
delete_source — how the delete was initiated: customer_delete, admin_delete, retention_delete, or system_delete.
deleted_by_user_email — the user who deleted the vault, populated for customer_delete and admin_delete; null for retention/system deletes or when the actor is unknown.
recycle_bin_purged_scheduled_at — when the vault is scheduled to be permanently purged from the recycle bin. null when no purge is scheduled.

Permanent deletion is not instantaneous at recycle_bin_purged_scheduled_at. The purge is carried out by a periodic background sweep, so a vault can take up to 30 minutes after recycle_bin_purged_scheduled_at passes to be fully purged.

Best Practices

Organize by Project

Use distinct project_id values to group documents by matter, client, or internal team structure.

Maintain File Path Consistency

Use the file_paths field to define relative folder structures so that uploads reflect your organization’s hierarchy.

Confirm Uploads and Deletions

After uploading, call GET /vault/get_metadata/{project_id} to confirm files are present, and use GET /vault/get_files to poll processing status until files reach ready_to_query. After deletions, check for a 200 confirmation response. When deleting entire projects, the project should no longer appear in the workspace projects list once deletion has completed.

Error Handling

Status Code	Description	Example Error Message
201	Success	N/A
400	Bad Request – Missing or invalid input	`{ "error": "Missing file" }`
401	Unauthorized – Invalid API key	`{ "error": "Unauthorized" }`
404	Not Found – Project or File not found	`{ "error": "File not found" }`
500	Internal Server Error	`{ "error": "Unexpected server error" }`

Need help getting started? Contact your Harvey Customer Success Manager for more information.

Getting Started

Endpoint Overview

MCP (Beta)

Overview

Supported File Types

Use Cases

Use Case 1: List All Workspace Projects

Use Case 2: Secure Document Storage in Vault

Use Case 3: Retrieve Project Storage Details

Use Case 4: Check File Processing Status

Use Case 5: Remove Outdated or Erroneous Files

Use Case 6: Delete Entire Vault Projects

Use Case 7: List and Filter Files Within a Project

Use Case 8: Review Vaults in the Recycle Bin

Best Practices

Organize by Project

Maintain File Path Consistency

Confirm Uploads and Deletions

Error Handling

​Overview

​Supported File Types

​Use Cases

​Use Case 1: List All Workspace Projects

​Use Case 2: Secure Document Storage in Vault

​Use Case 3: Retrieve Project Storage Details

​Use Case 4: Check File Processing Status

​Use Case 5: Remove Outdated or Erroneous Files

​Use Case 6: Delete Entire Vault Projects

​Use Case 7: List and Filter Files Within a Project

​Use Case 8: Review Vaults in the Recycle Bin

​Best Practices

​Organize by Project

​Maintain File Path Consistency

​Confirm Uploads and Deletions

​Error Handling

Overview

Supported File Types

Use Cases

Use Case 1: List All Workspace Projects

Use Case 2: Secure Document Storage in Vault

Use Case 3: Retrieve Project Storage Details

Use Case 4: Check File Processing Status

Use Case 5: Remove Outdated or Erroneous Files

Use Case 6: Delete Entire Vault Projects

Use Case 7: List and Filter Files Within a Project

Use Case 8: Review Vaults in the Recycle Bin

Best Practices

Organize by Project

Maintain File Path Consistency

Confirm Uploads and Deletions

Error Handling