Assistant message

Generates a response message from the assistant for the specified domain.

Integration with useChat

The useChat hook from Vercel’s AI SDK is the recommended way to integrate the assistant API into your application.

The Mintlify assistant API is compatible with AI SDK v4. If you use AI SDK v5 or later, you must configure a custom transport.

1. Install AI SDK v4

   npm i ai@^4.1.15
   

2. Use the hook

   import { useChat } from 'ai/react';
   
   function MyComponent({ domain }) {
     const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
       api: `https://api-dsc.mintlify.com/v1/assistant/${domain}/message`,
       headers: {
         'Authorization': `Bearer ${process.env.MINTLIFY_TOKEN}`,
       },
       body: {
         fp: 'anonymous',
         retrievalPageSize: 5,
       },
       streamProtocol: 'data',
       sendExtraMessageFields: true,
     });
   
     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>
     );
   }
   

   Required configuration for Mintlify:

   • streamProtocol: 'data' - Required for streaming responses.
   • sendExtraMessageFields: true - Required to send message metadata.
   • body.fp - Fingerprint identifier (use ‘anonymous’ or a user identifier).
   • body.retrievalPageSize - Number of search results to use (recommended: 5).

See useChat in the AI SDK documentation for more details.

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

Authorizations

Authorization · string · header · required

The Authorization header expects a Bearer token. See the Assistant API Key documentation for details on how to get your API key.

Path Parameters

domain · 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

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. On the frontend, you will likely want to use the handleSubmit function from the @ai-sdk package's useChat hook to append user messages and handle streaming responses, rather than manually defining the objects in this array as they have so many parameters.

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

Response

200 - application/json

Message generated successfully

Response object that streams formatted data stream parts with the specified status, headers, and content. This matches what is expected from the AI SDK as documented at ai-sdk.dev/docs/ai-sdk-ui/streaming-data. Instead of writing your own parser, it is recommended to use the useChat hook from ai-sdk as documented here.