# Query the knowledge base

`POST https://api.chat-data.com/api/v2/query-knowledge-base/{chatbotId}`

Canonical: https://www.chat-data.com/api-reference/query-knowledge-base

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

This operation fetches segments pertinent to generating responses. Designed for seamless chatbot integration with the GPTs store, this API endpoint allows users to supply relevant document fragments to the GPTs. As with the `/get-confidence-score` endpoint, results are cached by query for efficiency.

**Credit Cost:** Each query costs **0.5 message credits**. If reranking runs, the total cost is **1.0 message credit** (0.5 base + 0.5 reranking); a cached result costs 0.5 even with reranking enabled. Requests are rejected if the available credits are insufficient.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| chatbotId | path | string | yes | The unique identifier allocated to the chatbot. |

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| query | string | yes | The text used to search the knowledge base by vector (cosine) similarity. |
| count | number | no | The minimum number of context segments to select when available. More are added until a minimum token budget is met, then the list is trimmed to a maximum token budget, so the result can hold more or fewer. Only segments with a positive cosine similarity to the query are returned. |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/query-knowledge-base/6650f1c2a9e4b83d2c7a1f05' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "What are your opening hours?"
}'
```

## Example response (200)

```json
[
  {
    "source": "https://www.example.com/support/opening-hours",
    "type": "website",
    "snippet": "Our support team is available Monday to Friday, 9am to 6pm EST. Outside these hours you can email support@example.com.",
    "relavant_score": "0.87"
  }
]
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Successful response. The body is a JSON array of matching chunks, without a `status` field. |
| 400 | The query could not be run. For example: the chatbot does not use the `custom-data-upload` model, `query` is missing or empty, the workspace has run out of message credits, or the chatbot has reached its credit limit. |
| 401 | Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which. |
| 403 | The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. |
| 429 | The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying. |