curl -X POST https://api.mintlify.com/discovery/v2/assistant/your-domain/message \
-H "Authorization: Bearer mint_dsc_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"fp": "anonymous",
"messages": [
{
"id": "msg1",
"role": "user",
"parts": [
{
"type": "text",
"text": "How do I get started?"
}
]
}
],
"retrievalPageSize": 5
}'
import { useChat } from '@ai-sdk/react';
function MyComponent() {
const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
api: 'https://api.mintlify.com/discovery/v2/assistant/your-domain/message',
headers: {
'Authorization': `Bearer ${process.env.NEXT_PUBLIC_MINTLIFY_ASSISTANT_KEY}`,
},
body: {
fp: 'anonymous',
retrievalPageSize: 5,
context: [
{
type: 'code',
value: 'const example = "code snippet";',
elementId: 'code-block-1',
},
],
},
});
return (
<div>
{messages.map((message) => (
<div key={message.id}>
{message.role === 'user' ? 'User: ' : 'Assistant: '}
{message.content}
</div>
))}
<form onSubmit={handleSubmit}>
<input value={input} onChange={handleInputChange} />
<button type="submit">Send</button>
</form>
</div>
);
}
const response = await fetch(
'https://api.mintlify.com/discovery/v2/assistant/your-domain/message',
{
method: 'POST',
headers: {
'Authorization': 'Bearer mint_dsc_your_api_key_here',
'Content-Type': 'application/json',
},
body: JSON.stringify({
fp: 'anonymous',
messages: [
{
id: 'msg1',
role: 'user',
parts: [
{
type: 'text',
text: 'How do I get started?'
}
]
}
],
retrievalPageSize: 5
}),
}
);
// Handle streaming response
const reader = response.body.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(new TextDecoder().decode(value));
}
{
"type": "streaming",
"description": "Streaming response compatible with AI SDK v5. Use the useChat hook from @ai-sdk/react to handle the response stream."
}
Assistant
Generate Assistant Message
Embed the assistant, trained on your docs, into any application
POST
/
discovery
/
v2
/
assistant
/
{domain}
/
message
curl -X POST https://api.mintlify.com/discovery/v2/assistant/your-domain/message \
-H "Authorization: Bearer mint_dsc_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"fp": "anonymous",
"messages": [
{
"id": "msg1",
"role": "user",
"parts": [
{
"type": "text",
"text": "How do I get started?"
}
]
}
],
"retrievalPageSize": 5
}'
import { useChat } from '@ai-sdk/react';
function MyComponent() {
const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
api: 'https://api.mintlify.com/discovery/v2/assistant/your-domain/message',
headers: {
'Authorization': `Bearer ${process.env.NEXT_PUBLIC_MINTLIFY_ASSISTANT_KEY}`,
},
body: {
fp: 'anonymous',
retrievalPageSize: 5,
context: [
{
type: 'code',
value: 'const example = "code snippet";',
elementId: 'code-block-1',
},
],
},
});
return (
<div>
{messages.map((message) => (
<div key={message.id}>
{message.role === 'user' ? 'User: ' : 'Assistant: '}
{message.content}
</div>
))}
<form onSubmit={handleSubmit}>
<input value={input} onChange={handleInputChange} />
<button type="submit">Send</button>
</form>
</div>
);
}
const response = await fetch(
'https://api.mintlify.com/discovery/v2/assistant/your-domain/message',
{
method: 'POST',
headers: {
'Authorization': 'Bearer mint_dsc_your_api_key_here',
'Content-Type': 'application/json',
},
body: JSON.stringify({
fp: 'anonymous',
messages: [
{
id: 'msg1',
role: 'user',
parts: [
{
type: 'text',
text: 'How do I get started?'
}
]
}
],
retrievalPageSize: 5
}),
}
);
// Handle streaming response
const reader = response.body.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(new TextDecoder().decode(value));
}
{
"type": "streaming",
"description": "Streaming response compatible with AI SDK v5. Use the useChat hook from @ai-sdk/react to handle the response stream."
}
Generates a response message from the assistant for the specified domain. Compatible with AI SDK v5+. This endpoint enables you to embed Mintlify’s AI assistant into your product, support portal, or internal tools.
This is the v2 endpoint compatible with AI SDK v5+. If you use AI SDK v4, see the deprecated v1 endpoint in the source documentation.
Authentication
Requires an assistant API key (prefixed withmint_dsc_). Generate one on the API keys page in your dashboard.
The assistant API key is a public token that you can reference in frontend code.
Calls using the assistant API token can incur costs: either using your assistant credits or incurring overages.
Path Parameters
string
required
The domain identifier from your
domain.mintlify.app URL. Can be found at the end of your dashboard URL. For example, dashboard.mintlify.com/organization/domain has a domain identifier of domain.Body Parameters
string
required
Fingerprint identifier for tracking conversation sessions. Use
anonymous for anonymous users or provide a unique user identifier.array
required
Array of messages in the conversation. Use the handleSubmit function from the @ai-sdk/react package’s useChat hook to manage messages and streaming responses.
Show Message object
Show Message object
string
required
Unique identifier for the message.
string
required
The role of the message sender. Possible values:
system, assistant, user.array
required
Array of message parts. Each part has a type and type-specific fields (e.g., text, reasoning, source-url, file, step-start).
string
Timestamp when the message was created (ISO 8601 format).
object
Optional metadata associated with the message.
string
An optional identifier used to maintain conversation continuity across multiple messages. When provided, it allows the system to associate follow-up messages with the same conversation thread. The
threadId is returned in the response as event.threadId when event.type === 'finish'.number
default:5
Number of documentation search results to use for generating the response. Higher values provide more context but may increase response time. Recommended: 5.
object
array
Optional array of contextual information to provide to the assistant.
string
The path of the page the user is currently viewing. When provided, the assistant uses this context to provide more relevant answers. Maximum length: 200 characters.
Rate limits
The assistant API has the following limits:- 10,000 uses per key per month
- 10,000 requests per Mintlify organization per hour
- 10,000 requests per IP per day
Integration with useChat
TheuseChat hook from Vercel’s AI SDK is the recommended way to integrate the assistant API into your application.
curl -X POST https://api.mintlify.com/discovery/v2/assistant/your-domain/message \
-H "Authorization: Bearer mint_dsc_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"fp": "anonymous",
"messages": [
{
"id": "msg1",
"role": "user",
"parts": [
{
"type": "text",
"text": "How do I get started?"
}
]
}
],
"retrievalPageSize": 5
}'
import { useChat } from '@ai-sdk/react';
function MyComponent() {
const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
api: 'https://api.mintlify.com/discovery/v2/assistant/your-domain/message',
headers: {
'Authorization': `Bearer ${process.env.NEXT_PUBLIC_MINTLIFY_ASSISTANT_KEY}`,
},
body: {
fp: 'anonymous',
retrievalPageSize: 5,
context: [
{
type: 'code',
value: 'const example = "code snippet";',
elementId: 'code-block-1',
},
],
},
});
return (
<div>
{messages.map((message) => (
<div key={message.id}>
{message.role === 'user' ? 'User: ' : 'Assistant: '}
{message.content}
</div>
))}
<form onSubmit={handleSubmit}>
<input value={input} onChange={handleInputChange} />
<button type="submit">Send</button>
</form>
</div>
);
}
const response = await fetch(
'https://api.mintlify.com/discovery/v2/assistant/your-domain/message',
{
method: 'POST',
headers: {
'Authorization': 'Bearer mint_dsc_your_api_key_here',
'Content-Type': 'application/json',
},
body: JSON.stringify({
fp: 'anonymous',
messages: [
{
id: 'msg1',
role: 'user',
parts: [
{
type: 'text',
text: 'How do I get started?'
}
]
}
],
retrievalPageSize: 5
}),
}
);
// Handle streaming response
const reader = response.body.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(new TextDecoder().decode(value));
}
{
"type": "streaming",
"description": "Streaming response compatible with AI SDK v5. Use the useChat hook from @ai-sdk/react to handle the response stream."
}