---
title: "Semantic search across collections"
method: POST
path: "/v1/rag/query"
tags: ["RAG"]
---

# Semantic search across collections

`POST /v1/rag/query`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/rag/query`
- Auth: HTTP bearer

## Request body

- RagQueryRequest
  - `query` string, required
  - `collectionIds` string[], required
  - `topK` integer
  - `threshold` number
  - `debug` boolean
  - `hybrid` boolean: Enable BM25 + vector hybrid search
  - `mediaTypes` string[]: Filter results by media type. Omit for all types.
  - `maxContextChars` integer: Max characters for enriched prompt. Lowest-scored chunks truncated when exceeded.

## Response `200`

Search results with enriched prompt

- RagQueryResponse
  - `results` object[], required
    - `text` string, required
    - `score` number, required
    - `sourceFile` string, required
    - `chunkIndex` integer, required
    - `collectionId` string, required
    - `mediaType` 'text' | 'image'
    - `debug` object
      - `chunkId` string
      - `fullText` string
      - `dimensions` integer
      - `collectionName` string
  - `enrichedPrompt` string, required
  - `debug` object
    - `queryEmbeddingTimeMs` number
    - `searchTimeMs` number
    - `totalChunksSearched` integer
    - `collectionsQueried` integer
    - `bm25TimeMs` number
    - `retrievalMode` string

## Other responses

- `400`: Invalid request

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)