Skip to main content
External Knowledge Base lets you search documents without needing to upload them in Orq.ai.
You can also manage your Knowledge Base and documents fully on orq, to do so, see Creating an Internal Knowledge Base.

​
Creating an External Knowledge Base

To create an external Knowledge Base, choose the + button on the desired Project.
External Knowledge Base Create Pn

Choose `External` when creating your Knowledge Base

The following modal opens to configure an external knowledge base.
Configure External Knowledge Base Pn

Configuration Modal.

Configuration
FieldDescriptionExample
KeyUnique Identifier, alphanumeric with hyphens/underscoreexternal_kb
DescriptionDescriptionExternal Knowledge Base
NameDisplay NameExternal Knowledge Base Name
API URLURL to search knowledge base, must be HTTPShttps://api.example.org/search
API KeyAuthentication API key to the previously API URL. Orq will use Bearer Authentication Header to call your API.<API_KEY>
orq.ai will include 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 Create to finalize the creation of your external Knowledge Base.

​
API Payloads

Here are example payloads for request and response expected from your API. 
{
  "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
  }
}

{
  "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, to learn more about the expected payload, see our Search API.

​
Example Implementation for an External API

We’ve created example implementation for External Knowledge Base API.

Get the Code

Clone the Python example Server

Install Dependencies

# Install dependencies
pip install -r requirements.txt

Run the Server

# Run the server
uvicorn main:app --reload

Test the API

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

Get the Code

Clone the Node example Server

Install Dependencies

# Install dependencies
npm install

Run the Server

# Run the server
npm run dev

Test the API

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

​
Integrating Vector Database Providers

We support providers like Weaviate and Pinecone, as both platforms expose REST APIs that conform to the expected payload format documented above. Integration Examples

​
Common Errors and Troubleshooting

ScenarioError 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”
Problem: Cannot connect to external API
  1. Verify your API endpoint is publicly accessible via HTTPS
  2. Check your API logs for incoming requests from orq.ai IP addresses
  3. Verify your firewall/security groups allow inbound HTTPS traffic
Problem: API key authentication failing
  1. Verify the API key is correct and has not expired
  2. Check that your API expects Bearer authentication in the Authorization header
  3. Confirm your API key has the necessary permissions to perform searches
Problem: No results returned or poor quality results
  1. Verify your API returns the expected response format (see Response Payload above)
  2. Check that scores.search_score values are between 0 and 1
  3. Test with different threshold values (lower threshold = more results)
  4. If using reranking, ensure both search_score and rerank_score are provided
  5. Verify your external vector database has sufficient indexed documents
Problem: Slow response times
  1. Monitor your external API response times
  2. Consider implementing caching for frequently searched queries
  3. Optimize your vector database indexes
  4. Check if your external API is rate limiting requests

​
Configuring your External Knowledge Base

Datasource configuration is not accessible within External Knowledge base, as data is hosted outside of Orq.ai.
The available configurations are:
To learn more about the configuration possibilities of Knowledge Bases in Orq, see Creating an Internal Knowledge Base.
Your External Knowledge Base is created: