> ## Documentation Index
> Fetch the complete documentation index at: https://docs.miso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hybrid Search Quick Start

> Combine traditional keyword search with AI-generated answers in a single unified interface.

## 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.

<Steps>
  <Step title="Obtain Your API Key">
    Log in to the [Miso Dashboard](https://dojo.askmiso.com), select your target environment (e.g., **Production**), and navigate to the **Overview** section to copy your **Publishable API Key**.

    <img src="https://mintcdn.com/miso/3qrR--X4Z69DKEAH/images/quickstart-ask/hybrid-dashboard-api-keys.png?fit=max&auto=format&n=3qrR--X4Z69DKEAH&q=85&s=234c772adcebd50ef7f1ae2db32021a4" alt="Miso Dashboard — select your environment and copy your API keys" width="1509" height="830" data-path="images/quickstart-ask/hybrid-dashboard-api-keys.png" />

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Upload Your Corpus via API">
    Upload your content to Miso using the [**Product / Content Upload API**](/api-reference/product-content-apis/product-content-upload-api). You can do this with any HTTP client — the steps below use [Postman](https://www.postman.com/).

    **Endpoint** — [View full API reference](/api-reference/product-content-apis/product-content-upload-api)

    ```
    POST https://api.askmiso.com/v1/products
    ```

    **Step 1 — Set your request headers**

    In Postman, go to the **Headers** tab and add your Secret API Key:

    | Header         | Value               |
    | -------------- | ------------------- |
    | `X-API-KEY`    | Your Secret API Key |
    | `Content-Type` | `application/json`  |

    <img src="https://mintcdn.com/miso/3qrR--X4Z69DKEAH/images/quickstart-ask/postman-headers.png?fit=max&auto=format&n=3qrR--X4Z69DKEAH&q=85&s=327ba4b42fa7f15bf9e1576166f7d0f6" alt="Postman — set the X-API-KEY header with your Secret API Key" width="2048" height="395" data-path="images/quickstart-ask/postman-headers.png" />

    **Step 2 — Add your request body**

    Switch to the **Body** tab, select **raw → JSON**, and paste your corpus data:

    ```json theme={null}
    {
      "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 verify**

    Click **Send**. A `200 OK` response confirms the corpus has been uploaded successfully.

    <img src="https://mintcdn.com/miso/3qrR--X4Z69DKEAH/images/quickstart-ask/postman-body-200ok.png?fit=max&auto=format&n=3qrR--X4Z69DKEAH&q=85&s=8b84248b50ff9823d77b87efa8c298e9" alt="Postman — request body with JSON data and 200 OK response" width="2048" height="1200" data-path="images/quickstart-ask/postman-body-200ok.png" />

    You can verify the upload under **Miso Dashboard → Data Sets → Catalog**.

    <img src="https://mintcdn.com/miso/6VnZ2gM4VtDSnL2E/images/quickstart-ask/dashboard-catalog.png?fit=max&auto=format&n=6VnZ2gM4VtDSnL2E&q=85&s=6b7e24b179abdee3ecd13d43bd5b9260" alt="Miso Dashboard — Data Sets → Catalog showing uploaded articles" width="689" height="829" data-path="images/quickstart-ask/dashboard-catalog.png" />
  </Step>

  <Step title="Install the Miso SDK">
    Add the Miso JavaScript SDK to your webpage using either method:

    <Tabs>
      <Tab title="npm (Node Module)">
        Install the SDK via npm:

        ```bash theme={null}
        npm install --save @miso.ai/client-sdk
        ```

        Then import it in your JavaScript file:

        ```js theme={null}
        import MisoClient from '@miso.ai/client-sdk';
        ```
      </Tab>

      <Tab title="Script Tag">
        Add the following to your `<head>`:

        ```html theme={null}
        <script async src="https://cdn.jsdelivr.net/npm/@miso.ai/client-sdk@1.12.7/dist/umd/miso.min.js"></script>
        ```

        Since the SDK loads asynchronously, use the `misocmd` queue to ensure your code runs only after the SDK is ready:

        ```js theme={null}
        const misocmd = window.misocmd || (window.misocmd = []);
        misocmd.push(() => {
          const MisoClient = window.MisoClient;
          // Your initialization code here
        });
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add the Hybrid Search UI to Your Page">
    **Place the container element** in your HTML where you want the search interface to appear:

    ```html theme={null}
    <body>
      <div id="miso-hybrid-search-combo" class="miso-hybrid-search-combo"></div>
    </body>
    ```

    **Configure the workflow** by adding the following script:

    ```html theme={null}
    <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>
    ```

    <Tip>
      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.
    </Tip>
  </Step>
</Steps>

## Complete Example

Here is a minimal working HTML file:

```html theme={null}
<!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.

<img src="https://mintcdn.com/miso/3qrR--X4Z69DKEAH/images/quickstart-ask/hybrid-search-demo.png?fit=max&auto=format&n=3qrR--X4Z69DKEAH&q=85&s=41cb964014aad277a93f1dd8c9c36623" alt="Hybrid Search — AI answer box, cited sources, and search results displayed together" width="1869" height="800" data-path="images/quickstart-ask/hybrid-search-demo.png" />

<Note>
  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.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Ask Module Quick Start" icon="message-question" href="/introduction/quickstart-ask">
    Set up the Ask module for standalone Q\&A.
  </Card>

  <Card title="Explore Module Quick Start" icon="compass" href="/introduction/quickstart-explore">
    Add related questions to your article pages.
  </Card>

  <Card title="Product / Content Upload API" icon="upload" href="/api-reference/product-content-apis/product-content-upload-api">
    Full reference for uploading your corpus to Miso.
  </Card>

  <Card title="Search API" icon="magnifying-glass" href="/api-reference/search-apis/search-api">
    The underlying search API powering keyword results in Hybrid Search.
  </Card>

  <Card title="Ask Questions API" icon="message-question" href="/api-reference/ask-apis/ask-questions-api">
    The underlying API powering AI-generated answers in Hybrid Search.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn how API keys work and how to authenticate your requests.
  </Card>
</CardGroup>