Skip to main content
The assistant message v2 endpoint is compatible with AI SDK v5+. If you use AI SDK v4, use the assistant message v1 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

npm i ai@^6 @ai-sdk/react
2

Use the hook

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 - Use DefaultChatTransport to 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.
See useChat and Transport 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
curl -X POST https://api.mintlify.com/discovery/v2/assistant/{domain}/message \
  -H "Authorization: Bearer YOUR_ASSISTANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fp": "anonymous",
    "messages": [
      {
        "id": "msg-1",
        "role": "user",
        "parts": [
          {
            "type": "text",
            "text": "How do I get started?"
          }
        ]
      }
    ],
    "retrievalPageSize": 5
  }'

​
Endpoint

​
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.

​
Request Body

​
fp
string
required
Fingerprint identifier for tracking conversation sessions. Use anonymous for anonymous users or provide a unique user identifier.
​
messages
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.
​
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.
​
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'.
​
filter
object
Optional filter criteria for the search.
​
context
array
Optional array of contextual information to provide to the assistant.

​
Response

Streaming response compatible with AI SDK v5. Use the useChat hook from @ai-sdk/react to handle the response stream.

​
Authentication

This endpoint requires 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us