---
title: "Vector search within a book version"
method: GET
path: "/v1/vector-search/{bookId}/{versionId}"
tags: ["V1"]
---

# Vector search within a book version

`GET /v1/vector-search/{bookId}/{versionId}`

Perform a vector (semantic) search within a specific book version. Requires bearer token authentication.

## Path parameters

- `bookId` string, required
- `versionId` string, required

## Query parameters

- `q` string, required
- `include_chapters` 'true' | 'false'
- `include_details` 'true' | 'false'
- `page` integer
- `limit` integer

## Response `200`

Vector search results retrieved successfully

- V1SearchResponse
  - `total` integer, required — Total number of matching results
  - `totalPages` integer, required — Total number of pages
  - `perPage` integer, required — Results per page
  - `currentPage` integer, required — Current page number
  - `hasNextPage` boolean, required — Whether there is a next page
  - `hasPreviousPage` boolean, required — Whether there is a previous page
  - `results` V1SearchResult[], required
    - `score` number — Relevance score of the result
    - `versionId` string — The version ID of the matched book
    - `node` object
      - `text` string — The matched text content (omitted when highlights are present for text search)
      - `highlights` object[] — Highlighted text snippets (only present for text search results)
      - `metadata` object
        - `bookId` string — The ID of the book
        - `page` integer — Page number in the book
        - `vol` string — Volume number
        - `chapters` object[] — Chapter information (only present when include_chapters=true)
    - `book` object — Book details (only present when include_details=true)
      - `id` string
      - `slug` string
      - `primaryName` string
      - `secondaryName` string
      - `author` object
        - `id` string
        - `slug` string
        - `primaryName` string
        - `secondaryName` string
        - `year` integer

## Other responses

- `401` — Unauthorized - invalid or missing bearer token

---

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