Create assistant message
POST
/
v2
/
assistant
/
/
message
Assistant message
curl --request POST \
--url https://api.mintlify.com/discovery/v2/assistant/{domain}/message \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"fp": "<string>",
"messages": [
{
"id": "foobar",
"role": "user",
"parts": [
{
"type": "text",
"text": "How do I get started"
}
]
}
],
"threadId": null,
"retrievalPageSize": 5,
"filter": null,
"context": [
{
"value": "<string>",
"path": "<string>",
"elementId": "<string>"
}
],
"currentPath": "<string>"
}
'{}Integration with useChat
Section titled “Integration with useChat”The useChat hook from Vercel’s AI SDK is the recommended way to integrate the assistant API into your application.
Install AI SDK
shellscript npm i ai@^6 @ai-sdk/reactUse the hook
TSX import { useState } from "react"; import { useChat } from "@ai-sdk/react"; import { DefaultChatTransport } from "ai"; function MyComponent({ domain }) { const [input, setInput] = useState(""); const { messages, sendMessage } = useChat({ transport: new DefaultChatTransport({ api: `https://api.mintlify.com/discovery/v2/assistant/${domain}/message`, headers: { Authorization: `Bearer ${process.env.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.parts .filter((part) => part.type === "text") .map((part) => part.text) .join("")} </div> ))} <form onSubmit={(e) => { e.preventDefault(); if (input.trim()) { sendMessage({ text: input }); setInput(""); } }} > <input value={input} onChange={(e) => setInput(e.target.value)} /> <button type="submit">Send</button> </form> </div> ); }Required configuration:
transport- UseDefaultChatTransportto configure the API connection.body.fp- Fingerprint identifier (use'anonymous'or a unique user identifier).body.retrievalPageSize- Number of search results to use (recommended: 5).
Optional configuration:
body.context- Array of contextual information to provide to the assistant. Each context object contains:type- Either'code'or'textSelection'.value- The code snippet or selected text content.path(optional) - Path to the source file or page.elementId(optional) - Identifier for the UI element containing the context.
body.currentPath- 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.
See useChat and Transport in the AI SDK documentation for more details.
Rate limits
Section titled “Rate limits”The assistant API has the following limits:
- 10,000 requests per Mintlify organization per hour
- 10,000 requests per IP per day
Authorizations
Section titled “Authorizations”Authorization
string
header
required
The Authorization header expects a Bearer token. Use an assistant API key. Generate one on the API keys page in your dashboard. In production, proxy requests through your backend rather than embedding the key in client-side code.
Path Parameters
Section titled “Path Parameters”domain
string
required
The domain identifier from your domain.mintlify.site URL. Can be found at the end of your dashboard URL. For example, app.mintlify.com/organization/domain has a domain identifier of domain.
application/json
fp
string
required
Fingerprint identifier for tracking conversation sessions. Use anonymous for anonymous users or provide a unique user identifier.
messages
object[]
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 child attributes
threadId
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'.
retrievalPageSize
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.
filter
object
Optional filter criteria for the search.
Show child attributes
context
object[]
Optional array of contextual information to provide to the assistant.
Show child attributes
currentPath
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.
Response
Section titled “Response”200 - application/json
Message generated successfully
Streaming response compatible with AI SDK v5. Use the useChat hook from @ai-sdk/react to handle the response stream.
⌘I