---
title: "Semantic search over a vault project"
method: POST
path: "/api/v1/vault/semantic_search"
tags: ["Vault"]
---

# Semantic search over a vault project

`POST /api/v1/vault/semantic_search`

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.

Requires vault sharing to be enabled.

## Request body

- VaultSemanticSearchRequest — 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.
  - `project_id` string, uuid, required — UUID of the vault project to search in
  - `query` string, required — Natural language search query.
  - `include_file_names` boolean — 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.

## Response `200`

Search completed successfully

- VaultSemanticSearchResponse — Response from semantic search
  - `status` 'COMPLETED', required — Status of the operation
  - `data` object, required
    - `file_ids` string[], required — Unique file IDs that had matching chunks (deduplicated)
    - `chunks` VaultSemanticSearchChunk[], required — Chunks ordered by relevance, with text and metadata
      - `file_id` string, uuid, required — ID of the source file
      - `text` string, required — Chunk text content
      - `chunk_id` string — Chunk identifier (optional)
      - `chunk_idx` integer — Chunk index within the file (optional)
      - `page_number` integer — Page number in the source document (optional)
      - `start_idx` integer — Start character index (optional)
      - `end_idx` integer — End character index (optional)
      - `file_name` string, nullable — 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).

## Other responses

- `400` — Bad request - Missing or invalid project_id or query
- `401` — Unauthorized - Invalid or missing API token
- `403` — Forbidden - User does not have access to the Vault API or to the project
- `500` — Internal server error

---

[API](https://skmtc.dev/harvey/apis/harvey-client-matter-api.md) · [All operations](https://skmtc.dev/harvey/apis/harvey-client-matter-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/harvey/harvey-client-matter-api/revisions/4a9e0925d49e/schema)