QueryBox Documentation

A lightweight, embeddable JavaScript widget for search and AI chat powered by Elastic Agent Builder.

See live examples of QueryBox in action across different websites.

Installation

Choose your preferred installation method below:

<!-- Add to your HTML <head> -->
<link rel="stylesheet" href="https://unpkg.com/@jedrazb/querybox/dist/style.css">
<script src="https://unpkg.com/@jedrazb/querybox/dist/querybox.umd.js"></script>

<!-- Add before closing </body> tag -->
<script>
  const querybox = new QueryBox({
    apiEndpoint: 'https://api.querybox.dev/{your-domain}/v1',
    theme: 'auto',
    primaryColor: '#ec4899'
  });

  // Add keyboard shortcut (Cmd+K / Ctrl+K)
  document.addEventListener('keydown', (e) => {
    if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
      e.preventDefault();
      querybox.search();
    }
  });
</script>

Quick Start

The fastest way to get started is using our interactive Get Started page. It walks you through the entire setup process including domain setup and automatic crawling.

QueryBox can crawl your web content automatically to keep your search index up-to-date.

Manual Setup

If you prefer to set up manually, here's a basic example:

import QueryBox from '@jedrazb/querybox';
import '@jedrazb/querybox/dist/style.css';

const querybox = new QueryBox({
  apiEndpoint: 'https://api.querybox.dev/yoursite.com/v1',
  theme: 'auto',
  primaryColor: '#ec4899'
});

// Open search
querybox.search();

// Open AI chat
querybox.chat();

Configuration

QueryBox is highly customizable to match your brand and user experience. All options except apiEndpoint are optional with sensible defaults.

Option	Type	Default	Description
`apiEndpoint`	string	required	Your QueryBox API endpoint URL (generated during setup)
`theme`	'light' \| 'dark' \| 'auto'	'auto'	Visual theme. 'auto' follows system preferences
`primaryColor`	string	'#007aff'	Primary color for buttons, links, and accents (hex format)
`title`	string	undefined	Optional title displayed at the top of the panel (e.g., "Help Center")
`initialQuestions`	string[]	undefined	Array of suggested questions to display in empty chat state (max 3). Users can click these to start a conversation.

Example with All Options

const querybox = new QueryBox({
  apiEndpoint: 'https://api.querybox.dev/yoursite.com/v1',
  theme: 'dark',
  primaryColor: '#10b981',
  title: 'Documentation',
  initialQuestions: [
    'How do I get started?',
    'What are the pricing options?',
    'How do I integrate with React?'
  ],
  container: '#querybox-container',
  classNames: {
    panel: 'custom-panel',
    overlay: 'custom-overlay'
  }
});

Widget Interface

Methods

`querybox.search()`

Opens the search panel.

`querybox.chat()`

Opens the AI chat panel.

`querybox.destroy()`

Destroys the instance and cleans up event listeners.

`querybox.isValid()`

Returns true if configuration is valid.

`querybox.getConfig()`

Returns the current configuration object.

Public API

QueryBox provides public REST API endpoints for direct integration without the widget. Perfect for custom implementations, mobile apps, or backend services.

API Base URLhttps://api.querybox.dev

Available Endpoints

`POST /{your-domain}/v1/search`

Search your indexed content. Returns matching results with titles, URLs, and relevance scores.

`POST /{your-domain}/v1/chat`

AI-powered chat with Server-Sent Events (SSE) streaming. Maintains conversation context for multi-turn conversations.

Simple POST request to search your indexed content. Returns results with title, content, URL, and score.

// Search endpoint - simple POST request
const searchQuery = async (query) => {
  const response = await fetch('https://api.querybox.dev/{your-domain}/v1/search', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query })
  });

  const data = await response.json();
  return data;
  // Returns: { results: [...], total: number, took: number }
};

// Usage
const results = await searchQuery('your search term');
results.results.forEach(result => {
  console.log(result.title, result.url);
});

Response format:

{
  "results": [
    {
      "id": "doc_123",
      "title": "Page Title",
      "content": "Page content...",
      "url": "https://...",
      "score": 0.95
    }
  ],
  "total": 42,
  "took": 12
}

Crawler

You can trigger crawls manually from the Get Started page. Re-crawling updates your search index with new or changed content.

Crawler Configuration

Crawling only a subset of your site (e.g., your-domain.com/docs/*):

Set up an HTTP redirect from docs.your-domain.com to your-domain.com/docs
Add docs.your-domain.com as your crawler domain
The crawler will automatically detect the redirect and create a configuration scoped to /docs/* only

This allows you to create multiple instances of QueryBox for different sections of your site (e.g., docs, help, blog), each with its own search index and AI chat.

Common Issues

robots.txt blocking crawlers: Ensure your robots.txt doesn't disallow crawlers. Whitelist the QueryBox crawler by allowing QueryBox-Crawler/1.0 user agent.

HTTPS required: Your website must be served over HTTPS. The crawler only supports secure connections.

QueryBox Documentation - Complete Guide