Build a customer support knowledge search layer that combines queries against your own documentation site with open web search to find answers for support tickets. When a customer asks a question, the system first searches your docs using a site-scoped query, then falls back to general web search if no relevant docs are found. This two-tier approach ensures accurate answers from official sources while still handling edge cases and third-party integration questions. Scavio's API makes both tiers a single endpoint call with different query formats.
Prerequisites
- Python 3.8+ or Node.js 18+ installed
- requests library (Python) or built-in fetch (JS)
- A Scavio API key from scavio.dev
- Your product's documentation URL (e.g., docs.yourproduct.com)
Walkthrough
Step 1: Configure the two-tier search
Set up the docs-first search strategy with your documentation domain and a fallback to general web search.
Python
import os, requests
API_KEY = os.environ['SCAVIO_API_KEY']
DOCS_DOMAIN = 'docs.yourproduct.com'
def search_docs(query: str) -> list:
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': API_KEY},
json={'platform': 'google', 'query': f'{query} site:{DOCS_DOMAIN}'}, timeout=10)
return resp.json().get('organic_results', [])
def search_web(query: str) -> list:
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': API_KEY},
json={'platform': 'google', 'query': query}, timeout=10)
return resp.json().get('organic_results', [])Step 2: Build the tiered search function
Try docs first; if no results or insufficient results, fall back to web search. Tag results with their source.
Python
def knowledge_search(query: str, min_docs: int = 1) -> dict:
docs_results = search_docs(query)
if len(docs_results) >= min_docs:
return {
'source': 'docs',
'results': [{'title': r['title'], 'url': r['link'], 'snippet': r.get('snippet', '')} for r in docs_results[:3]]
}
web_results = search_web(query)
return {
'source': 'web',
'results': [{'title': r['title'], 'url': r['link'], 'snippet': r.get('snippet', '')} for r in web_results[:3]]
}Step 3: Format results for the support agent
Convert search results into a context block that the support agent can use to draft a response.
Python
def format_support_context(search_result: dict) -> str:
source_label = 'Official docs' if search_result['source'] == 'docs' else 'Web search'
lines = [f'Source: {source_label}', '']
for r in search_result['results']:
lines.append(f"- {r['title']}")
lines.append(f" {r['snippet']}")
lines.append(f" URL: {r['url']}")
lines.append('')
return '\n'.join(lines)
result = knowledge_search('how to set up webhooks')
print(format_support_context(result))Step 4: Handle ticket batches
Process multiple support tickets in batch, running the knowledge search for each and collecting the results.
Python
def process_tickets(tickets: list) -> list:
responses = []
for ticket in tickets:
search_result = knowledge_search(ticket['question'])
context = format_support_context(search_result)
responses.append({
'ticket_id': ticket['id'],
'question': ticket['question'],
'source': search_result['source'],
'context': context,
})
print(f"Ticket {ticket['id']}: answered from {search_result['source']}")
return responses
tickets = [
{'id': '001', 'question': 'how to set up webhooks'},
{'id': '002', 'question': 'SAML SSO configuration'},
{'id': '003', 'question': 'error 429 rate limit exceeded'},
]
process_tickets(tickets)Python Example
Python
import requests, os
H = {'x-api-key': os.environ['SCAVIO_API_KEY']}
def knowledge_search(query, docs_domain):
docs = requests.post('https://api.scavio.dev/api/v1/search', headers=H,
json={'platform': 'google', 'query': f'{query} site:{docs_domain}'}).json()
results = docs.get('organic_results', [])
if results:
return {'source': 'docs', 'results': results[:3]}
web = requests.post('https://api.scavio.dev/api/v1/search', headers=H,
json={'platform': 'google', 'query': query}).json()
return {'source': 'web', 'results': web.get('organic_results', [])[:3]}
print(knowledge_search('webhook setup', 'docs.example.com'))JavaScript Example
JavaScript
const H = {'x-api-key': process.env.SCAVIO_API_KEY, 'Content-Type': 'application/json'};
async function knowledgeSearch(query, docsDomain) {
let r = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST', headers: H,
body: JSON.stringify({platform: 'google', query: `${query} site:${docsDomain}`})
});
let results = (await r.json()).organic_results || [];
if (results.length) return {source: 'docs', results: results.slice(0, 3)};
r = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST', headers: H, body: JSON.stringify({platform: 'google', query})
});
results = (await r.json()).organic_results || [];
return {source: 'web', results: results.slice(0, 3)};
}
knowledgeSearch('webhook setup', 'docs.example.com').then(console.log);Expected Output
JSON
A two-tier knowledge search that returns official docs results when available and falls back to web search, formatted as context blocks for support agents.