> ## Documentation Index
> Fetch the complete documentation index at: https://developers.harvey.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantic search over a vault project

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

### Permissions

Requires `Vault API` and `Vault sharing` permissions.


## OpenAPI

````yaml /vault_api.json post /api/v1/vault/semantic_search
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
security: []
paths:
  /api/v1/vault/semantic_search:
    post:
      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.


        Requires 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: []
components:
  schemas:
    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
    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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````