Skip to main content

​
Overview

Hybrid Search delivers the best of both worlds: traditional keyword search results alongside AI-generated answers from your content. Users get direct, intelligent responses paired with a list of relevant articles β€” all in one seamless interface.
1

Obtain Your API Key

Log in to the Miso Dashboard, select your target environment (e.g., Production), and navigate to the Overview section to copy your Publishable API Key.Miso Dashboard β€” select your environment and copy your API keys
There is one publishable key and one secret key per environment. The publishable key is used in client-side code; the secret key is used for server-side API calls.
2

Upload Your Corpus via API

Upload your content to Miso using the Product / Content Upload API. You can do this with any HTTP client β€” the steps below use Postman.Endpoint β€” View full API reference
POST https://api.askmiso.com/v1/products
Step 1 β€” Set your request headersIn Postman, go to the Headers tab and add your Secret API Key:
HeaderValue
X-API-KEYYour Secret API Key
Content-Typeapplication/json
Postman β€” set the X-API-KEY header with your Secret API KeyStep 2 β€” Add your request bodySwitch to the Body tab, select raw β†’ JSON, and paste your corpus data:
{
  "data": [
    {
      "product_id": "art_001",
      "title": "Your Article Title Here",
      "url": "https://yoursite.com/your-article",
      "cover_image": "https://yoursite.com/cover.png",
      "description": "A brief description of the article content.",
      "html": "" // Full article HTML content, JSON-escaped
    },
    {
      "product_id": "art_002",
      "title": "Another Article Title",
      "url": "https://yoursite.com/another-article",
      "cover_image": "https://yoursite.com/cover2.png",
      "description": "Another article description.",
      "html": "" // Full article HTML content, JSON-escaped
    }
  ]
}
Step 3 β€” Send and verifyClick Send. A 200 OK response confirms the corpus has been uploaded successfully.Postman β€” request body with JSON data and 200 OK responseYou can verify the upload under Miso Dashboard β†’ Data Sets β†’ Catalog.Miso Dashboard β€” Data Sets β†’ Catalog showing uploaded articles
3

Install the Miso SDK

Add the Miso JavaScript SDK to your webpage using either method:
Install the SDK via npm:
npm install --save @miso.ai/client-sdk
Then import it in your JavaScript file:
import MisoClient from '@miso.ai/client-sdk';
4

Add the Hybrid Search UI to Your Page

Place the container element in your HTML where you want the search interface to appear:
<body>
  <div id="miso-hybrid-search-combo" class="miso-hybrid-search-combo"></div>
</body>
Configure the workflow by adding the following script:
<script>
  const misocmd = window.misocmd || (window.misocmd = []);
  misocmd.push(async () => {
    // setup client
    const MisoClient = window.MisoClient;
    const client = new MisoClient('YOUR_PUBLISHABLE_API_KEY');
    const workflow = client.ui.hybridSearch;

    // wait for styles to be loaded
    await client.ui.ready;

    // render DOM and get element references
    const defaults = MisoClient.ui.defaults.hybridSearch;
    const templates = defaults.templates;
    const rootElement = document.querySelector('#miso-hybrid-search-combo');
    rootElement.innerHTML = templates.root();

    // start query if specified in URL parameters
    workflow.autoQuery();
  });
</script>
Replace YOUR_PUBLISHABLE_API_KEY with the key from Step 1. To test, open the page in a browser and append ?q=media to the URL to see both AI answers and keyword search results side by side.

​
Complete Example

Here is a minimal working HTML file: 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Miso Hybrid Search Demo</title>
  <script async src="https://cdn.jsdelivr.net/npm/@miso.ai/client-sdk@1.12.7/dist/umd/miso.min.js"></script>
</head>
<body>
  <div id="miso-hybrid-search-combo" class="miso-hybrid-search-combo"></div>

  <script>
    const misocmd = window.misocmd || (window.misocmd = []);
    misocmd.push(async () => {
      // setup client
      const MisoClient = window.MisoClient;
      const client = new MisoClient('YOUR_PUBLISHABLE_API_KEY');
      const workflow = client.ui.hybridSearch;

      // wait for styles to be loaded
      await client.ui.ready;

      // render DOM and get element references
      const defaults = MisoClient.ui.defaults.hybridSearch;
      const templates = defaults.templates;
      const rootElement = document.querySelector('#miso-hybrid-search-combo');
      rootElement.innerHTML = templates.root();

      // start query if specified in URL parameters
      workflow.autoQuery();
    });
  </script>
</body>
</html>
Save as client_sdk_test_hybrid_search.html, open in a browser, and append ?q=media to the URL to see the Hybrid Search module in action.

​
Live Demo & Visuals

Once configured, the Miso Hybrid Search module provides a unified, interactive UI out of the box. To verify your setup is working:
  1. Open client_sdk_test_hybrid_search.html in a browser.
  2. Append ?q=media to the URL β€” you should see an AI-generated answer alongside keyword search results, cited sources, and category filters.
Hybrid Search β€” AI answer box, cited sources, and search results displayed together
API keys can be passed via the api_key query parameter or the X-API-KEY request header. There is one publishable key and one secret key per environment β€” use the publishable key in client-side code and the secret key for server-side API calls.

​
Next Steps

Ask Module Quick Start

Set up the Ask module for standalone Q&A.

Explore Module Quick Start

Add related questions to your article pages.

Product / Content Upload API

Full reference for uploading your corpus to Miso.

Search API

The underlying search API powering keyword results in Hybrid Search.

Ask Questions API

The underlying API powering AI-generated answers in Hybrid Search.

Authentication

Learn how API keys work and how to authenticate your requests.