Skip to main content
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.

​
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

​
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.
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.

​
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.

​
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.
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: Fetch Review Table Data

Challenge: After a review table has been run in Vault, teams need to programmatically access the table’s structure and results — for example, to export answers, check verification status, or build downstream workflows. Solution: Use review_table_ids from Get Project Metadata to discover available review tables, then retrieve each table’s metadata (title, file list) and drill into individual row results. Step 1 — Get the project’s review table IDs from the metadata endpoint:
The response includes a review_table_ids array (e.g., [2365724, 2365725]). An empty array means the project has no review tables. Step 2 — Fetch a review table’s metadata by ID to get its title and file list:
The response contains the table’s title, created_at timestamp, and file_ids — one ID per document row in the table. Step 3 — Retrieve a specific row using the review_table_id and a file_id from the previous step:
Each row contains an array of cells with the column name, Harvey’s short answer (summary), the full reasoning behind it (additional_context), supporting citations, and verification/flag status. Files reviewed together as a file group share a single row: requesting any file in the group returns that shared row, with file_id echoing the file you asked for. Within each field, a user-edited value takes precedence over the AI-generated value. Inline citation markers in summary and additional_context use [N] bracket notation, where N is the 1-based index into the cell’s citations array.

​
Use Case 6: 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.

​
Use Case 7: 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.
The success response confirms that deletion is in progress:

​
Use Case 8: 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.
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 9: 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).
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):
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.

​
Use Case 10: Add New Rows to an Existing Review Table

Challenge: Review tables are often long-lived — new documents arrive after the table was first run, and teams want them reviewed against the same columns without rebuilding the table in the UI. Sometimes a single row needs to cover several related documents, such as a master agreement and its amendments. Solution: Use the add row endpoint to add files from the review table’s Vault project as new rows. Harvey schedules a review run that populates each new row’s cells for every existing visible column. Step 1 — Upload the files to the review table’s Vault project (or pick existing files) and wait until each processing_status reaches ready_to_query:
Step 2 — Add the files to the review table. Pass a single ID in file_ids to add one file as its own row:
The response confirms the run was scheduled. review_file_group_id is null because a single file becomes its own row:
Step 3 — The run is asynchronous. Poll the row endpoint until its cells are populated:

​
Reviewing several files together as one row

Pass two or more IDs in file_ids to create a file group — the files are reviewed together and occupy a single row in the table, so each cell answers across the whole set of documents. Use the optional group_name to label the group:
The response returns the ID of the group that was created:
Because the group is a single row, poll it with get_row using any member file ID — each member resolves to the same grouped row. A few rules to keep in mind:
  • Every file must belong to the same Vault project the review table was created from; files from other projects return 404.
  • A file that already has a row returns 409. For a group request, a file that already belongs to a file group in the table also returns 409. A file that is still processing returns 409 too — retry once it reaches ready_to_query. In each case the error message names the offending file ID.
  • group_name defaults to the first file’s name, and is ignored when only one file is sent.
  • A request may carry up to 25 files by default; workspaces with a raised file-group limit may send more. Repeating the same ID in one request returns 400.
  • Adding several files at once always creates one grouped row rather than several individual rows. To add multiple independent rows, send one request per file.
  • File grouping must be enabled for your workspace; multi-file requests return 422 otherwise. Adding an already-grouped file as its own row also returns 422.
  • Re-adding a file whose row was previously deleted restores the original row instead of creating a duplicate.

​
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

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