Hybrid Search — Quick Start

Replace your search results page with one that answers. A reader searches once and gets an AI answer with citations, together with the matching articles.

This takes about ten minutes. At the end you have a working page.

Before you start

Get your keys. Open the Miso Dashboard, pick your environment, and copy the keys from Overview.

The Miso Dashboard. Pick the environment, then copy the keys.

Key	Where it belongs
Publishable	Browser code. The SDK uses this one.
Secret	Your server. Never ship it to a browser.

Put your content in Miso. Hybrid Search reads your catalog for both halves of the page, the answer and the results:

curl -X POST "https://api.askmiso.com/v1/products" \
  -H "X-Api-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "product_id": "art_001",
        "title": "Your article title",
        "url": "https://example.com/your-article",
        "cover_image": "https://example.com/cover.png",
        "published_at": "2026-06-12T09:00:00Z",
        "categories": [["News", "Markets"]],
        "html": "<p>The full article body.</p>"
      }
    ]
  }'

No content of your own yet? Load a real one in a few minutes. Example: Wikinews parses a free public archive of about 20,900 news articles and sends it to Miso, so you have something to ask questions about.

Send categories and cover_image for this module. The results list renders the image, and the category filters come from the hierarchy. See Integrating Your Data.

1. Install the SDK

<script
  async
  src="https://cdn.jsdelivr.net/npm/@miso.ai/client-sdk@1/dist/umd/miso.min.js"
></script>

npm install --save @miso.ai/client-sdk

The script tag loads the SDK asynchronously. Use the misocmd queue, which runs your function as soon as the SDK is ready.

2. Add the container

Put this where the search page belongs:

<div id="miso-hybrid-search-combo"
     class="miso-hybrid-search-combo"></div>

3. Start the workflow

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

  await client.ui.ready;                    // styles are loaded

  const defaults = MisoClient.ui.defaults.hybridSearch;
  const root =
    document.querySelector('#miso-hybrid-search-combo');
  root.innerHTML = defaults.templates.root();

  workflow.autoQuery();                     // read ?q= from the URL
});

autoQuery() reads the q parameter from the page URL, which is what a normal search form already submits. Point your existing form at this page, and the integration is done.

The complete page

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Miso Hybrid Search</title>
  <script
    async
    src="https://cdn.jsdelivr.net/npm/@miso.ai/client-sdk@1/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 () => {
      const client = new MisoClient('YOUR_PUBLISHABLE_API_KEY');
      const workflow = client.ui.hybridSearch;

      await client.ui.ready;

      const defaults = MisoClient.ui.defaults.hybridSearch;
      const root =
        document.querySelector('#miso-hybrid-search-combo');
      root.innerHTML = defaults.templates.root();

      workflow.autoQuery();
    });
  </script>
</body>
</html>

Check it works

Save the page, open it in a browser, and add ?q=media to the URL. You get an answer with its sources, the matching articles, and the category filters.

Hybrid Search: the answer, its sources, and the results list.

Symptom	Cause
Results appear, but no answer	The question matched no passage. Check that the article bodies are in `html` or `description`.
No category filters	Your records carry no `categories`.
Results have no image	Your records carry no `cover_image`.
The page renders empty	The key is the secret key, or your code ran before the SDK loaded.

Ask — Quick Start — the question box on its own.
Explore — Quick Start — related questions on an article page.
Live Showcase — the layouts you can build.
Hybrid Search API — the API behind the module, for your own front end.

Explore — Quick Start

Events & Custom JS