Skip to main content
POST
/
v1
/
knowledge-base
/
search
Semantic search across knowledge bases
curl --request POST \
  --url https://api-sandbox.featherhq.com/v1/knowledge-base/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "query": "<string>",
  "kb_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "rerank": false,
  "limit": 30,
  "prefer_draft": false,
  "version_overrides": {},
  "alpha": 0.5
}
'
{
  "results": [
    {
      "chunk_id": "<string>",
      "kb_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "document_title": "<string>",
      "source_type": "<string>",
      "content": "<string>",
      "score": 123,
      "chunk_index": 123,
      "version_id": "",
      "position": {
        "start_char": 1,
        "end_char": 1,
        "type": "text"
      },
      "sensitivity": "<string>",
      "sensitivity_level": 123,
      "pii_status": "",
      "pii_sensitivity": "",
      "pii_coverage_status": ""
    }
  ],
  "total_results": 123,
  "grouped_results": [
    {
      "embedding_model": "<string>",
      "embedding_dimensions": 123,
      "kb_ids": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "results": [
        {
          "chunk_id": "<string>",
          "kb_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "document_title": "<string>",
          "source_type": "<string>",
          "content": "<string>",
          "score": 123,
          "chunk_index": 123,
          "version_id": "",
          "position": {
            "start_char": 1,
            "end_char": 1,
            "type": "text"
          },
          "sensitivity": "<string>",
          "sensitivity_level": 123,
          "pii_status": "",
          "pii_sensitivity": "",
          "pii_coverage_status": ""
        }
      ]
    }
  ],
  "answerability": {
    "raw_top_score": 123
  }
}

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
query
string
required
​
kb_ids
string<uuid>[]
required
Minimum array length: 1
​
rerank
boolean
default:false

Request semantic reranking of the candidate set. For mixed embedding spaces, the service may still rerank automatically when Cohere is configured because raw vector scores are not comparable across spaces.

​
limit
integer
default:30
Required range: 1 <= x <= 100
​
prefer_draft
boolean
default:false
​
version_overrides
Version Overrides · object
​
alpha
number
default:0.5

Hybrid search weighting between dense and sparse vectors. alpha=1.0 is dense-only, alpha=0.5 weights both equally. Minimum is 0.1: sparse-dominant queries on this hybrid index starve dense signal without materially improving recall, and pure sparse (alpha=0.0) sends a degenerate all-zero dense vector that Pinecone rejects.

Required range: 0.1 <= x <= 1

Response

Successful Response

​
results
SearchResult · object[]
required
​
total_results
integer
required

Total candidate count before the flat results list is truncated by limit.

​
ranking_mode
enum<string>
required

global_score means one embedding space ranked by raw vector score; reranked means a text reranker determined final ordering; grouped_unranked means mixed embedding spaces were returned as separate groups.

Available options:
global_score,
reranked,
grouped_unranked
​
grouped_results
SearchResultGroup · object[] | null

Present only when mixed embedding spaces were searched without reranking. In that case the response is grouped by embedding space instead of pretending there is one globally ranked list.

​
answerability
SearchAnswerability · object

Retrieval-confidence verdict for this search (ENG-671). Present only when the answerability gate is enabled (shadow/enforce) for the org; null when the gate is off. The public search API returns the verdict as DATA only — chunk suppression is the agent-path behavior and never applies to this endpoint.