Ask — Quick Start

Put Miso's question box on your page. A reader asks a question in their own words, and gets an answer built from your content, with citations.

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. The Ask module answers from your catalog, so upload it first:

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",
        "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.

The upload is asynchronous, and the response carries a task_id. See Integrating Your Data for batches, the status poll, and the other upload methods. Confirm the result in Dashboard ▸ Data Sets ▸ Catalog.

The catalog in Dojo, with the uploaded articles.

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, so your code must wait for it. Use the misocmd queue, which runs your function as soon as the SDK is ready:

const misocmd = window.misocmd || (window.misocmd = []);
misocmd.push(() => {
  const MisoClient = window.MisoClient;
  // Your code goes here.
});

With npm, import it instead: import MisoClient from '@miso.ai/client-sdk'.

2. Add the container

Put this where the question box belongs:

<div id="miso-ask-combo" class="miso-ask-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.ask;

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

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

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

autoQuery() reads the q parameter from the page URL and asks that question. Call workflow.query('…') instead to ask one yourself.

The complete page

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Miso Ask</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-ask-combo" class="miso-ask-combo"></div>

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

      await client.ui.ready;

      const defaults = MisoClient.ui.defaults.ask;
      const root = document.querySelector('#miso-ask-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 from your own content, with follow-up questions and the articles it used.

The Ask module, with an answer and its sources.

If nothing appears, check these three things first:

Symptom	Cause
The box never renders	The key is the secret key, or it is wrong. Use the publishable key.
The answer refuses every question	The catalog is empty, or the upload is still running.
The page is blank until you reload	Your code ran before the SDK loaded. Use the `misocmd` queue.

Explore — Quick Start — related questions on an article page.
Hybrid Search — Quick Start — search results and an answer together.
Template helpers and elements — change the layout and the markup.
Answer Response Fields — the API behind the module, for your own front end.

Filtering (fq)

Explore — Quick Start