Skip to main content
POST
/
v2
/
assistant
/
{domain}
/
message
Assistant message v2
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": [
    {
      "type": "code",
      "value": "<string>",
      "path": "<string>",
      "elementId": "<string>"
    }
  ]
}
'
{}
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

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. Use the handleSubmit function from the @ai-sdk/react package's useChat hook to manage messages and streaming responses.

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

​
context
object[]

Optional array of contextual information to provide to the assistant.

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.