{ "openapi": "3.0.1", "info": { "title": "Vault - Upload Documents", "description": "The Vault Upload Documents API enables users to programmatically upload and manage documents within Vault projects. This API allows organizations to maintain projects with their own internal files for their users to use within the Harvey app.", "version": "1.0.0", "contact": { "email": "support@harvey.ai" } }, "servers": [ { "url": "https://api.harvey.ai", "description": "Harvey API server" } ], "x-readme": { "explorer-enabled": false, "proxy-enabled": true }, "paths": { "/api/v1/vault/workspace/projects": { "get": { "x-mint": { "content": "### Permissions\nRequires `View workspace projects` permission." }, "tags": [ "Vault" ], "summary": "List Vault Projects and Knowledge Bases", "description": "Lists all Vault projects and knowledge bases in the current workspace with pagination support. This endpoint returns a paginated list of projects that the authenticated user has permission to view.", "operationId": "listWorkspaceProjects", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (default: 20, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "name", "in": "query", "description": "Case-insensitive substring match on project name.", "schema": { "type": "string", "maxLength": 256 }, "example": "acme" }, { "name": "is_knowledge_base", "in": "query", "description": "Filter by knowledge base flag. `true` returns only knowledge base projects, `false` excludes them, and omitting the parameter returns both.", "schema": { "type": "boolean" } }, { "name": "created_after", "in": "query", "description": "Inclusive lower bound on project creation time, expressed as a UTC Unix epoch timestamp in seconds. Only projects with `created_at >= created_after` are returned. Must be strictly less than `created_before` when both are provided.", "schema": { "type": "integer", "format": "int64" }, "example": 1767225600 }, { "name": "created_before", "in": "query", "description": "Exclusive upper bound on project creation time, expressed as a UTC Unix epoch timestamp in seconds. Only projects with `created_at < created_before` are returned.", "schema": { "type": "integer", "format": "int64" }, "example": 1775347200 }, { "name": "sort_by", "in": "query", "description": "Field to sort the results by. `date` sorts by the project's last content-update timestamp (the default ordering). `name` sorts alphabetically by project name.", "schema": { "type": "string", "enum": [ "date", "name" ], "default": "date" } }, { "name": "sort_order", "in": "query", "description": "Sort direction to order results list.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Successfully retrieved workspace projects", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "properties": { "content": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" }, "description": "Array of projects in the workspace" }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page number", "example": 3 }, "per_page": { "type": "integer", "description": "Number of items per page", "example": 20 }, "total": { "type": "integer", "description": "Total number of projects", "example": 45 }, "total_pages": { "type": "integer", "description": "Total number of pages", "example": 3 } } } } } } } } }, "examples": { "listWorkspaceProjects": { "summary": "Example response for listing workspace projects", "value": { "response": { "content": { "pagination": { "page": 1, "per_page": 20, "total": 150, "total_pages": 8 }, "projects": [ { "created_at": "2024-01-15T10:30:00.000000", "creator_email": "user@example.com", "files_count": 109, "id": "12345678-1234-5678-1234-567812345678", "is_knowledge_base_project": false, "name": "Example Legal Project", "project_retained_at": "2027-01-20T14:45:00.000000", "project_updated_at": "2026-01-20T14:45:00.000000", "query_count": 30, "sharing": { "user_count": 0, "user_shares": [], "workspace_count": 0, "workspace_shares": [] }, "size_bytes": 104857600, "updated_at": "2024-01-20T14:45:00.000000" }, { "created_at": "2024-01-10T09:15:00.000000", "creator_email": "user@example.com", "files_count": 45, "id": "87654321-8765-4321-8765-432187654321", "is_knowledge_base_project": true, "name": "Knowledge Base Project", "project_updated_at": "2026-01-18T11:20:00.000000", "query_count": 15, "sharing": { "user_count": 2, "user_shares": [ { "created_at": "2024-01-16T13:45:00.000000", "dest_user_email": "collaborator@example.com", "dest_user_id": "11111111-2222-3333-4444-555566667777", "dest_workspace_id": 2, "permission_level": "VIEW", "src_user_id": "12345678-1234-5678-1234-567812345678", "src_workspace_id": 1, "vault_folder_id": "87654321-8765-4321-8765-432187654321" } ], "workspace_count": 1, "workspace_shares": [ { "created_at": "2024-01-17T16:30:00.000000", "dest_workspace_id": 3, "permission_level": "EDIT", "src_user_id": "12345678-1234-5678-1234-567812345678", "src_workspace_id": 1, "vault_folder_id": "87654321-8765-4321-8765-432187654321" } ] }, "size_bytes": 52428800, "updated_at": "2024-01-18T11:20:00.000000" } ] } } } } } } } }, "400": { "description": "Bad request - Invalid query parameters (e.g. `page < 1`, `per_page > 100`, malformed `created_after`/`created_before`, `created_after >= created_before`, or unrecognized `sort_by`/`sort_order` value)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid query parameters" }, "details": { "type": "array", "description": "Per-field validation errors", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Name of the query parameter that failed validation", "example": "created_before" }, "message": { "type": "string", "description": "Human-readable description of the validation failure", "example": "created_after must be earlier than created_before" } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API token" }, "403": { "description": "Forbidden - User does not have permission to view workspace projects" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/workspace/recycle_bin": { "get": { "x-mint": { "content": "### Permissions\nRequires `View workspace projects` permission." }, "tags": [ "Vault" ], "summary": "List Vaults in the Recycle Bin", "description": "Lists every vault currently in the recycle bin for the current workspace. When a Vault project is deleted it is not purged immediately \u2014 it first moves to a workspace recycle bin, where it can be reviewed before being permanently deleted. Entries are ordered by `deleted_at` descending. This endpoint is restricted to workspace vault admins (the same permission as `GET /api/v1/vault/workspace/projects`).", "operationId": "listWorkspaceRecycleBins", "parameters": [ { "name": "search_text", "in": "query", "description": "Case-insensitive substring filter on the vault name.", "schema": { "type": "string" }, "example": "acme" }, { "name": "client_matter_id", "in": "query", "description": "Restrict results to vaults associated with this client matter (the client matter UUID, not the human-readable matter number).", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "responses": { "200": { "description": "Successfully retrieved recycle-bin entries for the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RecycleBinEntry" }, "description": "Recycle-bin entries ordered by `deleted_at` descending" }, "total": { "type": "integer", "description": "Number of entries returned", "example": 1 } }, "required": [ "items", "total" ] }, "examples": { "listWorkspaceRecycleBins": { "summary": "Example response for listing recycle-bin entries", "value": { "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 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API token" }, "403": { "description": "Forbidden - User is not a workspace vault admin" }, "404": { "description": "Not found - The recycle bin feature is not enabled for the workspace" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/get_metadata/{project_id}": { "get": { "x-mint": { "content": "### Permissions\nRequires `Vault API` permission." }, "tags": [ "Vault" ], "summary": "Get Vault Project Metadata", "description": "Fetches metadata for a specified Vault project, including file details and storage limits.", "operationId": "getProjectMetadata", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The project ID." } } ], "responses": { "201": { "description": "Project metadata details", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectMetadata" } } } } } }, "examples": { "projectMetadata": { "summary": "Project metadata response", "value": { "response": { "content": [ { "project_id": "01936a5f-53a0-7b33-91aa-3bd2441ccc89", "file_ids": [ "01936a5f-8289-703a-9962-42bf196ae611", "01936a5f-82a2-708a-9df6-91d72c1cd26d", "01936a5f-82de-7096-a7c2-021638a813ad" ], "file_names": [ "Employment Agreement - John Smith.pdf", "Merger Agreement - Acme Corp.docx", "Non-Disclosure Agreement - TechCo Inc.pdf" ], "file_count": 3, "max_file_count": 100000, "project_size": "11015244", "max_project_size": 107374182400 } ] } } } } } } }, "400": { "description": "Bad request." }, "401": { "description": "Unauthorized." }, "404": { "description": "Project not found." }, "500": { "description": "Internal server error." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/review_table/{review_table_id}": { "get": { "x-mint": { "content": "### Permissions\nRequires `Vault API` permission." }, "tags": [ "Vault" ], "summary": "Get Review Table Metadata", "description": "Fetches metadata for a single review table by its ID, including its title, creation timestamp, and the list of file IDs associated with it.\n\nUse the `review_table_ids` returned by **Get Vault Project Metadata** to enumerate available review tables in a project. Once you have a `review_table_id`, you can:\n- Call this endpoint to retrieve the table's `title`, `created_at`, and `file_ids`.\n- Call **Get Review Table Row** with a `review_table_id` and `file_id` to retrieve row-level data for a specific file.", "operationId": "getReviewTable", "parameters": [ { "name": "review_table_id", "in": "path", "required": true, "description": "The integer ID of the review table. Obtain this from the `review_table_ids` array in the Get Vault Project Metadata response.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Review table metadata returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/ReviewTable" } } } } }, "examples": { "getReviewTable": { "summary": "Example response for getting a review table", "value": { "response": { "content": { "review_table_id": 2365724, "title": "Lease Review \u2013 Q1 2025", "created_at": "2025-01-10T09:00:00.000000", "file_ids": [ "0199c5c1-50d9-7d60-93aa-cd65c3b7d5a9", "01936a5f-8289-703a-9962-42bf196ae611" ] } } } } } } } }, "401": { "description": "Unauthorized \u2013 Missing or invalid API token." }, "403": { "description": "Forbidden \u2013 User does not have access to the project that contains this review table." }, "404": { "description": "Review table not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/get_files": { "get": { "x-mint": { "content": "### Permissions\nRequires `Vault API` permission." }, "tags": [ "Vault" ], "summary": "Get File Details", "description": "Retrieves details and processing status for one or more files by their IDs. A maximum of 1000 file IDs can be provided per request. This endpoint is useful for checking the processing status of recently uploaded files to determine when they are ready to query. Files that are not found or not accessible are returned with an error field instead of file details.", "operationId": "getFiles", "parameters": [ { "name": "file_ids", "in": "query", "required": true, "description": "Comma-separated list of file IDs to retrieve details for.", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "example": "01936a5f-8289-703a-9962-42bf196ae611,01936a5f-82a2-708a-9df6-91d72c1cd26d" } ], "responses": { "200": { "description": "File details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/FileDetails" } } } } } }, "examples": { "getFiles": { "summary": "Example response for getting file details", "value": { "response": { "content": [ { "file_id": "01936a5f-8289-703a-9962-42bf196ae611", "file_name": "Employment Agreement - John Smith.pdf", "processing_status": "ready_to_query", "content_type": "application/pdf", "deleted_at": null }, { "file_id": "01936a5f-82a2-708a-9df6-91d72c1cd26d", "file_name": "Merger Agreement - Acme Corp.docx", "processing_status": "processing", "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "deleted_at": null }, { "file_id": "01936a5f-82de-7096-a7c2-021638a813ad", "error": "not_found" } ] } } } } } } }, "400": { "description": "Bad request - Missing or empty file_ids" }, "401": { "description": "Unauthorized - Invalid or missing API token" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/get_row/{review_table_id}/{file_id}": { "get": { "x-mint": { "content": "### Permissions\nRequires `Vault API` permission." }, "tags": [ "Vault" ], "summary": "Get Review Table Row Details", "description": "Enables authorized users to retrieve a row from a review table, given a review table ID and a file ID corresponding to the row.\n\nFiles that belong to a file group (multiple files reviewed together as a single row) are supported: requesting any file in the group returns the group's row, with `file_id` in the response echoing the requested file.\n\nThe `review_table_id` path parameter is the review table's integer ID \u2014 the same value as `review_table_ids` entries in **Get Vault Project Metadata** and as `review_table_id` in the **Get Review Table Metadata** response. Use **Get Review Table Metadata** to obtain the `file_ids` valid for a given `review_table_id`.\n\nFor each cell in the response, `summary` contains the short answer and `additional_context` contains the full reasoning behind it. Within each field, a user-edited value takes precedence over the AI-generated value, including the empty string \u2014 if a user clears a field, the API returns `\"\"` for that field and sets `is_edited` to `true` rather than falling back to the AI text. The AI value is only used when the user has never edited that field.", "operationId": "getReviewTableRow", "parameters": [ { "name": "review_table_id", "in": "path", "required": true, "description": "The review table ID (integer). This is the same value as `review_table_ids` entries returned by Get Vault Project Metadata and as `review_table_id` returned by Get Review Table Metadata.", "schema": { "type": "integer" } }, { "name": "file_id", "in": "path", "required": true, "description": "The file ID corresponding to the row. A file that is part of a file group resolves to the group's row.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Review table row returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "assigned_user": { "type": "string", "format": "email", "description": "Email of the user assigned to the row" }, "event_id": { "type": "integer", "description": "The review table ID (same value as the path parameter)" }, "file_id": { "type": "string", "format": "uuid", "description": "Echoes the requested file ID. For a row that covers a file group, this is the requested member file rather than an identifier of the row itself." }, "is_assigned": { "type": "boolean", "description": "Whether the row is assigned to a user" }, "updated_at": { "type": "string", "description": "Timestamp when the row was last updated" }, "response": { "type": "object", "description": "The review table response containing cells", "properties": { "cells": { "type": "array", "description": "Array of cells in the review table", "items": { "type": "object", "properties": { "additional_context": { "type": "string", "description": "The full reasoning behind the answer (user-edited value if present, otherwise the AI-generated reasoning). May contain inline citation markers in `[N]` bracket notation, where `N` is the 1-based index into the `citations` array." }, "citations": { "type": "array", "description": "Citations for the cell", "items": { "type": "object", "properties": { "citation_page": { "type": "integer", "description": "Page number of the citation" }, "citation_quote": { "type": "string", "description": "Quote from the citation" } } } }, "column_name": { "type": "string", "description": "Name of the column" }, "column_question": { "type": "string", "description": "Question for the column" }, "flagged_timestamp": { "type": "string", "description": "Timestamp when the cell was flagged" }, "flagged_user": { "type": "string", "format": "email", "description": "Email of the user who flagged the cell" }, "is_edited": { "type": "boolean", "description": "Whether the cell has been edited" }, "is_flagged": { "type": "boolean", "description": "Whether the cell is flagged" }, "is_verified": { "type": "boolean", "description": "Whether the cell is verified" }, "summary": { "type": "string", "description": "The short answer for this cell (user-edited value if present, otherwise the AI-generated answer). May contain inline citation markers in `[N]` bracket notation, where `N` is the 1-based index into the `citations` array." }, "verified_timestamp": { "type": "string", "description": "Timestamp when the cell was verified" }, "verified_user": { "type": "string", "format": "email", "description": "Email of the user who verified the cell" } } } } } } } }, "examples": { "getReviewTableRow": { "summary": "Example response for getting a review table row", "value": { "assigned_user": "grace.hong@harvey.ai", "event_id": 2365724, "file_id": "0199c5c1-50d9-7d60-93aa-cd65c3b7d5a9", "is_assigned": true, "updated_at": "Wed, 10 Dec 2025 00:38:49 GMT", "response": { "cells": [ { "citations": [ { "citation_page": 62, "citation_quote": "IN WITNESS WHEREOF, Landlord and Tenant have executed this Lease as of the Commencement Date as set " }, { "citation_page": 5, "citation_quote": "COMMENCEMENT DATE: February 7, 2011" }, { "citation_page": 7, "citation_quote": "The Reference Pages, including all terms defined thereon, are incorporated as part of this Lease." } ], "column_name": "Lease Start Date", "column_question": "What date is the lease from?", "additional_context": "The lease is from February 07, 2011. This is the Commencement Date specified in the lease, and the lease was executed as of this date.", "is_edited": false, "is_flagged": false, "is_verified": true, "summary": "February 7, 2011", "verified_timestamp": "Sat, 20 Dec 2025 01:37:19 GMT", "verified_user": "grace.hong@harvey.ai" }, { "citations": [ { "citation_page": 12, "citation_quote": "Tenant agrees to pay to Landlord the Annual Rent in effect from time to time by paying the Monthly I" }, { "citation_page": 21, "citation_quote": "Tenant shall keep the Project and appurtenant land and Tenant's leasehold interest in the Premises f" }, { "citation_page": 22, "citation_quote": "Tenant shall have the right to assign or pledge this Lease or to sublet all or any portion of the Pr" }, { "citation_page": 42, "citation_quote": "Tenant and Landlord shall meet for two (2) joint inspections of the Premises, the first to occur at " }, { "citation_page": 18, "citation_quote": "Tenant shall, at its own cost and expense, keep and maintain all parts of the Premises in good condition." }, { "citation_page": 24, "citation_quote": "Tenant shall keep in force throughout the Term: (a) a Commercial General Liability insurance policy " }, { "citation_page": 23, "citation_quote": "Except to the extent arising from the gross negligence or willful misconduct of Landlord, its agents" }, { "citation_page": 42, "citation_quote": "Tenant shall be responsible for the payment of any" } ], "column_name": "Lessee Obligations", "column_question": "What are the obligations of the leasee?", "additional_context": "The obligations of the lessee (Tenant) under the Company C Lease include paying Annual Rent in monthly installments, keeping the Premises and appurtenant land free of liens, maintaining the Premises in good condition, carrying Commercial General Liability insurance, indemnifying Landlord for claims arising from the Tenant's use, and participating in joint inspections of the Premises with the Landlord.", "flagged_timestamp": "Sat, 20 Dec 2025 01:37:23 GMT", "flagged_user": "grace.hong@harvey.ai", "is_edited": false, "is_flagged": true, "is_verified": true, "summary": "Pay rent, maintain the Premises, carry insurance, and indemnify the Landlord.", "verified_timestamp": "Sat, 20 Dec 2025 01:37:22 GMT", "verified_user": "grace.hong@harvey.ai" }, { "additional_context": "The lease is from February 07, 2011. This is the Commencement Date specified in the lease, and the lease was executed.", "citations": [], "column_name": "Lease Start Date", "column_question": "What date is the lease from?", "is_edited": true, "is_flagged": false, "is_verified": true, "summary": "February 7, 2011", "verified_timestamp": "Sat, 20 Dec 2025 01:37:19 GMT", "verified_user": "grace.hong@harvey.ai" } ] } } } } } } }, "400": { "description": "Bad request." }, "401": { "description": "Unauthorized." }, "404": { "description": "Review table row not found. Returned when the file has neither its own row nor a file group row in the review table." }, "500": { "description": "Internal server error." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/add_row/{review_table_id}": { "post": { "x-mint": { "content": "### Permissions\nRequires `Vault API` permission and permission to modify workspace projects." }, "tags": [ "Vault" ], "summary": "Add Row to Review Table", "description": "Adds one or more files to an existing review table as new rows and populates each new row's cells for every existing visible column.\n\nSend a single file ID in `file_ids` to add it as its own row. Send two or more file IDs to create a **file group** \u2014 the files are reviewed together and occupy a single row in the table. Pass the optional `group_name` to name that group; it defaults to the first file's name.\n\nEvery file must belong to the same Vault project the review table was created from and must have finished processing. Use **List Files in a Vault Project** or **Get File Details** to check a file's `processing_status` before adding it.\n\nThe run is asynchronous: a successful response means the request was accepted and the rows were scheduled for execution. Poll **Get Review Table Row Details** with the same `review_table_id` and one of the submitted file IDs until the row's cells are returned. For a file group, requesting any member file returns the group's single row.\n\nA file that already has a row in the table, or that already belongs to a file group in it, is rejected with `409`; the error message names the offending file ID. Adding a file whose row was previously deleted from the table restores that row rather than creating a duplicate.\n\nThe `review_table_id` path parameter is the review table's integer ID \u2014 the same value as `review_table_ids` entries in **Get Vault Project Metadata** and as `review_table_id` in the **Get Review Table Metadata** response.", "operationId": "addReviewTableRow", "parameters": [ { "name": "review_table_id", "in": "path", "required": true, "description": "The review table ID (integer). This is the same value as `review_table_ids` entries returned by Get Vault Project Metadata and as `review_table_id` returned by Get Review Table Metadata.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_ids": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string", "format": "uuid" }, "description": "The IDs of the files to add. One file is added as its own row; two or more are grouped into a file group that occupies a single row. Every file must belong to the review table's Vault project, must have finished processing, and must not already have a row or group membership in the table. Duplicate IDs are rejected with `400`. Capped at 25 files per request by default; workspaces with a raised file-group limit may send more." }, "group_name": { "type": "string", "nullable": true, "description": "Optional name for the file group created when two or more files are added. Defaults to the first file's name. Ignored for single-file requests." } }, "required": [ "file_ids" ] }, "examples": { "addSingleRow": { "summary": "Add a single file as its own row", "value": { "file_ids": [ "0199c5c1-50d9-7d60-93aa-cd65c3b7d5a9" ] } }, "addFileGroupRow": { "summary": "Add several files as one grouped row", "value": { "file_ids": [ "0199c5c1-50d9-7d60-93aa-cd65c3b7d5a9", "019f66b0-5706-7239-b7b8-9c61cbec8b7a" ], "group_name": "Acme MSA and amendments" } } } } } }, "responses": { "200": { "description": "Review run scheduled successfully for the new rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "properties": { "event_id": { "type": "integer", "description": "The review table ID (same value as the path parameter)" }, "file_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Echoes the file IDs that were added" }, "review_event_run_id": { "type": "string", "format": "uuid", "description": "The ID of the review run scheduled to populate the new rows" }, "review_file_group_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The ID of the file group created when two or more files were added as one grouped row. `null` for single-file requests." }, "status": { "type": "string", "description": "Always `scheduled` on success. Poll Get Review Table Row Details for the row's results." } } } } }, "examples": { "addSingleRow": { "summary": "Example response for adding a single file as its own row", "value": { "response": { "event_id": 2365724, "file_ids": [ "0199c5c1-50d9-7d60-93aa-cd65c3b7d5a9" ], "review_event_run_id": "019f8d8f-fc20-79e0-8b78-980b747c5ef3", "review_file_group_id": null, "status": "scheduled" } } }, "addFileGroupRow": { "summary": "Example response for adding several files as one grouped row", "value": { "response": { "event_id": 2365724, "file_ids": [ "0199c5c1-50d9-7d60-93aa-cd65c3b7d5a9", "019f66b0-5706-7239-b7b8-9c61cbec8b7a" ], "review_event_run_id": "019f97bd-6d6c-7715-b63e-a0a11437f202", "review_file_group_id": "019f97bd-6d57-7aaf-9559-58812be0e1a7", "status": "scheduled" } } } } } } }, "400": { "description": "Bad request. Returned when `file_ids` is missing or empty, contains duplicate IDs, exceeds the per-request file limit, or when the review table has no columns to run." }, "401": { "description": "Unauthorized." }, "403": { "description": "Forbidden. The caller does not have permission to modify this review table." }, "404": { "description": "Review table not found, or a file does not exist in the review table's Vault project. The error message names the offending file ID." }, "409": { "description": "Conflict. A file already has a row in this review table, already belongs to a file group in it, or is still processing and cannot be added yet. The error message names the offending file ID." }, "422": { "description": "Unprocessable. File grouping is not enabled for this workspace, a file being added as its own row belongs to a file group, or the review table is not backed by a Vault project." }, "429": { "description": "Too many requests. Retry after the interval in the Retry-After header." }, "500": { "description": "Internal server error." } } } }, "/api/v1/vault/projects/{project_id}/files": { "get": { "x-mint": { "content": "### Permissions\nRequires `Vault API` permission and access to the specified vault project." }, "tags": [ "Vault" ], "summary": "List Files in a Vault Project", "description": "Lists files within a single vault project, with filtering and sorting supported.\n\n**Pagination.** Omit `cursor` on the first request. Subsequent requests should pass back the `next_cursor` value returned in the previous response. Continue until `has_more` is `false`.", "operationId": "listProjectFiles", "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The unique identifier of the vault project", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor returned in the previous response's `next_cursor` field. Omit on the first request.", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "limit", "in": "query", "description": "Maximum number of files to return per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "name", "in": "query", "description": "Case-insensitive substring match on file name. `%` and `_` are treated as literals, not SQL `LIKE` wildcards.", "schema": { "type": "string", "maxLength": 256 }, "example": "contract" }, { "name": "content_type", "in": "query", "description": "Filter by MIME type. Repeat the query parameter to match any of multiple values (e.g. `?content_type=application/pdf&content_type=text/plain`). Up to 20 values, each at most 256 characters.", "schema": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "maxItems": 20 }, "explode": true, "style": "form", "example": [ "application/pdf" ] }, { "name": "processing_status", "in": "query", "description": "Filter by processing status. Repeat the query parameter to match any of multiple values. Accepted case-insensitively (`READY_TO_QUERY` and `ready_to_query` are equivalent). Internal-only statuses are rejected. Up to 20 values.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "UPLOADED", "PROCESSING", "READY_TO_QUERY", "READY_TO_REVIEW", "RECOVERABLE_FAILURE", "UNRECOVERABLE_FAILURE" ] }, "maxItems": 20 }, "explode": true, "style": "form" }, { "name": "uploaded_after", "in": "query", "description": "Inclusive lower bound on the file's upload time, as a UTC Unix epoch timestamp in seconds. Must be strictly less than `uploaded_before` when both are provided.", "schema": { "type": "integer", "format": "int64" }, "example": 1767225600 }, { "name": "uploaded_before", "in": "query", "description": "Inclusive upper bound on the file's upload time, as a UTC Unix epoch timestamp in seconds.", "schema": { "type": "integer", "format": "int64" }, "example": 1775347200 }, { "name": "sort_by", "in": "query", "description": "Field to sort the results by. Accepted case-insensitively.", "schema": { "type": "string", "enum": [ "name", "uploaded_at", "size" ], "default": "uploaded_at" } }, { "name": "sort_order", "in": "query", "description": "Sort direction. Accepted case-insensitively. Results include the file `id` as a deterministic tiebreaker so cursor-paginated ordering is stable across pages.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Successfully retrieved project files", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "properties": { "content": { "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectFile" }, "description": "Files matching the filter and sort criteria, ordered as requested." }, "pagination": { "$ref": "#/components/schemas/ProjectFilesPagination" } } } } } } }, "examples": { "listProjectFiles": { "summary": "Example response for listing files in a project", "value": { "response": { "content": { "files": [ { "id": "018e38dc-8726-7bc2-af5d-bdd5d04c84ec", "name": "engagement_letter.pdf", "content_type": "application/pdf", "processing_status": "READY_TO_QUERY", "size": 184320, "uploaded_at": 1767225600 }, { "id": "0199c5c1-50d9-7d60-93aa-cd65c3b7d5a9", "name": "merger_agreement.docx", "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "processing_status": "PROCESSING", "size": 521447, "uploaded_at": 1767139200 } ], "pagination": { "page_size": 20, "has_more": true, "next_cursor": "eyJsYXN0X2ZpbGVfaWQiOiAiMDE5OWM1YzEtNTBkOS03ZDYwLTkzYWEtY2Q2NWMzYjdkNWE5In0=", "total_count": 137 } } } } } } } } }, "400": { "description": "Bad request - Invalid query parameters (e.g. `limit` out of range, malformed `cursor`, unrecognized `sort_by`, `uploaded_after >= uploaded_before`, or an internal-only `processing_status` value)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid query parameters" }, "details": { "type": "array", "description": "Per-field validation errors", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Name of the query parameter that failed validation", "example": "processing_status" }, "message": { "type": "string", "description": "Human-readable description of the validation failure", "example": "Value error, processing_status must be one of: ['PROCESSING', 'READY_TO_QUERY', 'READY_TO_REVIEW', 'RECOVERABLE_FAILURE', 'UNRECOVERABLE_FAILURE', 'UPLOADED']" } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API token" }, "403": { "description": "Forbidden - User does not have access to the Vault API or to the requested project" }, "404": { "description": "Project not found" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/projects/{project_id}/users": { "get": { "x-mint": { "content": "### Permissions\nRequires `Vault API` permission, and either `Vault sharing (view only)` or `Vault sharing` permission." }, "tags": [ "Vault" ], "summary": "List Project Users", "description": "Lists all workspace users with current active access to a specified Vault project, along with their access levels. Includes effective user access (including inherited access), and the project owner is always included with `MANAGE` access.\n\nRequires vault sharing to be enabled.", "operationId": "listProjectUsers", "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The unique identifier of the Vault project", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successfully retrieved project users", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED" ], "description": "Status of the request" }, "data": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "The project ID" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectUserShare" }, "description": "List of users with access to the project" } }, "required": [ "project_id", "users" ] } }, "required": [ "status", "data" ] }, "examples": { "listProjectUsers": { "summary": "Example response for listing project users", "value": { "status": "COMPLETED", "data": { "project_id": "12345678-1234-5678-1234-567812345678", "users": [ { "user_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "email": "admin@example.com", "name": "Alice Admin", "access_level": "MANAGE" }, { "user_id": "11111111-2222-3333-4444-555566667777", "email": "reviewer@example.com", "name": "Bob Reviewer", "access_level": "READ" } ] } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API token" }, "403": { "description": "Forbidden - User lacks required permissions, vault sharing is disabled, or project access is denied" }, "404": { "description": "Project not found" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "x-mint": { "content": "### Permissions\nRequires `Vault API` and `Vault sharing` permissions." }, "tags": [ "Vault" ], "summary": "Update Project Users", "description": "Adds or updates workspace user shares on a Vault project. This endpoint uses an additive/partial-update model: users in the request are added or have their access level updated; users not in the request are left unchanged. The project owner cannot be included in the request.\n\nRequires vault sharing to be enabled.", "operationId": "updateProjectUsers", "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The unique identifier of the Vault project", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "The email address of the workspace user" }, "access_level": { "type": "string", "enum": [ "READ", "WRITE", "MANAGE" ], "description": "The desired access level for this user" } }, "required": [ "email", "access_level" ] }, "description": "The list of users and their desired access levels to add or update. Users omitted from this list are left unchanged." } }, "required": [ "users" ] }, "examples": { "updateProjectUsers": { "summary": "Example request to update project users", "value": { "users": [ { "email": "admin@example.com", "access_level": "MANAGE" }, { "email": "reviewer@example.com", "access_level": "READ" } ] } } } } } }, "responses": { "200": { "description": "Project users successfully updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED" ], "description": "Status of the request" }, "data": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "The project ID" }, "added": { "type": "array", "description": "Users that were newly granted access", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "access_level": { "type": "string", "enum": [ "READ", "WRITE", "MANAGE" ] } }, "required": [ "email", "access_level" ] } }, "updated": { "type": "array", "description": "Users whose access level was changed", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "access_level": { "type": "string", "enum": [ "READ", "WRITE", "MANAGE" ] }, "previous_access_level": { "type": "string", "enum": [ "READ", "WRITE", "MANAGE" ] } }, "required": [ "email", "access_level", "previous_access_level" ] } }, "failed": { "type": "array", "description": "Users whose share update failed, with the reason", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "reason": { "type": "string", "description": "Why the share update failed for this user" } }, "required": [ "email", "reason" ] } } }, "required": [ "project_id", "added", "updated", "failed" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Bad request - malformed request body (e.g. missing required fields, invalid JSON)" }, "401": { "description": "Unauthorized - Invalid or missing API token" }, "403": { "description": "Forbidden - User lacks required permissions, vault sharing is disabled, or project access is denied" }, "404": { "description": "Project not found" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "x-mint": { "content": "### Permissions\nRequires `Vault API` and `Vault sharing` permissions." }, "tags": [ "Vault" ], "summary": "Remove Project Users", "description": "Removes direct workspace user shares for specified users (identified by email address) from a Vault project. Only direct `WORKSPACE_USER` shares are removed; inherited access via workspace, group, or space shares is not affected. Per-user validation failures (e.g. unknown email, inactive user, project owner, self-removal) are returned in the `failed` list rather than rejecting the entire request.\n\nRequires vault sharing to be enabled.", "operationId": "removeProjectUsers", "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The unique identifier of the Vault project", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "List of workspace user email addresses whose direct shares should be removed from the project" } }, "required": [ "emails" ] } } } }, "responses": { "200": { "description": "Successfully processed removal request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED" ], "description": "Status of the request" }, "data": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "The project ID" }, "removed": { "type": "array", "description": "Email addresses of users whose direct shares were successfully removed", "items": { "type": "string", "format": "email" } }, "failed": { "type": "array", "description": "Users whose share removal failed, with per-user reasons", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "The email address that failed" }, "reason": { "type": "string", "description": "Why the removal failed (e.g. \"User not found\", \"Cannot remove project owner\", \"Duplicate email in request\")" } }, "required": [ "email", "reason" ] } } }, "required": [ "project_id", "removed", "failed" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Bad request - malformed request body (e.g. missing required fields, invalid JSON)" }, "401": { "description": "Unauthorized - Invalid or missing API token" }, "403": { "description": "Forbidden - User lacks required permissions, vault sharing is disabled, or project access is denied" }, "404": { "description": "Project not found" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/create_project": { "post": { "x-mint": { "content": "### Permissions\nRequires `Vault API` and `Modify workspace projects` permissions." }, "tags": [ "Vault" ], "summary": "Create a new Vault project", "description": "Creates a new project in the Vault system. The project can be designated as a knowledge base.", "operationId": "createVaultProject", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the new project", "example": "Example Legal Documents Project" }, "is_knowledge_base_project": { "type": "boolean", "description": "Flag indicating whether this project is a knowledge base", "example": true }, "client_matter_id": { "type": "string", "format": "uuid", "description": "When set, associates the new project with this client matter. Use the client matter UUID (from Client Matters API responses), not the human-readable matter number.", "example": "11111111-2222-3333-4444-555555555555" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Project successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectResponse" } } } }, "400": { "description": "Bad request." }, "401": { "description": "Unauthorized." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Internal server error." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/upload_files/{project_id}": { "post": { "x-mint": { "content": "### Permissions\nRequires `Vault API` and `Modify workspace projects` permissions." }, "tags": [ "Vault" ], "summary": "Upload Files to Project", "description": "The Upload Files API endpoint enables organizations to both upload new files and update existing ones within Vault projects. A maximum of 50 files can be uploaded per API request.", "operationId": "uploadFilesToProject", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The project ID." } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Path to the files to be uploaded, e.g. `@/path/to/hello_world.pdf`. Each file is a separate multipart/form-data. PDF, DOCX, XLSX, PPT, TXT, RTF, CSV, EML, and other file formats supported (reference our Help Center). Max size of 500 MB for all file types. A maximum of 50 files can be uploaded per API request. Beware of HTTPS timeouts if too many large files are sent at a time.", "example": "@/path/to/hello_world.pdf" }, "file_paths": { "type": "array", "items": { "type": "string" }, "description": "The desired folder structure for the file(s), e.g. `/caselaw/usa/california/sf/hello_world.pdf`. This will be reconciled with the names in the provided `files` paths.", "example": "/caselaw/usa/california/sf/hello_world.pdf" }, "duplicate_mode": { "type": "string", "enum": [ "skip", "replace", "keep" ], "description": "Determines how duplicate file names are handled. `skip` will not update if a file with the same name already exists. `replace` will create a new file record (with its own unique `file_id`) and set its `root_file_id` to the original `file_id`. `keep` will rename the new file to avoid collision (e.g. `document (1).pdf`).", "example": "skip" } } } } } }, "responses": { "201": { "description": "Files successfully uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } }, "400": { "description": "Bad request." }, "401": { "description": "Unauthorized." }, "413": { "description": "Payload too large." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Internal server error." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/semantic_search": { "post": { "x-mint": { "content": "### Permissions\nRequires `Vault API` and `Vault sharing` permissions." }, "tags": [ "Vault" ], "summary": "Semantic search over a vault project", "description": "Performs semantic search over documents in a single vault project. Returns the most relevant text chunks for the given natural-language query. Intended for use by external systems (e.g. a customer's own assistant or LLM) that need to retrieve relevant passages and then generate responses using their own models.\n\nRequires vault sharing to be enabled.", "operationId": "vaultSemanticSearch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSemanticSearchRequest" } } } }, "responses": { "200": { "description": "Search completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSemanticSearchResponse" } } } }, "400": { "description": "Bad request - Missing or invalid project_id or query" }, "401": { "description": "Unauthorized - Invalid or missing API token" }, "403": { "description": "Forbidden - User does not have access to the Vault API or to the project" }, "500": { "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/delete_file/{file_id}": { "delete": { "x-mint": { "content": "### Permissions\nRequires `Vault API` and `Modify workspace projects` permissions." }, "tags": [ "Vault" ], "summary": "Delete a file from a Vault project", "description": "Enables authorized organizations to remove an existing file from a Vault project. The endpoint verifies that the file exists and that the requesting user belongs to the file's workspace before proceeding with the deletion. In cases where deletion cannot be immediately completed (for example, if there are pending jobs associated with the file), the API responds with a conflict status. On success, the system logs an audit event and returns confirmation of the deletion.", "operationId": "deleteVaultFile", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The unique identifier of the file to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "File successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "File successfully deleted" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API token" }, "403": { "description": "Forbidden - User does not have required permissions" }, "404": { "description": "File not found" }, "409": { "description": "Conflict - File cannot be deleted due to pending jobs or other constraints" }, "429": { "description": "Too Many Requests - Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/vault/delete_project/{project_id}": { "delete": { "x-mint": { "content": "### Permissions\nRequires `Vault API` and `Modify workspace projects` permissions." }, "summary": "Delete an entire vault project and all its contents", "operationId": "deleteVaultProject", "tags": [ "Vault" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The unique identifier of the project to delete" } ], "responses": { "200": { "description": "Project deletion accepted. Deletion continues asynchronously after the API request returns.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Deletion status message.", "example": "Project deletion is in progress" } }, "required": [ "message" ] }, "examples": { "inProgress": { "summary": "Deletion queued", "value": { "message": "Project deletion is in progress" } } } } } }, "400": { "description": "Bad request." }, "401": { "description": "Unauthorized." }, "403": { "description": "Forbidden - Cannot delete example projects or insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Cannot delete example projects" } } } } } }, "404": { "description": "Project not found." }, "409": { "description": "Conflict - Project deletion partially failed due to processing conflicts", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Project deletion partially failed due to processing conflicts" }, "details": { "type": "object", "properties": { "failed_folders": { "type": "integer", "description": "Number of folders that failed to delete" }, "failed_files": { "type": "integer", "description": "Number of files that failed to delete" } } } } } } } }, "500": { "description": "Internal server error." } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "CreateProjectResponse": { "type": "object", "properties": { "project_id": { "type": "string", "description": "The unique identifier of the created project.", "example": "proj_1234567890abcdef" }, "name": { "type": "string", "description": "The name of the created project.", "example": "My Legal Documents" }, "description": { "type": "string", "description": "The description of the project.", "example": "Project for storing legal case documents" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the project was created.", "example": "2024-01-15T10:30:00Z" }, "settings": { "type": "object", "properties": { "max_file_size": { "type": "integer", "description": "Maximum file size in bytes.", "example": 104857600 }, "max_files": { "type": "integer", "description": "Maximum number of files allowed in the project.", "example": 1000 }, "allowed_file_types": { "type": "array", "items": { "type": "string" }, "description": "Array of allowed file extensions.", "example": [ "pdf", "docx", "xlsx", "pptx", "txt", "rtf", "csv", "eml" ] } } }, "status": { "type": "string", "description": "The status of the project.", "example": "active" } } }, "ProjectMetadata": { "type": "object", "properties": { "project_id": { "type": "string", "description": "The project ID.", "example": "01936a5f-53a0-7b33-91aa-3bd2441ccc89" }, "file_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of file IDs in the project.", "example": [ "01936a5f-8289-703a-9962-42bf196ae611", "01936a5f-82a2-708a-9df6-91d72c1cd26d", "01936a5f-82de-7096-a7c2-021638a813ad" ] }, "file_names": { "type": "array", "items": { "type": "string" }, "description": "Array of file names in the project, corresponding to the file_ids array.", "example": [ "Employment Agreement - John Smith.pdf", "Merger Agreement - Acme Corp.docx", "Non-Disclosure Agreement - TechCo Inc.pdf" ] }, "file_count": { "type": "integer", "description": "Number of files in the project.", "example": 3 }, "max_file_count": { "type": "integer", "description": "Maximum number of files allowed in the project.", "example": 100000 }, "project_size": { "type": "string", "description": "Total size of files in bytes.", "example": "11015244" }, "max_project_size": { "type": "integer", "description": "Maximum storage size allowed in bytes.", "example": 107374182400 }, "review_table_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs of non-deleted review tables in this project. Use each ID with `GET /api/v1/vault/review_table/{review_table_id}` to fetch that table's metadata and file list, or as the first path parameter in the Get Review Table Row endpoint. Returns an empty array if the project has no review tables.", "example": [ 2365724, 2365725 ] } } }, "ReviewTable": { "type": "object", "properties": { "review_table_id": { "type": "integer", "description": "The unique integer ID of the review table.", "example": 2365724 }, "title": { "type": "string", "description": "The title of the review table.", "example": "Lease Review \u2013 Q1 2025" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp when the review table was created, or null if unavailable.", "example": "2025-01-10T09:00:00.000000" }, "file_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of file IDs associated with this review table. Pass a `review_table_id` and one of these `file_id` values to the Get Review Table Row endpoint to retrieve row-level data.", "example": [ "0199c5c1-50d9-7d60-93aa-cd65c3b7d5a9", "01936a5f-8289-703a-9962-42bf196ae611" ] } } }, "Project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the project", "example": "abcdef12-3456-7890-abcd-ef1234567890" }, "name": { "type": "string", "description": "The name of the project", "example": "Sample Contract Repository" }, "client_matter_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The associated client matter UUID (not the human-readable matter number)", "example": "11111111-2222-3333-4444-555555555555" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the project was created", "example": "2024-12-04T01:22:03.584677" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the project metadata was last updated", "example": "2025-03-25T14:49:45.612193" }, "project_updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the project content was last updated", "example": "2025-02-14T19:29:50.549982" }, "project_retained_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the vault project is retained. This date can be in the future. This field is only present in the response when it is non-null; it is omitted when the project has no retention timestamp set.", "example": "2026-02-14T19:29:50.549982" }, "creator_email": { "type": "string", "format": "email", "description": "Email of the user who created the project", "example": "user@example.com" }, "is_knowledge_base_project": { "type": "boolean", "description": "Whether this project is designated as a knowledge base", "example": false }, "files_count": { "type": "integer", "description": "Number of files in the project", "example": 4 }, "size_bytes": { "type": "integer", "description": "Total size of all files in bytes", "example": 5325148 }, "query_count": { "type": "integer", "description": "Number of queries made against this project", "example": 0 }, "sharing": { "type": "object", "description": "Sharing information for the project", "properties": { "user_count": { "type": "integer", "description": "Number of users the project is shared with", "example": 0 }, "user_shares": { "type": "array", "items": { "$ref": "#/components/schemas/ShareDetails" }, "description": "List of user share details" }, "workspace_count": { "type": "integer", "description": "Number of workspaces the project is shared with", "example": 1 }, "workspace_shares": { "type": "array", "items": { "$ref": "#/components/schemas/ShareDetails" }, "description": "List of workspace share details" } } } } }, "RecycleBinEntry": { "type": "object", "description": "A single recycle-bin entry. Top-level fields describe the recycle-bin row (when, who, and how the vault was deleted); `vault_project` embeds the deleted vault using the same project shape returned by `GET /api/v1/vault/workspace/projects`.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the recycle-bin entry", "example": "0197a1b2-3c4d-5e6f-7a8b-9c0d1e2f3a4b" }, "resource_id": { "type": "string", "format": "uuid", "description": "The unique identifier of the deleted resource (the vault project)", "example": "abcdef12-3456-7890-abcd-ef1234567890" }, "resource_type": { "type": "string", "description": "The type of the deleted resource (currently always `vault_project`)", "example": "vault_project" }, "recycle_bin_status": { "type": "string", "enum": [ "deleted" ], "description": "Recycle-bin status (always `deleted` for entries returned by this endpoint)", "example": "deleted" }, "deleted_at": { "type": "string", "format": "date-time", "description": "Timestamp when the vault was moved into the recycle bin", "example": "2026-07-15T18:42:10.512000Z" }, "recycle_bin_purged_scheduled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp 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 this timestamp: the purge is carried out by a periodic background sweep, so a vault can take up to 30 minutes after this timestamp passes to be fully purged.", "example": "2026-08-14T18:42:10.512000Z" }, "delete_source": { "type": "string", "enum": [ "customer_delete", "admin_delete", "retention_delete", "system_delete" ], "description": "How the delete was initiated", "example": "customer_delete" }, "deleted_source_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The identifier of the actor that initiated the delete, interpreted in the context of `delete_source`: a user ID for customer/admin deletes, a retention-policy ID for retention deletes. Null when the source did not record an actor.", "example": "12345678-1234-5678-1234-567812345678" }, "deleted_by_user_email": { "type": "string", "nullable": true, "description": "Email of the user who deleted the vault, populated when `delete_source` is `customer_delete` or `admin_delete`. Null for retention/system deletes or when the actor is unknown.", "example": "user@example.com" }, "vault_project": { "$ref": "#/components/schemas/Project" } }, "required": [ "id", "resource_id", "resource_type", "recycle_bin_status", "deleted_at", "delete_source", "vault_project" ] }, "ShareDetails": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When the share was created", "example": "2024-01-16T13:45:00.000000" }, "dest_user_email": { "type": "string", "format": "email", "description": "Email of the destination user (for user shares)", "example": "collaborator@example.com" }, "dest_user_id": { "type": "string", "format": "uuid", "description": "ID of the destination user (for user shares)", "example": "11111111-2222-3333-4444-555566667777" }, "dest_workspace_id": { "type": "integer", "description": "Destination workspace ID", "example": 2 }, "permission_level": { "type": "string", "enum": [ "VIEW", "EDIT", "ADMIN" ], "description": "Permission level for the share", "example": "VIEW" }, "src_user_id": { "type": "string", "format": "uuid", "description": "Source user ID who created the share", "example": "12345678-1234-5678-1234-567812345678" }, "src_workspace_id": { "type": "integer", "description": "Source workspace ID", "example": 1 }, "vault_folder_id": { "type": "string", "format": "uuid", "description": "The vault folder/project ID being shared", "example": "87654321-8765-4321-8765-432187654321" } } }, "FileDetails": { "type": "object", "properties": { "file_id": { "type": "string", "format": "uuid", "description": "The unique identifier of the file.", "example": "01936a5f-8289-703a-9962-42bf196ae611" }, "file_name": { "type": "string", "description": "The name of the file. Only present when the file is found.", "example": "Employment Agreement - John Smith.pdf" }, "processing_status": { "type": "string", "description": "The current processing status of the file. Only present when the file is found.", "enum": [ "uploaded", "processing", "ready_to_query", "ready_to_review", "recoverable_failure", "unrecoverable_failure" ], "example": "ready_to_query" }, "content_type": { "type": "string", "nullable": true, "description": "The MIME type of the file. Only present when the file is found.", "example": "application/pdf" }, "deleted_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the file was deleted, or null if not deleted. Only present when the file is found.", "example": null }, "error": { "type": "string", "description": "Error code indicating why the file could not be retrieved. Only present when the file is not found.", "example": "not_found" } }, "required": [ "file_id" ] }, "ProjectFile": { "type": "object", "description": "A single file as returned by `List Files in a Vault Project`. The shape is intentionally scoped to the public-API surface and does not expose internal File model fields.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the file.", "example": "018e38dc-8726-7bc2-af5d-bdd5d04c84ec" }, "name": { "type": "string", "description": "The display name of the file.", "example": "engagement_letter.pdf" }, "content_type": { "type": "string", "nullable": true, "description": "The MIME type of the file.", "example": "application/pdf" }, "processing_status": { "type": "string", "description": "The current processing status of the file. Returned as an uppercase identifier.", "enum": [ "UPLOADED", "PROCESSING", "READY_TO_QUERY", "READY_TO_REVIEW", "RECOVERABLE_FAILURE", "UNRECOVERABLE_FAILURE" ], "example": "READY_TO_QUERY" }, "size": { "type": "integer", "description": "Size of the file in bytes.", "example": 184320 }, "uploaded_at": { "type": "integer", "format": "int64", "description": "Upload time as a UTC Unix epoch timestamp in seconds.", "example": 1767225600 } }, "required": [ "id", "name", "processing_status", "size", "uploaded_at" ] }, "ProjectFilesPagination": { "type": "object", "description": "Cursor-pagination metadata for the `List Files in a Vault Project` response.", "properties": { "page_size": { "type": "integer", "description": "Number of files returned in this page. Equals the request's `limit` except on the final page.", "example": 20 }, "has_more": { "type": "boolean", "description": "`true` if at least one more page is available. When `false`, the walk is complete and `next_cursor` is `null`.", "example": true }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor to pass as the `cursor` query parameter on the next request. `null` when `has_more` is `false`. Do not parse or construct cursors client-side.", "example": "eyJsYXN0X2ZpbGVfaWQiOiAiMDE5OWM1YzEtNTBkOS03ZDYwLTkzYWEtY2Q2NWMzYjdkNWE5In0=" }, "total_count": { "type": "integer", "description": "Total number of files in the project matching the filter criteria (across all pages).", "example": 137 } }, "required": [ "page_size", "has_more", "total_count" ] }, "UploadResponse": { "type": "object", "properties": { "project_id": { "type": "string", "description": "The project ID." }, "file_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of file IDs that were added to the project." } } }, "VaultSemanticSearchRequest": { "type": "object", "description": "Request body for semantic search over a vault project. Returns relevant document chunks for the query; clients can pass these chunks to their own LLM. Access requires Vault API permission; contact Harvey for permissioning needs.", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "UUID of the vault project to search in" }, "query": { "type": "string", "description": "Natural language search query.", "minLength": 1 }, "include_file_names": { "type": "boolean", "default": false, "description": "When true, each chunk in the response includes a file_name field (display name of the source file, or null if the file was deleted after indexing). Omit or set to false for backward compatibility." } }, "required": [ "project_id", "query" ], "additionalProperties": false }, "VaultSemanticSearchChunk": { "type": "object", "description": "A single text chunk from semantic search results", "properties": { "file_id": { "type": "string", "format": "uuid", "description": "ID of the source file" }, "text": { "type": "string", "description": "Chunk text content" }, "chunk_id": { "type": "string", "description": "Chunk identifier (optional)" }, "chunk_idx": { "type": "integer", "description": "Chunk index within the file (optional)" }, "page_number": { "type": "integer", "description": "Page number in the source document (optional)" }, "start_idx": { "type": "integer", "description": "Start character index (optional)" }, "end_idx": { "type": "integer", "description": "End character index (optional)" }, "file_name": { "type": "string", "nullable": true, "description": "Display name of the source file. Only present when include_file_names was true in the request; null if the file was not found (e.g. deleted after indexing)." } }, "required": [ "file_id", "text" ] }, "VaultSemanticSearchResponse": { "type": "object", "description": "Response from semantic search", "properties": { "status": { "type": "string", "enum": [ "COMPLETED" ], "description": "Status of the operation" }, "data": { "type": "object", "properties": { "file_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Unique file IDs that had matching chunks (deduplicated)" }, "chunks": { "type": "array", "items": { "$ref": "#/components/schemas/VaultSemanticSearchChunk" }, "description": "Chunks ordered by relevance, with text and metadata" } }, "required": [ "file_ids", "chunks" ] } }, "required": [ "status", "data" ] } } }, "x-codeSamples": [ { "lang": "cURL", "label": "List Workspace Projects", "source": "curl -X GET \"https://api.harvey.ai/api/v1/vault/workspace/projects?page=1&per_page=20\" \\\n-H \"Authorization: Bearer \" \\\n-H \"Content-Type: application/json\"" }, { "lang": "cURL", "label": "List Workspace Projects (filtered and sorted)", "source": "curl -X GET \"https://api.harvey.ai/api/v1/vault/workspace/projects?page=1&per_page=20&name=acme&is_knowledge_base=false&created_after=1767225600&created_before=1775347200&sort_by=name&sort_order=asc\" \\\n-H \"Authorization: Bearer \" \\\n-H \"Content-Type: application/json\"" }, { "lang": "cURL", "label": "Create Project", "source": "curl -X POST \"https://api.harvey.ai/api/v1/vault/create_project\" \\\n-H \"Authorization: Bearer \" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"name\": \"My Legal Documents\",\n \"description\": \"Project for storing legal case documents\",\n \"settings\": {\n \"max_file_size\": 104857600,\n \"max_files\": 1000\n },\n \"client_matter_id\": \"11111111-2222-3333-4444-555555555555\"\n}'" }, { "lang": "cURL", "label": "Create Project (multipart form)", "source": "curl -X POST \"https://api.harvey.ai/api/v1/vault/create_project\" \\\n-H \"Authorization: Bearer \" \\\n-F \"name=My Legal Documents\" \\\n-F \"is_knowledge_base_project=false\" \\\n-F \"client_matter_id=11111111-2222-3333-4444-555555555555\"" }, { "lang": "cURL", "label": "Get Vault Project Metadata", "source": "curl -X GET \"https://api.harvey.ai/api/v1/vault/get_metadata/{project_id}\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\"" }, { "lang": "cURL", "label": "Upload Files to Project", "source": "curl -X POST \"https://api.harvey.ai/api/v1/vault/upload_files/{project_id}\" \\\n-H \"Authorization: Bearer \" \\\n-F \"files=@/path/to/document1.pdf\" \\\n-F \"files=@/path/to/document2.docx\" \\\n-F \"files=@/path/to/document3.xlsx\"" }, { "lang": "cURL", "label": "Get File Details", "source": "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\" \\\n-H \"Authorization: Bearer \"" }, { "lang": "cURL", "label": "Semantic Search", "source": "curl -X POST \"https://api.harvey.ai/api/v1/vault/semantic_search\" \\\n-H \"Authorization: Bearer \" \\\n-H \"Content-Type: application/json\" \\\n-d '{\"project_id\": \"12345678-1234-5678-1234-567812345678\", \"query\": \"What are the key terms of the agreement?\", \"include_file_names\": true}'" }, { "lang": "cURL", "label": "Delete File", "source": "curl -X DELETE \"https://api.harvey.ai/api/v1/vault/delete_file/{file_id}\" \\\n-H \"Authorization: Bearer \"" }, { "lang": "cURL", "label": "Delete Project", "source": "curl -X DELETE \"https://api.harvey.ai/api/v1/vault/delete_project/{project_id}\" \\\n-H \"Authorization: Bearer \" \\\n-H \"Accept: application/json\"" }, { "lang": "cURL", "label": "List Files in a Vault Project", "source": "curl -X GET \"https://api.harvey.ai/api/v1/vault/projects/{project_id}/files?limit=20&sort_by=uploaded_at&sort_order=desc\" \\\n-H \"Authorization: Bearer \"" }, { "lang": "cURL", "label": "List Files (filtered) and follow cursor", "source": "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&uploaded_after=1767225600&sort_by=size&sort_order=desc&limit=50\" \\\n-H \"Authorization: Bearer \"\n\n# Then pass next_cursor from the response back as the cursor param:\ncurl -X GET \"https://api.harvey.ai/api/v1/vault/projects/{project_id}/files?cursor=&limit=50\" \\\n-H \"Authorization: Bearer \"" }, { "lang": "cURL", "label": "List Project Users", "source": "curl -X GET \"https://api.harvey.ai/api/v1/vault/projects/{project_id}/users\" \\\n-H \"Authorization: Bearer \"" }, { "lang": "cURL", "label": "Update Project Users", "source": "curl -X POST \"https://api.harvey.ai/api/v1/vault/projects/{project_id}/users\" \\\n-H \"Authorization: Bearer \" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"users\": [\n {\"email\": \"admin@example.com\", \"access_level\": \"MANAGE\"},\n {\"email\": \"reviewer@example.com\", \"access_level\": \"READ\"}\n ]\n}'" }, { "lang": "cURL", "label": "Remove Project Users", "source": "curl -X DELETE \"https://api.harvey.ai/api/v1/vault/projects/{project_id}/users\" \\\n-H \"Authorization: Bearer \" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"user_ids\": [\n \"11111111-2222-3333-4444-555566667777\"\n ]\n}'" }, { "lang": "cURL", "label": "Get Review Table Metadata", "source": "curl -X GET \"https://api.harvey.ai/api/v1/vault/review_table/{review_table_id}\" \\\n-H \"Authorization: Bearer \"" }, { "lang": "cURL", "label": "Get Review Table Row", "source": "curl -X GET \"https://api.harvey.ai/api/v1/vault/get_row/{review_table_id}/{file_id}\" \\\n-H \"Authorization: Bearer \" \\\n-H \"Content-Type: application/json\"" } ] }