mintlify · Nov 9, 2026 · Nov 9, 2026 · Nov 11, 2026
diff --git a/assistant/widget.mdx b/assistant/widget.mdx
@@ -1,7 +1,7 @@
 ---
 title: "Embed the AI assistant widget"
 sidebarTitle: "Widget"
-description: "Install and configure the Mintlify widget to embed an AI assistant trained on your content into any website, web app, or dashboard."
+description: "Install and configure an existing Mintlify assistant widget on your site or app, or build your own in-app assistant with the assistant API."
 keywords: ["assistant", "chat", "embed"]
 ---
 
@@ -9,26 +9,27 @@

 export const WidgetCodeBlock = ({ children, ...props }) => (
   <CodeBlock {...props}>{children}</CodeBlock>
 );
 
-The [assistant](/assistant) answers questions on your Mintlify site. To embed the same capability on another site or web app, use the widget. The widget gives your users access to AI chat trained on your content, wherever they use your product. Embed it in your dashboard, marketing site, support portal, or elsewhere.
+<Note>
+  New widgets are not available. If you already use the widget, it keeps working on your authorized sites, and this page explains how to install and configure it.
+
+  To add an AI assistant to a new site or app, build your own with the assistant API. The [Build an in-app assistant](/guides/assistant-embed) tutorial walks through building one in a Next.js app.
+
+  For other frameworks, point a coding agent to the [create assistant message](/api/assistant/create-assistant-message-v2) API reference and ask it to build a chat widget for your app.
+</Note>
+
+The [assistant](/assistant) answers questions on your Mintlify site. The widget embeds the same capability on another site or web app. It gives your users access to AI chat trained on your content, wherever they use your product. Embed it in your dashboard, marketing site, support portal, or elsewhere.
 
 Add the widget to any website or web application with a hosted script. The widget owns its trigger and renders inside a closed Shadow DOM, an isolated document tree that prevents your application styles from affecting the widget.
 
 The only required browser option is your public widget ID. Set embed-specific starter questions and a support email in the browser configuration. The widget uses the [deflection contact form](/assistant/configure#set-deflection-emails) from your assistant settings.
 
 ## Prerequisites
 
+- An existing widget and its widget ID.
 - A [Pro or Enterprise plan](https://mintlify.com/pricing?ref=assistant). The widget uses the same credits as the assistant.
 
-## Enable the widget
-
-<Note>
-  You can no longer configure the widget in the dashboard. If you already use the widget, it keeps working on your authorized sites.
-
-  Email [support@mintlify.com](mailto:support@mintlify.com) if you need help setting up the widget on a new site.
-</Note>
-
 ## Install and configure
 
 Use the playground to configure the presentation, visual options, and observer hooks for your widget. The installation code block updates as you change each option.
@@ -287,7 +288,7 @@

 Conversation snapshots remain private to the widget. Each method resolves to `void`.

 ## Content Security Policy

 If your site uses a Content Security Policy, allow the origins required by your enabled widget features:

@@ -298,8 +299,8 @@
 | `connect-src`                                | `https://api.mintlify.com`          | Configuration, messages, and feedback |
 | `connect-src`                                | `https://ph.mintlify.com`           | Internal widget analytics             |
 | `font-src`                                   | `https://widget.mintlify.com`       | Optional bundled Inter font           |
 | `script-src`                                 | `https://js.hcaptcha.com`           | hCaptcha bot protection               |
 | `connect-src` and `frame-src`                | `https://*.hcaptcha.com`            | hCaptcha bot protection               |

 A strict `script-src` policy must still authorize both the loader and initialization script. A strict `style-src` policy must authorize the nonce you pass to `init()`, which the widget copies to its injected style sheet. Passing `nonce` to `init()` propagates it only to resources the widget creates after initialization.


diff --git a/help-center/embed-docs-site-in-iframe.mdx b/help-center/embed-docs-site-in-iframe.mdx
@@ -1,12 +1,12 @@
 ---
 title: "Docs site refuses to load in an iframe"
 description: "Learn why your Mintlify documentation site refuses to load inside an iframe on another domain and how to request that your app's origins be allowed."
 keywords: ["iframe", "embed docs", "frame-ancestors", "refused to connect", "in-app documentation", "CSP"]
 ---

 Mintlify documentation sites block embedding in iframes on other domains by default. If you load your docs in an `<iframe>` inside your own product, the browser refuses to display the page and logs a `frame-ancestors` Content Security Policy violation in the console.

 ## Why the iframe is blocked

 By default, Mintlify-hosted documentation sites send a `Content-Security-Policy` header with this `frame-ancestors` directive:

@@ -18,9 +18,9 @@

 ## Request access for your app's origins

 You cannot change `frame-ancestors` in `docs.json`. To request that your app's origins be allowed, contact support. Mintlify reviews these requests case by case.

 1. List every origin that needs to embed your docs. Include the scheme, such as `https://app.example.com`. Wildcard subdomains, such as `https://*.example.com`, are supported.
 2. Email <a href="mailto:support@mintlify.com">support@mintlify.com</a> with your project subdomain, your documentation domain, the list of origins, and how you plan to use the embed.
 3. If support approves the request, reload the page in your app to verify that the iframe displays your docs.

@@ -28,6 +28,6 @@
 
 If you serve your docs through your own reverse proxy that overwrites the `Content-Security-Policy` header, set `frame-ancestors` in your proxy's policy instead. See [CSP configuration](/deploy/csp-configuration).
 
-## Alternative: embed the assistant widget
+## Alternative: build an in-app assistant
 
-If you want users to get answers from your documentation inside your app without loading the full site, embed the assistant widget instead. The widget loads from a hosted script, so it does not depend on your docs site's `frame-ancestors` policy. You manage the origins allowed to load the widget in your dashboard. The widget requires a Pro or Enterprise plan. See [Embed the AI assistant widget](/assistant/widget).
+If you want users to get answers from your documentation inside your app without loading the full site, build your own assistant with the assistant API instead. Your assistant doesn't load your docs site, so `frame-ancestors` doesn't apply. The assistant requires a Pro or Enterprise plan. See [Build an in-app assistant](/guides/assistant-embed).
diff --git a/migration-services/go-live-checklist.mdx b/migration-services/go-live-checklist.mdx
@@ -37,7 +37,7 @@ Use this checklist to set up configurations and validate settings before going l
   - Configure your [support and sales deflection emails](/assistant/configure#set-deflection-emails).
   - Configure your [search domains](/assistant/configure#search-domains).
   - Customize the [assistant's response patterns](/assistant/customize) and [add assistant skills](/assistant/skills).
-- **Embed the assistant widget.** Enable the [assistant widget](/assistant/widget) to add the assistant to your product dashboard, marketing site, or support portal.
+- **Build an in-app assistant.** Use the assistant API to [build your own assistant](/guides/assistant-embed) for your product dashboard, marketing site, or support portal.
 - **Enable add-ons.** Go to the [Site](https://app.mintlify.com/settings/project/site) page in your dashboard. Enable relevant add-ons such as agent feedback, [CI checks](/deploy/ci), related topics, and more.
 - **Set up the Slack agent.** This lets you make changes to your content directly in Slack. See [Connect your Slack workspace](/agent/slack#connect-your-slack-workspace).
 - **Set up automations.** See [how to enable an automation](/automations/manage#enable-an-automation).

diff --git a/mint-instructions/publish/assistant.mdx b/mint-instructions/publish/assistant.mdx
@@ -28,17 +28,17 @@
   - Deflection, **Link** mode: full `http`/`https` URL, no credentials. Mintlify appends `threadId` as a query parameter. No sales deflection in this mode.
   - Search domains for web search: public, no JavaScript-rendered sites. Patterns: `example.com`, `docs.example.com`, `*.example.com`, `docs.example.com/api`.
   - Up to three starter questions.
   - Bot protection: **Assistant settings** (https://app.mintlify.com/products/assistant/settings) > **Bot Protection** > **Invisible Captcha**. Up to 10 minutes to apply. With custom CSP, allow `hcaptcha.com` and `*.hcaptcha.com`.
 4. Instructions for every answer (repo): write `.mintlify/Assistant.md` (`ASSISTANT.md` also accepted). It adds to the system prompt, never replaces defaults. Delete the file to remove.
 5. Topic skills (repo): one `skill.md` per directory under `.mintlify/assistant/skills/<slug>/`. Redeploy after adding or changing.
 6. Contextual menu entry: add `"assistant"` to `contextual.options` in `docs.json`.
 7. Widget (another site or app): see Examples.
 8. Narration: user opens **Site** settings (https://app.mintlify.com/settings/project/site), **Narration** section, enables **Page narration**.
 9. Bring your own model: user selects the project, opens **API keys** (https://app.mintlify.com/settings/organization/api-keys), **AI model** section (only appears if the contract includes it), enables **Bring your own model**, picks provider (OpenRouter, Anthropic, OpenAI, Amazon Bedrock plus **Region**), **Assistant model**, optional **Agent model**, enters the key, clicks **Save**. Bedrock needs an Amazon Bedrock API key (no AWS access keys or IAM roles). Disable to delete the key and return to defaults.

 ## Rules

 - Never put `Assistant.md` at the repo root: it would be served at `/assistant.md`. If it must live elsewhere, add it to `.mintignore`.
 - Skill frontmatter needs `name` and `description`. The description decides when the skill loads, so state when it applies. Keep descriptions distinct.
 - Skill directory slugs: lowercase letters, numbers, hyphens only. Duplicate slugs publish only one (warning in deployment log).
 - Skills: truncated at about 6,000 tokens, max three per response, self-contained, prose and code (no screenshots). Delete `.mintlify/assistant/skills/` and redeploy to remove all.
@@ -81,7 +81,7 @@
 }
 ```
 
-Widget. The widget is no longer configurable in the dashboard (an enabled widget's Widget settings entry only links to the docs). To enable the widget for a site, get a widget ID, or change authorized sites or availability, the user emails support@mintlify.com. Existing widgets keep working on their authorized sites. Install code comes from the playground on https://www.mintlify.com/docs/assistant/widget (do not invent the loader URL). Then initialize; `id` is the only required option:
+Widget. Not configurable in the dashboard; no new widgets. For a new site or app, the user builds one with the assistant API: Next.js tutorial https://www.mintlify.com/docs/guides/assistant-embed, or, for other frameworks, a coding agent given https://www.mintlify.com/docs/api/assistant/create-assistant-message-v2. Existing widgets keep working on their authorized sites; for changes, the user emails support@mintlify.com. Install code comes from the playground on https://www.mintlify.com/docs/assistant/widget (do not invent the loader URL). Then initialize; `id` is the only required option:
 ```js
 await window.MintlifyAssistant.init({
   id: "YOUR_WIDGET_ID",
@@ -93,7 +93,7 @@
  void window.MintlifyAssistant.open({ source: "help-button", focus: true });
 });
 ```
 Other methods: `ask(question, options)`, `update(config)` (pass `null` to reset a field), `close()`, `reset()`, `destroy()`. `identity` takes a signed end-user token; omit for anonymous visitors. Widget `supportEmail` and `starterQuestions` do not inherit from the dashboard. CSP: `script-src` and `connect-src` `https://widget.mintlify.com`, `connect-src` `https://api.mintlify.com` and `https://ph.mintlify.com`, plus hCaptcha (`https://js.hcaptcha.com`, `https://*.hcaptcha.com`) when bot protection is on. Pass `nonce` for a strict `style-src`.

 ## Verify


diff --git a/mint-instructions/publish/domain.mdx b/mint-instructions/publish/domain.mdx
@@ -1,7 +1,7 @@
 ---
 title: "Custom domain and subpath hosting"
 name: mintlify-publish-domain
 description: "Covers custom domains and where the site is served: mint add-domain, DNS and TLS, /docs subpaths, reverse proxies on Vercel, Cloudflare, and AWS, CSP, and iframes. Use for domain and hosting tasks."
 when: "Custom domain (mint add-domain), /docs subpath, reverse proxy, CSP"
 related: false
 ---
@@ -34,7 +34,7 @@

 ## Provider setups (base path `/docs`)

 - Vercel (`vercel.json` rewrites): `/_mintlify/:path*` to `https://<sub>.mintlify.site/_mintlify/:path*`, `/api/request` to `.../_mintlify/api/request`, `/docs` and `/docs/:match*` to `.../docs` and `.../docs/:match*`, `/mintlify-assets/:path+` to `.../mintlify-assets/:path+`. `/_mintlify` and `/mintlify-assets` are required. An external proxy in front of Vercel must pass `/.well-known/acme-challenge/*`, `/.well-known/vercel/*`, `/mintlify-assets/_next/static/*` untouched and forward `Host`.
 - Cloudflare Workers: the Worker script shown in the dashboard after adding the domain proxies only `/docs` and `/docs/*` to `<sub>.mintlify.site`, sets `Host` to that target, `X-Forwarded-Host` to the custom domain, `X-Forwarded-Proto: https`, and sends all other requests to the origin unchanged. It does not proxy root `/mintlify-assets/*` or `/_mintlify/*`. With route patterns, add `yoursite.com/mintlify-assets/*` and `yoursite.com/_mintlify/*` routes at the domain root. A Worker on a custom domain must route other traffic to the main site (Webflow pattern). WAF or Bot Fight Mode 403s on `/mintlify-assets/`: add a WAF Skip rule (hostname equals docs host, URI Path starts with `/mintlify-assets/`).
 - AWS Route 53 + CloudFront: two origins (`<sub>.mintlify.site`, the main site's staging URL). Six behaviors: `/docs`, `/docs/*`, `/_mintlify/*`, `/.well-known/*` with CachingDisabled; `/mintlify-assets/*` with CachingOptimized; `Default (*)` to the main site. All use origin request policy `AllViewerExceptHostHeader`. Subpath and `/_mintlify/*` behaviors allow GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE (GET/HEAD only breaks analytics). Add the domain as Alternate domain name with an ACM cert from `us-east-1`, then a Route 53 Alias record to the distribution.
 - Other reverse proxy (nginx etc.): proxy `/docs` and `/docs/*` (includes `/docs/_llms/*`) and `/.well-known/vercel/*` with no cache; optional root `/llms.txt`, `/llms-full.txt`, `/skill.md`, `/.well-known/skills/*`, `/.well-known/agent-skills/*` mapped to the files under `/docs` on the target. Forward all HTTP methods (analytics POSTs to `/docs/_mintlify/api/v1/e`). Set `Origin: <sub>.mintlify.site`, forward `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Real-IP`, `User-Agent`. Do not forward `Host`. Cache only `/mintlify-assets/_next/static/*`.
@@ -45,8 +45,8 @@
 - Only add the Mintlify CNAME with `--basePath` if the domain hosts nothing else.
 - Do not rewrite only `/docs/llms.txt` to root; forward the full base path route.
 - CSP: the default CSP allows any HTTPS origin; it blocks plain HTTP resources, `blob:`/`data:` scripts, `<object>`/`<embed>`, cross-origin workers. A proxy that overwrites CSP must allow the required domains (`*.mintlify.site`, `*.mintlify.com`, `mintcdn.com`, `*.mintcdn.com`, hCaptcha, two CloudFront hosts and more): copy the policy from the CSP page.
-- Iframes: default `frame-ancestors 'self' https://dashboard.mintlify.com https://app.mintlify.com` blocks other sites. It is not configurable in `docs.json`. Email support@mintlify.com with subdomain, docs domain, every origin (wildcard subdomains allowed) and use case. Own proxy overwriting CSP: set `frame-ancestors` there. Alternative: assistant widget (Pro or Enterprise).
+- Iframes: default `frame-ancestors 'self' https://dashboard.mintlify.com https://app.mintlify.com` blocks other sites. It is not configurable in `docs.json`. Email support@mintlify.com with subdomain, docs domain, every origin (wildcard subdomains allowed) and use case. Own proxy overwriting CSP: set `frame-ancestors` there. Alternative: build an in-app assistant with the assistant API (Pro or Enterprise; https://www.mintlify.com/docs/guides/assistant-embed).
 - Default address stays indexed: the default Mintlify address remains reachable and crawlable after adding a domain. Support can make it return 404, only if the CNAME points to `cname.mintlify.builders` (not with a reverse proxy or a CNAME to the default address). While disabled, new domains cannot be added from the dashboard. Also set the canonical and submit `https://<custom-domain>/sitemap.xml` in Search Console.
 - `Domain is already in use by another deployment in your organization` or `Domain is already claimed by another organization`: one project holds a domain at a time. Remove it (trash icon) on the holding project's Custom domain setup page, then re-add. No access to that org: email support with proof of DNS control.
 
 ## Examples
@@ -73,4 +73,4 @@
 - https://www.mintlify.com/docs/customize/custom-domain
 - https://www.mintlify.com/docs/deploy/docs-subpath
 - https://www.mintlify.com/docs/deploy/reverse-proxy
 - https://www.mintlify.com/docs/deploy/csp-configuration
diff --git a/poc-onboarding.mdx b/poc-onboarding.mdx
@@ -134,7 +134,7 @@

 <Tabs>
  <Tab title="Use Mintlify migration services">
    Ask your AE or SE whether migration is included in your POC. If it is, send:

    - Your current documentation URL or export.
    - Your list of sample pages.
@@ -259,15 +259,15 @@
 3. Record whether the answer is correct and cites the right page.
 4. Use wrong or missing answers to identify pages to update or create.

 Review unanswered and downvoted questions in [Assistant analytics](/analytics/assistant). If a relevant page is not cited, make its frontmatter `description` specific and unique.

 ### Test one additional AI workflow

 Choose the workflow most relevant to your evaluation:
 
 <AccordionGroup>
-  <Accordion title="Embed the assistant">
-    Add the [assistant widget](/assistant/widget) to your product, marketing site, or support portal.
+  <Accordion title="Build an in-app assistant">
+    Use the assistant API to [build your own assistant](/guides/assistant-embed) for your product, marketing site, or support portal.
   </Accordion>
 
   <Accordion title="Connect AI tools">
@@ -291,7 +291,7 @@
 | Engineers keep review control | The pull request and its checks. |
 | Complex content migrates correctly | Side-by-side sample pages. |
 | The assistant answers accurately | Your scored questions and cited pages. |
 | Content gaps are identifiable | Unanswered and downvoted questions in [Assistant analytics](/analytics/assistant). |
 | Readers find useful content | [Traffic](/analytics/traffic), [search](/analytics/search), and [engagement](/analytics/user-engagements) data. |
 | Automated updates are useful | The automation run history and proposed change. |

@@ -299,7 +299,7 @@

 ## Suggested timeline

 Most POCs take two to three weeks:

 | Week | Focus |
 |---|---|