External Knowledge Bases

To connect an external Knowledge Base, open Knowledge Bases, click Knowledge, and select External Knowledge Base. The Knowledge Base is created in the selected Project.

Create menu on the Knowledge Bases page listing Knowledge Base and External Knowledge Base, with External Knowledge Base selected. — Choose External Knowledge Base when connecting a Knowledge Base.

The Connect External Knowledge Base modal opens.

Connect External Knowledge Base modal with Key, Description, Name, API URL, API Key, and Path fields, and Cancel and Connect actions. — Connect External Knowledge Base modal.

Field	Required	Description	Example
Key	Yes	Unique identifier, alphanumeric with hyphens and underscores.	`external_kb`
Description	No	Description of the knowledge base.	`External Knowledge Base`
Name	No	Display name.	`External Knowledge Base Name`
API URL	Yes	HTTPS URL Orq.ai calls to search the knowledge base.	`https://api.example.org/search`
API Key	Yes	Authentication key. Orq.ai sends it as `Authorization: Bearer <API_KEY>`.	`<API_KEY>`
Path	Yes	Folder that stores the knowledge base. Select Browse to pick a location.	`Demo`

Orq.ai includes the API Key in the Authorization: Bearer <API_KEY> header when calling your endpoint.

API keys are encrypted using workspace-specific keys (AES-256-GCM).

Select Connect to finalize.

API Payloads

Example payloads for the request and response expected from your external API:

Request Payload

{
  "query": "<string>",
  "top_k": 50,
  "threshold": 0.5,
  "filter_by": {},
  "search_options": {
    "include_vectors": true,
    "include_metadata": true,
    "include_scores": true
  }
}

Response Payload

{
  "matches": [
    {
      "id": "<string>",
      "text": "<string>",
      "vector": [123],
      "metadata": {},
      "scores": {
        "rerank_score": 123,
        "search_score": 123
      }
    }
  ]
}

The API must respond like a standard Knowledge Base search. See our Search API for the expected payload format.

Example Implementations

Python Implementation

An Example Python Server for External Knowledge Base

Get the Code

Clone the Python example Server

Install Dependencies

pip install -r requirements.txt

Run the Server

uvicorn main:app --reload

Test the API

The API is running at http://localhost:8000Dynamic Documentation is available at http://localhost:8000/docs

Node.js Implementation

An Example Node Server for External Knowledge Base

Get the Code

Clone the Node example Server

Install Dependencies

npm install

Run the Server

npm run dev

Test the API

The API is running at http://localhost:8000Dynamic Documentation is available at http://localhost:8000/doc

Integrate Vector Database Providers

Orq.ai supports providers like Weaviate and Pinecone, as both platforms expose REST APIs that conform to the expected payload format.

Show Weaviate

Configuration in Orq.ai:

API URL: https://your-cluster.weaviate.cloud/v1/graphql
API Key: Your Weaviate API key

Show Pinecone

Configuration in Orq.ai:

API URL: https://$INDEX_HOST/records/namespaces/$NAMESPACE/search
API Key: Your Pinecone API key

Troubleshoot Common Errors

Scenario	Error Message
HTTP instead of HTTPS	`external knowledge base URL must use HTTPS protocol`
Local/private IP	`external knowledge base URL cannot point to local network`
API unreachable	`failed to verify external knowledge base connectivity; tried: <endpoints>`
API timeout (>50s)	`External API request timed out`

Cannot connect to external API

Verify your API endpoint is publicly accessible via HTTPS.
Check your API logs for incoming requests from Orq.ai IP addresses.
Verify your firewall/security groups allow inbound HTTPS traffic.

API key authentication failing

Verify the API key is correct and has not expired.
Check that your API expects Bearer authentication in the Authorization header.
Confirm your API key has the necessary permissions to perform searches.

No results returned or poor quality results

Verify your API returns the expected response format (see Response Payload above).
Check that scores.search_score values are between 0 and 1.
Test with different threshold values (lower threshold = more results).
If using reranking, ensure both search_score and rerank_score are provided.
Verify your external vector database has sufficient indexed documents.

Slow response times

Monitor your external API response times.
Consider implementing caching for frequently searched queries.
Optimize your vector database indexes.
Check if your external API is rate limiting requests.

Configure your External Knowledge Base

Datasource configuration is not accessible within External Knowledge Bases, as data is hosted outside of Orq.ai.

The available configurations are:

Agentic RAG
Search mode: Hybrid, Vector, or Full text
Search retrieval parameters: Chunk Limit, Search Threshold
Rerank Model

For detailed configuration options, see Agentic RAG, Search Modes, and Rerank Model on the Knowledge Bases page. These settings apply to both internal and external Knowledge Bases.

Your External Knowledge Base is connected:

Use it just like any other Knowledge Base. See Search a Knowledge Base.
Your knowledge base can also be used with Agents. See Connect Knowledge Bases.
Your API is called at runtime when the model needs to perform a search.

Overview

Managed Agents

Context Management

Test & Evaluate

Chat

API Payloads

Example Implementations

Integrate Vector Database Providers

Troubleshoot Common Errors

Configure your External Knowledge Base

​API Payloads

​Example Implementations

​Integrate Vector Database Providers

​Troubleshoot Common Errors

​Configure your External Knowledge Base

API Payloads

Example Implementations

Integrate Vector Database Providers

Troubleshoot Common Errors

Configure your External Knowledge Base