Create assistant message (v1)

Generates a response message from the assistant for the specified domain. Compatible with AI SDK v4.

POST /v1/assistant/{domain}/message

Assistant message v1

cURL

curl --request POST \
  --url https://api.mintlify.com/discovery/v1/assistant/{domain}/message \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fp": "<string>",
  "messages": [
    {
      "id": "foobar",
      "role": "user",
      "content": "how do i get started",
      "parts": [
        {
          "type": "text",
          "text": "How do I get started"
        }
      ]
    }
  ],
  "threadId": null,
  "retrievalPageSize": 5,
  "filter": null,
  "context": [
    {
      "value": "<string>",
      "path": "<string>",
      "elementId": "<string>"
    }
  ],
  "currentPath": "<string>"
}
'

200

{}

Deprecated

The assistant message v1 endpoint is compatible with AI SDK v4. If you use AI SDK v5 or later, use the assistant message v2 endpoint instead.

Integration with useChat

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

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.mintlify.com/discovery/v1/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',
           },
         ],
       },
       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).

   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.
     • 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 in the AI SDK documentation for more details.

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

Authorization · string · header · required

The Authorization header expects a Bearer token. Use an assistant API key (prefixed with mint_dsc_). This is a public key safe for use in client-side code. Generate one on the API keys page in your dashboard.

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

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

200 - application/json

Message generated successfully

Response object with data stream parts formatted with the specified status, headers, and content. For more information, see the AI SDK documentation at ai-sdk.dev/docs/ai-sdk-ui/streaming-data. Use the useChat hook from ai-sdk to handle the response stream.