Mindset AI

Docs / Get started / Build it

Put an agent on your page

Two lines of HTML and one backend endpoint — the ten-minute quickstart.

Two lines of HTML and one endpoint on your backend. This walks through both, and by the end you'll have a working agent your users can talk to.

Budget about ten minutes if you already have an agent set up.

What you need first

An agent, published. Build it in the Mindset AI console. You'll need its handle, which you can copy from the agent's Embed tab.

An organization API key. Ask your Mindset AI administrator for one. It's admin-grade and lives on your server only.

Your host address, org slug and Environment slug. All three are on that same Embed tab, pre-filled for your organization, so you can copy them rather than assemble them.

Step 1: add a session endpoint to your backend

Your page can't call us directly, because doing so would mean putting your organization's API key in a browser. Instead your backend makes one call and hands the result to the browser.

Add an endpoint that does this. Express shown here, but any stack works.

app.get("/api/session", async (req, res) => {
  const user = req.user; // however your app knows who's signed in

  const r = await fetch(
    `https://${MINDSET_HOST}/api/v1/orgs/${ORG_SLUG}/envs/${ENV_SLUG}/agent-sessions`,
    {
      method: "POST",
      headers: {
        "x-api-key": process.env.ORG_API_KEY,
        "content-type": "application/json",
      },
      body: JSON.stringify({
        user: { email: user.email },
        agent: "support-bot",
        createUserIfNeeded: true,
      }),
    },
  );

  if (!r.ok) {
    const detail = await r.text();
    console.error("Mindset AI session create failed", r.status, detail);
    return res.status(502).json({ error: "Could not start a session" });
  }

  const { session } = await r.json();
  res.set("cache-control", "no-store").json({ session });
});

Three things to get right here.

Your organization API key stays on the server. It's never sent to the browser, never in a response body, never in a log line.

createUserIfNeeded set to true means a user we haven't seen before is created on their first visit. Leave it out and an unknown user gets a 404, which is the most common first-integration surprise.

The no-store cache header stops a proxy handing one user's session to another.

Return only the session value. It's opaque, so pass it along exactly as you received it rather than reading or reshaping it.

For the full request and response detail, including how to use your own user IDs instead of email, see "Create a session for your users".

Step 2: put the agent on your page

Load the script and write the tag.

<script src="https://YOUR-MINDSET-HOST/sdk/mindset-agent.js"></script>

<mindset-agent agent="support-bot"></mindset-agent>

<script>
  document.querySelector("mindset-agent").configure({
    getSession: async () => {
      const r = await fetch("/api/session");
      if (!r.ok) throw new Error("Could not start a session");
      const { session } = await r.json();
      return session;
    },
  });
</script>

That's the whole frontend integration. The script self-registers the mindset-agent tag, and configure() tells it how to get a session.

Notice that getSession is a function, not a string. The SDK calls it when it needs a session, which is what lets it get a fresh one after a page reload without you writing any refresh logic.

The agent renders inside a shadow root with its own styles, so it won't inherit your page's CSS and it won't leak styles into your page.

Step 3: check it works

Load the page. You should see a chat panel, and you should be able to send a message and get a reply.

If nothing appears, open your browser console. The element reports configuration and transport problems as mindset:error events with a stable code you can branch on, and it logs a load failure rather than throwing.

document.querySelector("mindset-agent").addEventListener("mindset:error", (e) => {
  console.error("Mindset AI error:", e.detail.code, e.detail.message);
});

Using React

React 19 renders custom elements natively, so there's no wrapper package to install. Same script tag, same element.

import { useEffect, useRef } from "react";

function Agent({ agent }) {
  const ref = useRef(null);

  useEffect(() => {
    ref.current?.configure({
      getSession: async () => {
        const r = await fetch("/api/session");
        if (!r.ok) throw new Error("Could not start a session");
        const { session } = await r.json();
        return session;
      },
    });
  }, []);

  return <mindset-agent ref={ref} agent={agent} />;
}

Load the script once, in your index.html or wherever you keep third-party tags, rather than inside the component.

If you're on TypeScript, you'll need to declare the element in JSX.IntrinsicElements once, since a custom element isn't there by default.

If you want to build your own interface

Everything above gives you our chat UI. If you'd rather render your own, there's a headless client that gives you the same conversation with no UI at all.

const { createAgentConversation } = await import(
  "https://YOUR-MINDSET-HOST/sdk/mindset-agent-uiless.js"
);

const chat = createAgentConversation({
  agent: "support-bot",
  getSession: async () => (await (await fetch("/api/session")).json()).session,
});

chat.on((event) => {
  if (event.type === "text_delta") appendToYourUI(event.content);
});

chat.send("Hello");

Your backend endpoint from step 1 is unchanged. Only the frontend differs.

Before you ship

There's no npm package. The SDK is served from your Mindset AI host and loaded by script tag or by URL import. There's nothing to install, and you always get the current build.

Only load one Mindset AI SDK per page. A custom element tag can only be claimed once per document. Loading our bundle twice is harmless, but loading it alongside an older Mindset AI embed will collide, and the SDK will tell you so by name.

Conversations start fresh on every page load unless you tell them not to. If you want a user to pick up where they left off, the element hands you a conversation ID after their first completed turn, and you hand it back on their next visit. See "The mindset-agent element" for the round trip.

Troubleshooting

Nothing renders and the console says the script failed to load. Check the host in your script tag. It should be the same host as the Embed tab shows.

missing-agent. The element was configured without an agent. Check the agent attribute is set and matches a handle in your organization.

invalid-auth. configure() didn't get a getSession function. A common cause is passing the session string itself rather than a function that returns one.

turn-failed. The turn couldn't run. Usually the session expired or your session endpoint returned something unexpected. Check your backend logs first.

A 404 from your session endpoint during setup. Four different things return an identical 404: a wrong org slug, a wrong Environment slug, an agent handle that isn't in your organization, and a key without the right scopes. The response won't tell you which, so check all four against the Embed tab.

Next steps

  • "Create a session for your users" covers the mint call properly, including using your own user IDs.
  • "The mindset-agent element" is the full reference: attributes, methods, events, theming.
  • "The UI-less SDK" covers building your own interface.