# Humind developer documentation

> Integrate the Humind AI shopping assistant: chat overlay, storefront widgets, catalog sync, public REST API and MCP server.

## Docs

- [Introduction](https://docs.thehumind.com/raw/ai-agent/index.md): The AI Agent is the conversational assistant your visitors see when they open the chat on your site. Everything that defines its behavior, what it knows, how it answers, where it shows up, is configured in your merchant dashboard, in the AI Agent section.
- [Instructions](https://docs.thehumind.com/raw/ai-agent/instructions.md): Page AI Agent → Train → Guidance in the dashboard (app.thehumind.com).
- [Knowledge](https://docs.thehumind.com/raw/ai-agent/knowledge.md): Page AI Agent → Train → Content → Sources in the dashboard (app.thehumind.com).
- [Product snippets](https://docs.thehumind.com/raw/ai-agent/product-snippets.md): Product snippets are private Q&A entries attached to a specific product in your catalog. Like regular snippets, they are never shown to the visitor; the AI uses them to answer, without citing them. The difference: they are scoped to a given product and only kick in when that product is in the conversation's context.
- [Shared snippets](https://docs.thehumind.com/raw/ai-agent/shared-snippets.md): A shared snippet is a regular snippet that you attach to specific products or whole collections, instead of letting the AI retrieve it by relevance. Write it once and it applies to every product in the chosen collections, including products you add to those collections later.
- [Analytics](https://docs.thehumind.com/raw/api-reference/analytics.md): Pull the same KPIs and clustered visitor questions your B2B dashboard shows: for a BI tool, a scheduled export, or an AI agent that needs to answer "how are we doing" without opening the dashboard.
- [Authentication](https://docs.thehumind.com/raw/api-reference/authentication.md): Every request to the public API authenticates with an API key passed in the Authorization header. Keys are scoped (catalog vs knowledge, read vs write) and bound to a single company. There are no OAuth flows, no JWTs, no signed requests, just one bearer token per call.
- [Collections](https://docs.thehumind.com/raw/api-reference/collections.md): Collections are named groups of products. The AI assistant uses them to narrow recommendations to a subset of your catalog, "show me bestsellers", "what's in the summer 2026 drop", "anything from the gift guide". Push your merchandising structure once and the assistant will respect it everywhere it surfaces products.
- [Conventions](https://docs.thehumind.com/raw/api-reference/conventions.md): Conventions that apply to every endpoint in the public API. Read this once; the per-resource pages assume you've internalized everything here.
- [Conversations](https://docs.thehumind.com/raw/api-reference/conversations.md): Export your chat conversations, the threads shoppers had with the AI assistant (and your operators after a handoff), for analytics, your data warehouse, CRM enrichment, or compliance archives.
- [Errors](https://docs.thehumind.com/raw/api-reference/errors.md): Every error response uses the same shape. The HTTP status code tells you the broad category; the error.code tells you the precise reason.
- [Imports](https://docs.thehumind.com/raw/api-reference/imports.md): The Imports API is the async, streaming alternative to POST /products. You hand Humind a pre-signed upload URL, push an NDJSON file straight to blob storage, and Humind ingests the file in the background using the same validation and upsert pipeline as the synchronous endpoints.
- [API reference](https://docs.thehumind.com/raw/api-reference/index.md): The Humind public API lets you push your catalog into Humind from any stack. Authenticate with a single API key per environment, send JSON over HTTPS, get back JSON. No SDK to install, no Shopify required. Optional webhooks push notifications back to you instead of polling.
- [Knowledge](https://docs.thehumind.com/raw/api-reference/knowledge.md): Knowledge is the AI assistant's source of truth for everything that isn't a product: shipping policy, return windows, sizing guides, brand story, FAQs. Push it once and the assistant grounds its answers on what you've written, instead of guessing.
- [Product groups](https://docs.thehumind.com/raw/api-reference/product-groups.md): Product groups connect products that represent the same model or family. A group defines stable option axes, such as color or material. Each product membership supplies the value selected for those axes.
- [Products](https://docs.thehumind.com/raw/api-reference/products.md): Push your product catalog to Humind so the AI assistant can recommend the right items, ground its answers in your data, and surface accurate prices and availability.
- [Rate limits](https://docs.thehumind.com/raw/api-reference/rate-limits.md): How much traffic the public API accepts today, how the per-API-key limits are enforced, and how to design a client that backs off correctly under throttling.
- [Settings](https://docs.thehumind.com/raw/api-reference/settings.md): Read and update your store's merchant settings (widget appearance, AI behavior, moderation, CSAT collection, usage limits, chat invitation, pre-chat survey, cookie consent, collection quiz, tracking, catalog behavior, and localization), the same settings surfaced in your dashboard, over the API.
- [Webhooks](https://docs.thehumind.com/raw/api-reference/webhooks.md): Webhooks are how Humind notifies your backend when something interesting happens, without you having to poll. You declare an HTTPS endpoint on your side, subscribe it to one or more event types via POST /public/v1/webhooks/endpoints, and Humind sends a signed JSON payload to that URL every time a matching event fires.
- [Sync your catalog](https://docs.thehumind.com/raw/catalog/custom.md): Where to go depends on your stack.
- [Shopify catalog sync](https://docs.thehumind.com/raw/catalog/shopify.md): If you're on Shopify, install the Humind app from the Shopify App Store. Your products, collections, and shop metadata sync automatically. There's nothing else to do.
- [Introduction](https://docs.thehumind.com/raw/getting-started/index.md): Humind is an AI assistant you install on your e-commerce site to help shoppers find the right products and get real-time answers. Concretely: a conversational chat (the main component) plus three optional blocks for your product, collection, and home pages, all powered by your synced catalog.
- [Add to cart](https://docs.thehumind.com/raw/install/add-to-cart.md): How the "Add to cart" button in the Humind widget works, platform by platform: what happens on Shopify, on PrestaShop, on WooCommerce, and how to wire it up on a custom storefront. For styling the button, see the widget settings; for the analytics events fired around the cart, see GA4 / GTM analytics.
- [Track widget events in GA4 / GTM](https://docs.thehumind.com/raw/install/analytics.md): The chat widget can mirror its interaction events into your site's window.dataLayer, where Google Tag Manager (or any tag management system reading the dataLayer) picks them up. From there, forward them to GA4, Meta, or any destination you already manage in your TMS: chat opens, messages sent, products added to cart from the chat, handoffs, CSAT, appointments.
- [Install the chat](https://docs.thehumind.com/raw/install/chat.md): Two lines of code on every page where the chat should be available.
- [Install the collection quiz](https://docs.thehumind.com/raw/install/collection-quiz.md): A multi-step discovery quiz on a collection page. AI-generated questions, streams a shortlist of products at the end.
- [Trigger the chat from your own UI](https://docs.thehumind.com/raw/install/custom-triggers.md): Dispatch a humind-open-chat custom event on window to open the chat overlay from any element on your page: a "Need help?" button in the checkout, a CTA inside a product card, a help-center tile, anywhere a visitor might want to start a conversation without going through the floating entry point.
- [Install the gift finder](https://docs.thehumind.com/raw/install/gift-finder.md): An "ask anything" block with a text input and suggested-question chips. Two visual variants: a full search section (default) and a narrow banner (banner).
- [Configure Microsoft Entra ID for Humind](https://docs.thehumind.com/raw/install/microsoft-entra-sso.md): This guide explains how to configure:
- [Install product questions](https://docs.thehumind.com/raw/install/product-questions.md): AI-generated preset questions plus a free-form input on a product page. Clicking anything opens the chat overlay with the question pre-filled.
- [Humind MCP server](https://docs.thehumind.com/raw/mcp.md): Connect Claude, or any MCP-compatible AI agent, directly to your Humind store. One endpoint, your existing API key, and an agent can read your settings, pull analytics, search conversations, manage your knowledge base, and browse your catalog: the same operations available through the public REST API, exposed as tools an LLM can call.
- [Humind widget: information for legal teams](https://docs.thehumind.com/raw/reference/browser-storage.md): This page describes the browser storage created by the Humind chat widget and the data sent to PostHog for usage measurement.
- [Changelog](https://docs.thehumind.com/raw/reference/changelog.md): Version history for the public Humind surfaces: the widgets bundle, the chat loader, and this documentation site.
- [Data retention and deletion](https://docs.thehumind.com/raw/reference/data-retention.md): This page describes what personal data the Humind platform stores server-side on behalf of merchants, for how long, and through which mechanisms it is deleted: automatically at the end of a retention period, in bulk at the end of the contract, or selectively for a given person.
- [FAQ](https://docs.thehumind.com/raw/reference/faq.md): No meaningful impact. The scripts load with defer, so they never block page rendering or Time to Interactive. They're served from a CDN (embed.thehumind.com, widgets.thehumind.com), code-split into chunks, and only the entry chunk runs on mount. The rest is fetched on demand when the shopper interacts.
- [Incident management and personal data breaches](https://docs.thehumind.com/raw/reference/incident-response.md): This page describes how Humind detects, classifies, and resolves incidents affecting its services, and the specific procedure applied when an incident qualifies as a personal data breach under Article 4(12) of the GDPR.
- [Troubleshooting](https://docs.thehumind.com/raw/reference/troubleshooting.md): Common issues when embedding Humind widgets, with the fastest checks for each.

## Optional

- [French versions](https://docs.thehumind.com/raw/index.json): every page also exists in French under /raw/fr/