> ## Documentation Index
> Fetch the complete documentation index at: https://guide.beenos-solutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query API — Direct Knowledge Base Search Endpoint

> Use POST /v1/query to run semantic, keyword, or hybrid searches across your Beenos Solutions knowledge base and retrieve relevance-scored content chunks.

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

<ParamField body="query" type="string" required>
  The search query. Write queries in natural language for semantic or hybrid searches, or use keywords and phrases for keyword searches.
</ParamField>

<ParamField body="limit" type="integer" default="5">
  The maximum number of results to return. Minimum `1`, maximum `20`.
</ParamField>

<ParamField body="search_type" type="string" default="hybrid">
  The search strategy to use. One of `semantic`, `keyword`, or `hybrid`. See [Choosing a Search Type](#choosing-a-search-type) below for guidance on which to use.
</ParamField>

<ParamField body="source_ids" type="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"]`.
</ParamField>

<ParamField body="min_score" type="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.
</ParamField>

#### Example Request

```bash theme={null}
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

```json theme={null}
{
  "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

<ResponseField name="results" type="array">
  An array of matching content chunks ordered by relevance score, highest first.

  <Expandable title="Result object fields">
    <ResponseField name="id" type="string">
      The unique ID of this content chunk.
    </ResponseField>

    <ResponseField name="source_id" type="string">
      The ID of the parent source document that this chunk belongs to.
    </ResponseField>

    <ResponseField name="source_name" type="string">
      The human-readable name of the parent source document.
    </ResponseField>

    <ResponseField name="text" type="string">
      The matching text excerpt from the source. This is the raw content — your application is responsible for rendering or summarizing it.
    </ResponseField>

    <ResponseField name="score" type="number">
      A relevance score between `0.0` and `1.0` indicating how closely this chunk matches the query. Higher is more relevant.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="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.
</ResponseField>

***

## Choosing a Search Type

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

<AccordionGroup>
  <Accordion title="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.

    ```json theme={null}
    { "query": "How do I cancel my plan?", "search_type": "semantic" }
    ```
  </Accordion>

  <Accordion title="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.

    ```json theme={null}
    { "query": "ERR_PAYMENT_DECLINED", "search_type": "keyword" }
    ```
  </Accordion>

  <Accordion title="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.

    ```json theme={null}
    { "query": "cancellation policy refund", "search_type": "hybrid" }
    ```
  </Accordion>
</AccordionGroup>

***

## 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.

```bash theme={null}
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](/api-reference/knowledge-base) using the `GET /v1/knowledge-base/sources` endpoint.

<Tip>
  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.
</Tip>