Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
9867568
create guides
ethanpalm Oct 20, 2025
3e23ba6
add new pages to docs.json
ethanpalm Oct 20, 2025
e97420a
alphabetize sidebar nav
ethanpalm Oct 20, 2025
9c051fe
add content for widget guide
ethanpalm Oct 20, 2025
9f98c81
review code samples
ethanpalm Oct 20, 2025
47c11cd
add content to deflection guide
ethanpalm Oct 20, 2025
f1fcda8
Update assistant-widget.mdx
ethanpalm Oct 21, 2025
0c097bc
replace `domain` with `project`
ethanpalm Oct 21, 2025
fa133a5
update reference
ethanpalm Oct 21, 2025
79b47c5
update testing info
ethanpalm Oct 21, 2025
ed3ce97
copy edit
ethanpalm Oct 21, 2025
68f29f3
💅
ethanpalm Oct 21, 2025
b0b9e7b
replace table with parafields
ethanpalm Oct 21, 2025
a784dc2
concision
ethanpalm Oct 21, 2025
d84450e
use accordion for troubleshooting
ethanpalm Oct 21, 2025
e6051b8
Merge branch 'main' into assistant-api-guides
ethanpalm Oct 23, 2025
0fb6ffe
fix parameter names
ethanpalm Oct 23, 2025
a352ac3
improve code sample
ethanpalm Oct 23, 2025
9f8c80c
remove deflection guide
ethanpalm Oct 23, 2025
595fde4
improve UX of sample code
ethanpalm Oct 23, 2025
dfb124e
tweak code sample
ethanpalm Oct 24, 2025
0fda0ce
simplify sample code
ethanpalm Oct 27, 2025
7f5a0ed
Merge branch 'main' into assistant-api-guides
ethanpalm Oct 31, 2025
69a7086
rename guide
ethanpalm Oct 31, 2025
253e033
edit intro
ethanpalm Oct 31, 2025
51b27e4
update prerequisites
ethanpalm Oct 31, 2025
77d72f9
use vite for consistency with sample code
ethanpalm Oct 31, 2025
55a46b8
clarify `domain`
ethanpalm Oct 31, 2025
0c4c583
copyedits
ethanpalm Oct 31, 2025
0cdfc57
set TODO:s
ethanpalm Oct 31, 2025
8b444a9
simplify sample code
ethanpalm Oct 31, 2025
9f0893e
update the verify steps
ethanpalm Oct 31, 2025
38a4c31
Update assistant-embed.mdx
ethanpalm Nov 1, 2025
80eb859
add missing option
ethanpalm Nov 5, 2025
0ee197b
review intro
ethanpalm Nov 5, 2025
209700c
add preview button
ethanpalm Nov 5, 2025
3f9273f
use steps
ethanpalm Nov 5, 2025
cbcc7b8
move verify section
ethanpalm Nov 5, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -234,9 +234,10 @@
"icon": "bot",
"pages": [
"guides/automate-agent",
"guides/geo",
"guides/assistant-embed",
"guides/claude-code",
"guides/cursor",
"guides/geo",
"guides/windsurf"
]
},
Expand Down
281 changes: 281 additions & 0 deletions guides/assistant-embed.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,281 @@
---
title: "Tutorial: Build an in-app documentation assistant"
sidebarTitle: "Build an in-app assistant"
description: "Embed the assistant in your application to answer questions with information from your documentation"

Check warning on line 4 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L4

Use 'app' instead of 'application'.
---

import { PreviewButton } from "/snippets/previewbutton.jsx"

## What you will build

Check warning on line 9 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L9

Avoid using 'will'.

A reusable React component that embeds the [assistant](/ai/assistant) directly in your application. The component provides:

Check warning on line 11 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L11

Use 'app' instead of 'application'.

- A floating widget that opens a chat panel when clicked
- Real-time streaming responses based on information from your documentation

Users can use the widget to get help with your product without leaving your application.

Check warning on line 16 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L16

Use 'app' instead of 'application'.

<PreviewButton href="https://github.com/mintlify/">Clone the repository to start working with a complete example locally.</PreviewButton>

## Prerequisites

- [Mintlify Pro or Custom plan](https://mintlify.com/pricing)
- Your domain name, which appears at the end of your dashboard URL. For example, if your dashboard URL is `https://dashboard.mintlify.com/org-name/domain-name`, your domain name is `domain-name`
- An [assistant API key](https://dashboard.mintlify.com/settings/organization/api-keys)
- Node.js v18 or higher and npm installed
- Basic React knowledge
- Existing React application (Next.js, Vite, Create React App, or similar). This guide uses a Vite application

Check warning on line 27 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L27

Use 'app' instead of 'application'.

### Get your assistant API key

1. Navigate to the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard.
2. Click **Create Assistant API Key**.
3. Copy the assistant API key (starts with `mint_dsc_`) and save it securely.

Check warning on line 33 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L33

Use parentheses judiciously.

<Note>
The assistant API key is a public token that can be used in frontend code. Calls using this token count toward your plan's message allowance and can incur overages.

Check warning on line 36 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L36

In general, use active voice instead of passive voice ('be used').
</Note>

## Build the widget

<Steps>
<Step title="Install dependencies">

Install the AI SDK for React and a Markdown renderer:

```bash
npm install ai @ai-sdk/react react-markdown
```
</Step>
<Step title="Create the assistant component">

Create a new file `AssistantWidget.jsx` (or `.tsx` if using TypeScript) in your components directory:

```jsx AssistantWidget.jsx expandable
import { useChat } from '@ai-sdk/react';

Check warning on line 55 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L55

Use semicolons judiciously.
import { useState } from 'react';
import ReactMarkdown from 'react-markdown';

export function AssistantWidget({ domain }) {
const [isOpen, setIsOpen] = useState(false);

const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
api: `https://api-dsc.mintlify.com/v1/assistant/${domain}/message`,
headers: {
'Authorization': `Bearer ${process.env.VITE_MINTLIFY_TOKEN}`,
},
body: {
fp: 'anonymous',
retrievalPageSize: 5,
},
streamProtocol: 'data',
sendExtraMessageFields: true,
});

return (
<>
<button
onClick={() => setIsOpen(!isOpen)}
className="fixed bottom-4 right-4 px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
>
{isOpen ? 'Close' : 'Ask'}
</button>

{isOpen && (
<div className="fixed bottom-16 right-4 w-96 h-[500px] bg-white rounded-lg shadow-xl flex flex-col z-50 border border-gray-200">
<div className="p-4 border-b border-gray-200 bg-gray-50 rounded-t-lg">
<h3 className="font-semibold text-gray-900">Documentation assistant</h3>
</div>

<div className="flex-1 overflow-y-auto p-4 space-y-4">
{messages.map((message) => (
<div key={message.id} className={`flex ${message.role === 'user' ? 'justify-end' : 'justify-start'}`}>
<div className={`max-w-[75%] rounded-lg px-4 py-2 ${message.role === 'user' ? 'bg-blue-600 text-white' : 'bg-gray-100 text-gray-900'}`}>
{message.role === 'user' ? (
<div className="text-sm">{message.content}</div>
) : (
<ReactMarkdown className="prose prose-sm max-w-none text-sm">{message.content}</ReactMarkdown>
)}
</div>
</div>
))}

{isLoading && <div className="text-gray-500 text-sm">Loading...</div>}
</div>

<form onSubmit={handleSubmit} className="p-4 border-t border-gray-200 bg-white rounded-b-lg">
<div className="flex gap-2">
<input
type="text"
value={input}
onChange={handleInputChange}
placeholder="Ask a question..."
className="flex-1 px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500 text-sm"
disabled={isLoading}
/>
<button
type="submit"
disabled={isLoading || !input.trim()}
className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 disabled:bg-gray-400 text-sm"
>
Send
</button>
</div>
</form>
</div>
)}
</>
);
}
```

</Step>
<Step title="Configure environment variables">

Add your assistant API token to your `.env` file in your project root:

```bash .env
VITE_MINTLIFY_TOKEN=mint_dsc_your_token_here
```

Restart your development server to apply the changes.

<Note>
Vite requires environment variables to be prefixed with `VITE_`. Use the appropriate prefix for your framework.

Check warning on line 144 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L144

In general, use active voice instead of passive voice ('be prefixed').
</Note>

</Step>
<Step title="Add the widget to your app">

Import and render the component in your application. Pass your Mintlify project `domain` (the end of your dashboard URL. For example, `domain-name` from `https://dashboard.mintlify.com/org-name/domain-name`).

Check warning on line 150 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L150

Use 'app' instead of 'application'.

```jsx App.jsx
import { AssistantWidget } from './components/AssistantWidget';

function App() {
return (
<div>
{/* Your existing app content */}
<AssistantWidget domain="yourcompany" />
</div>
);
}

export default App;
```

</Step>
<Step title="Test the widget">
1. Start your development server:
```bash
npm run dev
```
2. Open your application in a browser.

Check warning on line 173 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L173

Use 'app' instead of 'application'.
3. Click the "Ask" button in the bottom-right corner.
4. Ask a question about your documentation.
</Step>
</Steps>

## Customization ideas

This example shows a simple implementation of the assistant API. Here are some ways to begin customizing the widget.

### Add color customization

Accept color props and use them for theming:

```jsx
export function AssistantWidget({ domain, buttonColor = '#2563eb' }) {
// ... rest of component
return (
<>
<button
style={{ backgroundColor: buttonColor }}
// ... rest of button
>
```

### Add widget positioning options

Let users position the widget in different corners:

```jsx
export function AssistantWidget({ domain, position = 'bottom-right' }) {
const positions = {
'bottom-right': 'bottom-4 right-4',
'bottom-left': 'bottom-4 left-4',
'top-right': 'top-4 right-4',
'top-left': 'top-4 left-4',
};

return (
<>
<button className={`fixed ${positions[position]} ...`}
```

### Source citations

Extract and display sources from assistant responses:

```jsx
const extractSources = (parts) => {
return parts
?.filter(p => p.type === 'tool-invocation' && p.toolInvocation?.toolName === 'search')
.flatMap(p => p.toolInvocation?.result || [])
.map(source => ({
url: source.url || source.path,
title: source.metadata?.title || source.path,
})) || [];
};

// In your message rendering:
{messages.map((message) => {
const sources = message.role === 'assistant' ? extractSources(message.parts) : [];
return (
<div key={message.id}>
{/* message content */}
{sources.length > 0 && (
<div className="mt-2 text-xs">
<p className="font-semibold">Sources:</p>
{sources.map((s, i) => (
<a key={i} href={s.url} target="_blank" className="text-blue-600">
{s.title}
</a>
))}
</div>
)}
</div>
);
})}
```

## Troubleshooting

<AccordionGroup>
<Accordion title="Widget not appearing">
- Verify the component is imported and rendered in your app.

Check warning on line 256 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L256

In general, use active voice instead of passive voice ('is imported').
- Check that Tailwind CSS or your styling solution is properly configured.
- Ensure the z-index values do not conflict with other fixed elements.

Check warning on line 258 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L258

Use 'don't' instead of 'do not'.
</Accordion>

<Accordion title="401 authentication error">
- Verify your API token starts with `mint_dsc_`.
- Check the token is correctly set in your environment variables.
- Confirm you are using the public assistant API token, not the admin API key.

Check warning on line 264 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L264

Use 'administrator' instead of 'admin'.
- Restart your development server after adding environment variables.
</Accordion>

<Accordion title="No responses from assistant">
- Verify your project domain is correct.
- Check that your Mintlify plan includes the assistant feature.
- Confirm your documentation site is published and accessible.

Check warning on line 271 in guides/assistant-embed.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/assistant-embed.mdx#L271

In general, use active voice instead of passive voice ('is published').
- Verify the assistant API token is correctly set in your environment variables.
</Accordion>

<Accordion title="Debugging with browser console">
Open developer tools and check the Network tab to troubleshoot:
- Look for 401 or 403 authentication errors
- Verify API requests are reaching `https://api-dsc.mintlify.com/v1/assistant/{domain}/message`
- Check the response status and error messages
</Accordion>
</AccordionGroup>