External Knowledge Bases

To connect to an external Knowledge Base, click the button on the desired Project and select Knowledge Base > External.

Choose External when connecting your Knowledge Base

The following modal opens to configure the external knowledge base.

Connect External Kb — Configuration Modal

Field	Description	Example
Key	Unique identifier, alphanumeric with hyphens/underscores	`external_kb`
Description	Description of the knowledge base	`External Knowledge Base`
Name	Display name	`External Knowledge Base Name`
API URL	URL to search the knowledge base, must be HTTPS	`https://api.example.org/search`
API Key	Authentication API key. Orq.ai will use Bearer Authentication to call your API.	`<API_KEY>`

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
  },
  "rerank_config": {
    "model": "cohere/rerank-multilingual-v3.0",
    "threshold": 0,
    "top_k": 10
  }
}

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”
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 retrieval parameters: Chunk Limit, Search Threshold
Rerank Model

For detailed configuration options, see Embedding Models, Agentic RAG, Search Modes, and Rerank Model on the Knowledge Bases page. All 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

AI 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