Query API — Direct Knowledge Base Search Endpoint

The Query API gives you direct, low-level access to your knowledge base’s search engine — without routing through an AI agent. Instead of receiving a generated reply, you get back raw content chunks with relevance scores, giving you full control over how results are presented and processed. This makes the Query API the right choice when you are building a custom search UI, populating autocomplete suggestions, or integrating knowledge base content into a system that already handles its own response generation.

POST /v1/query

Search across all indexed sources in your knowledge base and return the most relevant content chunks. You can control the number of results, the search strategy, and optionally restrict the search to a specific subset of sources.

Request Body

string

required

The search query. Write queries in natural language for semantic or hybrid searches, or use keywords and phrases for keyword searches.

integer

default:"5"

The maximum number of results to return. Minimum 1, maximum 20.

string

default:"hybrid"

The search strategy to use. One of semantic, keyword, or hybrid. See Choosing a Search Type below for guidance on which to use.

array

An optional array of source IDs to restrict the search to specific content sources. When omitted, the query runs across all indexed sources. For example: ["src_abc123", "src_def456"].

number

An optional minimum relevance score threshold between 0.0 and 1.0. Results with a score below this value are excluded from the response. Use this to filter out low-quality matches. A value of 0.7 or higher returns only high-confidence results.

Example Request

curl -X POST https://api.beenossolutions.com/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the cancellation policy?",
    "limit": 3,
    "search_type": "hybrid"
  }'

Example Response

{
  "data": {
    "results": [
      {
        "id": "chunk_abc123",
        "source_id": "src_xyz789",
        "source_name": "FAQ Document",
        "text": "You can cancel your subscription at any time from the billing page...",
        "score": 0.92
      }
    ],
    "total": 3
  },
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Response Fields

array

An array of matching content chunks ordered by relevance score, highest first.

Show Result object fields

string

The unique ID of this content chunk.

string

The ID of the parent source document that this chunk belongs to.

string

The human-readable name of the parent source document.

string

The matching text excerpt from the source. This is the raw content — your application is responsible for rendering or summarizing it.

number

A relevance score between 0.0 and 1.0 indicating how closely this chunk matches the query. Higher is more relevant.

integer

The total number of results returned in this response. This reflects the actual count after any min_score filtering is applied, and will be less than or equal to the limit you specified.

Choosing a Search Type

Select the search strategy that best fits your query patterns and content type.

Semantic search

Semantic search converts your query into a vector embedding and finds content chunks that are conceptually similar, even when they use different words. Use semantic search when you expect users to phrase queries in natural language or when synonyms and paraphrasing are common. For example, a semantic search for “cancel my plan” will match content about “subscription termination” even though the exact words differ.

{ "query": "How do I cancel my plan?", "search_type": "semantic" }

Keyword search

Keyword search performs traditional full-text matching against the indexed content. Use keyword search when precision matters — for example, when searching for specific product names, error codes, or unique identifiers that must appear verbatim in the results.

{ "query": "ERR_PAYMENT_DECLINED", "search_type": "keyword" }

Hybrid search (recommended)

Hybrid search combines semantic and keyword strategies, merging their result sets and re-ranking by a blended relevance score. This gives you the recall benefits of semantic search alongside the precision of keyword matching, making it the best default choice for most use cases.

{ "query": "cancellation policy refund", "search_type": "hybrid" }

Filtering by Source

To restrict a query to specific content sources, pass an array of source IDs in the source_ids field. This is useful when your knowledge base contains content from multiple teams or products and you want search results to stay within a defined scope.

curl -X POST https://api.beenossolutions.com/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "refund processing time",
    "limit": 5,
    "search_type": "hybrid",
    "source_ids": ["src_billing123", "src_faq456"]
  }'

Retrieve source IDs from the Knowledge Base API using the GET /v1/knowledge-base/sources endpoint.

The Query API is a powerful building block for custom experiences. Use it to power a search bar in your help center, populate an autocomplete dropdown as users type, or pre-fetch relevant context before passing it to your own language model pipeline. Pair it with min_score: 0.75 to ensure only high-confidence results surface in user-facing interfaces.

Overview

Endpoints

Query API — Direct Knowledge Base Search Endpoint

POST /v1/query

Request Body

Example Request

Example Response

Response Fields

Choosing a Search Type

Filtering by Source

​POST /v1/query

​Request Body

​Example Request

​Example Response

​Response Fields

​Choosing a Search Type

​Filtering by Source

POST /v1/query

Request Body

Example Request

Example Response

Response Fields

Choosing a Search Type

Filtering by Source