Search - BeforeQuery

Run hybrid search over a project’s knowledge base: vector similarity and full-text ranking fused with Reciprocal Rank Fusion (RRF).

POST https://api.agents.beforequery.com/api/v1/public/projects/:projectId/search

Auth: client key.

Request body

Field	Type	Required	Description
`query`	`string`	Yes	Search query
`limit`	`number`	No	Max results
`group_ids`	`string[]`	No	Scope to source groups; intersected with the key’s `allowed_groups` (403 if outside the project or allowed set)

curl https://api.agents.beforequery.com/api/v1/public/projects/proj_xxx/search \
  -H "X-Client-Key: bq_pk_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "configure oauth", "limit": 5}'

Response

Top chunks with relevance scores and source document metadata:

{
  "results": [
    {
      "chunk_id": "chk_uuid",
      "content": "To configure OAuth, first register your application ...",
      "score": 0.87,
      "document": {
        "id": "doc_uuid",
        "url": "https://docs.example.com/auth/oauth",
        "title": "OAuth Configuration"
      },
      "heading_path": ["Authentication", "OAuth"]
    }
  ]
}

heading_path gives the section breadcrumb — useful for rendering results as Authentication > OAuth.

How ranking works

Two retrieval arms run over every chunk and are fused:

Vector — cosine similarity over embeddings (semantic matches, paraphrases).
Keyword — full-text ranking (exact terms, identifiers, error codes).

rrf_score(chunk) = Σ_arms 1 / (60 + rank_in_arm)

Optional server-side enhancements (configured per deployment): LLM query rewrite/expansion and listwise re-ranking of the top candidates — both degrade gracefully to plain hybrid search.

Notes

Restricted documents are excluded.
Use search for “find the page” UX (instant results as you type); use chat for synthesized answers.

​Request body

​Response

​How ranking works

​Notes

Request body

Response

How ranking works

Notes