---
title: "Semantic search over entity content"
method: GET
path: "/api/v1/ackdb/entities/{entityId}/search"
tags: ["ackDB"]
---

# Semantic search over entity content

`GET /api/v1/ackdb/entities/{entityId}/search`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/ackdb/entities/{entityId}/search`
- Auth: HTTP bearer

Hybrid search (pgvector cosine similarity + BM25 keyword search) over an entity's embedded content chunks. Uses Reciprocal Rank Fusion (RRF) to combine results.

**Requires:** an embedding provider configured (`GEMINI_API_KEY` by default, or `OPENAI_API_KEY` as the fallback provider - see `EMBEDDING_PROVIDER`) and `npm run embed` to have processed payloads.
Returns 501 if semantic search is not configured.

## Path parameters

- `entityId` string, required

## Query parameters

- `q` string, required
- `limit` integer

## Response `200`

Ranked search results

- object
  - `data` object[], required
    - `source` string
    - `text` string
    - `score` number: RRF relevance score
    - `timestamp` string, date-time
    - `metadata` object
  - `query` string, required
  - `total` integer, required

## Other responses

- `404`: Entity not found
- `422`: Missing query parameter
- `501`: Semantic search not configured (no embedding provider - set GEMINI_API_KEY by default, or OPENAI_API_KEY for the fallback provider)

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)