---
title: "Perform semantic search"
method: POST
path: "/search"
tags: ["Semantic Search"]
---

# Perform semantic search

`POST /search`

Run a semantic search across your organization's knowledge base.
Matching is meaning-based, so relevant results surface even when
the wording differs from the query.

Use optional `filters` to narrow the scope:

- `filters.apps` — restrict to specific connector apps (for
  example Google Drive or Confluence).
- `filters.kb` — restrict to specific knowledge bases.

The response returns a `searchId` for the persisted search along
with ranked matches, each carrying a relevance score and the
source document's metadata. Past searches can be retrieved via
`GET /search`.

## Request body

- SemanticSearchRequest — Request body for performing semantic search across the enterprise knowledge base. **How Semantic Search Works:** 1. Query is converted to vector embeddings 2. Similar content is found using vector similarity 3. Results are ranked by relevance score 4. Matching chunks with metadata are returned **Filtering:** Use filters to narrow search scope to specific apps or knowledge bases.
  - `query` string, required — Natural language search query. The system understands semantic meaning, not just keywords.
  - `filters` Filters — App connector instance ids and knowledge-base / record-group ids that narrow retrieval for a turn. For **org assistant** chat streams, send explicit `apps` / `kb` lists. For **agent** chat streams, send explicit id lists, or **omit** `filters` (and `tools`) to let the service use the agent’s stored knowledge and tool configuration. Sending `{ "apps": [], "kb": [] }` on an agent stream means **no** knowledge sources for that turn (it is not “full org default”).
    - `apps` string[] — Connector instance ids to scope retrieval for this turn. Each element must be a UUID (connector instance id, record-group id, etc.) or the org knowledge-base collection sentinel `knowledgeBase_<orgId>` (pattern `knowledgeBase_[a-zA-Z0-9_-]+`). Gateway validation matches Zod `appOrKbIdSchema`.
    - `kb` string[] — Knowledge-base / record-group ids to scope retrieval for this turn. Each element uses the same accepted formats as `apps`: a UUID or `knowledgeBase_<orgId>` (pattern `knowledgeBase_[a-zA-Z0-9_-]+`).
  - `limit` integer — Maximum number of results to return

## Response `200`

Search ID plus retrieval payload (`searchResponse`) from the AI search service

- SemanticSearchExecuteResponse — Immediate POST `/search` response: persisted search id plus the raw retrieval payload. SDK-oriented modeling: named fields only at this level; dynamic-key maps inside `searchResponse` use `additionalProperties` with a `$ref` (e.g. `virtual_to_record_map`) rather than boolean `additionalProperties: true`, so generated clients retain typed values where possible.
  - `searchId` string, objectId, required
  - `searchResponse` SemanticSearchAiResponse, required — Payload returned by the AI retrieval service for a semantic search (embedded in `searchResponse`). Optional `virtual_to_record_map` maps each virtual record id (string key) to one resolved graph record document. Empty responses from the retrieval layer omit `virtual_to_record_map`; success payloads may include it alongside hits and records.
    - `searchResults` SemanticSearchHit[], required
      - `score` number, nullable
      - `citationType` string, nullable
      - `chunkIndex` integer, nullable
      - `metadata` SemanticSearchHitMetadata — Per-hit metadata after retrieval enrichment (record + vector context). Listed fields are the documented contract; Qdrant or pipeline updates may add more keys over time—extend this schema when new stable fields appear.
        - `orgId` string, nullable
        - `recordId` string, nullable
        - `virtualRecordId` string, nullable
        - `recordName` string, nullable
        - `recordType` string, nullable
        - `recordVersion` union
          - string
          - number
        - `origin` string, nullable
        - `connector` string, nullable
        - `connectorId` string, nullable
        - `connectorName` string, nullable
        - `blockText` string, nullable
        - `blockType` string, nullable — Block type for this hit. Common values: `text`, `image`, `table_row`, `table`, `record_summary` (whole-record semantic summary chunk — no block index).
        - `bounding_box` SemanticSearchBoundingBox[], nullable
          - `x` number
          - `y` number
        - `pageNum` integer[], nullable
        - `extension` string, nullable
        - `mimeType` string, nullable
        - `blockNum` number[], nullable
        - `chunkIndex` integer, nullable
        - `sheetName` string, nullable
        - `sheetNum` integer, nullable
        - `webUrl` string, nullable
        - `previewRenderable` boolean, nullable
        - `hideWeburl` boolean, nullable
        - `categories` string[], nullable
        - `departments` string[], nullable
        - `topics` string[], nullable
        - `languages` string[], nullable
        - `subcategoryLevel1` string, nullable
        - `subcategoryLevel2` string, nullable
        - `subcategoryLevel3` string, nullable
        - `score` number, nullable
        - `_id` string, nullable
        - `_collection_name` string, nullable
        - `blockIndex` integer, nullable
        - `blockId` string, nullable
        - `isBlock` boolean, nullable
        - `isBlockGroup` boolean, nullable
        - `isRecordSummary` boolean, nullable — Set to `true` by the indexing pipeline when this vector chunk represents a whole-record semantic summary rather than an individual block. When true, `blockIndex` is absent and `block_type` on the parent hit is `record_summary`.
        - `kbId` string, nullable — Knowledge base id merged from graph record during retrieval (when present).
        - `point_id` union — Qdrant point identifier attached during vector lookup (shape varies by deployment).
          - string
          - integer
          - number
      - `content` string, nullable
      - `virtual_record_id` string, nullable
      - `block_type` string, nullable — Block type for this hit. Common values: `text`, `image`, `table_row`, `table`, `record_summary` (whole-record semantic summary — `block_index` is `null` for these hits).
      - `block_index` integer, nullable
    - `records` SemanticSearchGraphRecord[], required
      - `_key` string, nullable
      - `_id` string, nullable
      - `_rev` string, nullable
      - `recordName` string, nullable
      - `externalRecordId` string, nullable
      - `recordType` string, nullable
      - `origin` string, nullable
      - `createdAtTimestamp` number, nullable
      - `connectorId` string, nullable
      - `orgId` string, nullable
      - `updatedAtTimestamp` number, nullable
      - `externalGroupId` string, nullable
      - `externalParentId` string, nullable
      - `externalRevisionId` string, nullable
      - `externalRootGroupId` string, nullable
      - `recordGroupId` string, nullable
      - `version` number, nullable
      - `connectorName` string, nullable
      - `mimeType` string, nullable
      - `webUrl` string, nullable
      - `lastSyncTimestamp` number, nullable
      - `sourceCreatedAtTimestamp` number, nullable
      - `sourceLastModifiedTimestamp` number, nullable
      - `isDeleted` boolean, nullable
      - `isArchived` boolean, nullable
      - `isVLMOcrProcessed` boolean, nullable
      - `deletedByUserId` string, nullable
      - `indexingStatus` string, nullable
      - `extractionStatus` string, nullable
      - `isLatestVersion` boolean, nullable
      - `isDirty` boolean, nullable
      - `reason` string, nullable
      - `lastIndexTimestamp` number, nullable
      - `lastExtractionTimestamp` number, nullable
      - `summaryDocumentId` string, nullable
      - `virtualRecordId` string, nullable
      - `previewRenderable` boolean, nullable
      - `isShared` boolean, nullable
      - `isDependentNode` boolean, nullable
      - `parentNodeId` string, nullable
      - `hideWeburl` boolean, nullable
      - `isInternal` boolean, nullable
      - `md5Checksum` string, nullable
      - `sizeInBytes` number, nullable
      - `definition` string, nullable
      - `sourceTables` string[], nullable
      - `rowCount` number, nullable
    - `status` string, required
    - `status_code` integer, required
    - `message` string, required
    - `appliedFilters` SemanticSearchAppliedFilters — Present when KB filters were applied to the search request.
      - `kb` string[], required
      - `kb_count` integer, required
    - `virtual_to_record_map` object — Maps virtual record id (object property name) to the accessible graph record document for that id.

## Other responses

- `400` — Invalid request — `query` is missing, empty, or the request body fails validation.
- `401` — Missing or invalid bearer token.
- `403` — Bearer token lacks the `semantic:write` scope.
- `404` — A referenced knowledge base or app filter could not be resolved.
- `500` — Unexpected server error while executing the search, or the upstream AI search service was unreachable.
- `502` — The upstream AI search service returned an invalid response.
- `503` — The upstream AI search service is temporarily unavailable.
- `504` — The upstream AI search service timed out before returning a response.

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)