# 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 ' \ --header 'Content-Type: application/json' \ --data ' { "fp": "", "messages": [ { "id": "foobar", "role": "user", "parts": [ { "type": "text", "text": "How do I get started" } ] } ], "threadId": null, "retrievalPageSize": 5, "filter": null, "context": [ { "value": "", "path": "", "elementId": "" } ], "currentPath": "" } ' ``` :::code-group ```title="200" {} ``` ::: :::callout{intent="info"} The assistant message v2 endpoint is compatible with **AI SDK v5+**. If you use AI SDK v4, use the [assistant message v1 endpoint](https://www.mintlify.com/docs/api/assistant/create-assistant-message) instead. ::: ## Integration with `useChat` The `useChat` hook from Vercel’s AI SDK is the recommended way to integrate the assistant API into your application. ::::steps :::step{title="Install AI SDK"} ```shellscript npm i ai@^6 @ai-sdk/react ``` ::: :::step{title="Use 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 (
{messages.map((message) => (
{message.role === "user" ? "User: " : "Assistant: "} {message.parts .filter((part) => part.type === "text") .map((part) => part.text) .join("")}
))}
{ e.preventDefault(); if (input.trim()) { sendMessage({ text: input }); setInput(""); } }} > setInput(e.target.value)} />
); } ``` **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. - `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](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) and [Transport](https://ai-sdk.dev/docs/ai-sdk-ui/transport) 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. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. In production, proxy requests through your backend rather than embedding the key in client-side code. #### 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`. #### 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. :::accordion{title="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. :::accordion{title="Show child attributes"} ::: context object\[] Optional array of contextual information to provide to the assistant. :::accordion{title="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 Streaming response compatible with AI SDK v5. Use the [useChat hook from @ai-sdk/react](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) to handle the response stream. ⌘I ## Related pages - [Admin](./admin-index.md) - [Agent](./agent-2-index.md) - [Agent](./agent-index.md) - [Agent-ready content](./agent-ready-content-index.md) - [AI](./ai-index.md) - [Analytics](./analytics-index.md) - [API docs](./api-docs-index.md) - [API reference](./api-reference-index.md) - [Assistant](./assistant-2-index.md) - [Assistant](./assistant-index.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.