Assistant
Create assistant message
Generates a response message from the assistant for the specified domain. Compatible with AI SDK v5+.
Authenticate with an assistant API key.
POST
/
v2
/
assistant
/
{domain}
/
message
Create assistant message
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": [
{
"value": "<string>",
"path": "<string>",
"elementId": "<string>"
}
],
"currentPath": "<string>"
}
'import requests
url = "https://api.mintlify.com/discovery/v2/assistant/{domain}/message"
payload = {
"fp": "<string>",
"messages": [
{
"id": "foobar",
"role": "user",
"parts": [
{
"type": "text",
"text": "How do I get started"
}
]
}
],
"threadId": None,
"retrievalPageSize": 5,
"filter": None,
"context": [
{
"value": "<string>",
"path": "<string>",
"elementId": "<string>"
}
],
"currentPath": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fp: '<string>',
messages: [
{
id: 'foobar',
role: 'user',
parts: [{type: 'text', text: 'How do I get started'}]
}
],
threadId: null,
retrievalPageSize: 5,
filter: null,
context: [{value: '<string>', path: '<string>', elementId: '<string>'}],
currentPath: '<string>'
})
};
fetch('https://api.mintlify.com/discovery/v2/assistant/{domain}/message', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mintlify.com/discovery/v2/assistant/{domain}/message",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'fp' => '<string>',
'messages' => [
[
'id' => 'foobar',
'role' => 'user',
'parts' => [
[
'type' => 'text',
'text' => 'How do I get started'
]
]
]
],
'threadId' => null,
'retrievalPageSize' => 5,
'filter' => null,
'context' => [
[
'value' => '<string>',
'path' => '<string>',
'elementId' => '<string>'
]
],
'currentPath' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mintlify.com/discovery/v2/assistant/{domain}/message"
payload := strings.NewReader("{\n \"fp\": \"<string>\",\n \"messages\": [\n {\n \"id\": \"foobar\",\n \"role\": \"user\",\n \"parts\": [\n {\n \"type\": \"text\",\n \"text\": \"How do I get started\"\n }\n ]\n }\n ],\n \"threadId\": null,\n \"retrievalPageSize\": 5,\n \"filter\": null,\n \"context\": [\n {\n \"value\": \"<string>\",\n \"path\": \"<string>\",\n \"elementId\": \"<string>\"\n }\n ],\n \"currentPath\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mintlify.com/discovery/v2/assistant/{domain}/message")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"fp\": \"<string>\",\n \"messages\": [\n {\n \"id\": \"foobar\",\n \"role\": \"user\",\n \"parts\": [\n {\n \"type\": \"text\",\n \"text\": \"How do I get started\"\n }\n ]\n }\n ],\n \"threadId\": null,\n \"retrievalPageSize\": 5,\n \"filter\": null,\n \"context\": [\n {\n \"value\": \"<string>\",\n \"path\": \"<string>\",\n \"elementId\": \"<string>\"\n }\n ],\n \"currentPath\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mintlify.com/discovery/v2/assistant/{domain}/message")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"fp\": \"<string>\",\n \"messages\": [\n {\n \"id\": \"foobar\",\n \"role\": \"user\",\n \"parts\": [\n {\n \"type\": \"text\",\n \"text\": \"How do I get started\"\n }\n ]\n }\n ],\n \"threadId\": null,\n \"retrievalPageSize\": 5,\n \"filter\": null,\n \"context\": [\n {\n \"value\": \"<string>\",\n \"path\": \"<string>\",\n \"elementId\": \"<string>\"\n }\n ],\n \"currentPath\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{}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>
);
}
transport- UseDefaultChatTransportto 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).
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.
Migrate from v1
The v1 endpoint is discontinued and returns410 Gone. To migrate, change the URL from /discovery/v1/assistant/{domain}/message to /discovery/v2/assistant/{domain}/message and update your messages and stream handling.
Your API key and these body fields don’t change: fp, threadId, threadKey, regenerate, retrievalPageSize, filter, context, and currentPath.
If you use useChat
Upgrade to AI SDK v5 or later and use DefaultChatTransport as shown in Integration with useChat. Remove streamProtocol and sendExtraMessageFields. They aren’t needed in v2. Render messages from message.parts instead of message.content.
If you call the API directly
Messages useparts instead of content. Remove the content string and send text as a text part. The data role is no longer accepted.
{
"id": "msg_1",
"role": "user",
"content": "How do I get started?",
"parts": [{ "type": "text", "text": "How do I get started?" }]
}
{
"id": "msg_1",
"role": "user",
"parts": [{ "type": "text", "text": "How do I get started?" }]
}
file parts. Replace experimental_attachments with entries in parts.
{
"experimental_attachments": [
{ "name": "screenshot.png", "contentType": "image/png", "url": "data:image/png;base64,..." }
]
}
{
"parts": [
{ "type": "file", "filename": "screenshot.png", "mediaType": "image/png", "url": "data:image/png;base64,..." }
]
}
0:"..." lines. v2 returns the AI SDK UI message stream. Each event is a data: {...} JSON line, text arrives in text-delta events, and the stream ends with data: [DONE]. The X-Thread-Id, X-Thread-Key, and X-Message-Id response headers are unchanged.
Rate limits
The assistant API has the following limit:- 10,000 requests per Mintlify organization per hour
Authorizations
The Authorization header expects a Bearer token. Use an assistant API key. Generate one on the API keys page in your dashboard. In production, proxy requests through your backend rather than embedding the key in client-side code.
Path Parameters
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
Fingerprint identifier for tracking conversation sessions. Use anonymous for anonymous users or provide a unique user identifier.
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.
Show child attributes
Show child attributes
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'.
Number of documentation search results to use for generating the response. Higher values provide more context but may increase response time. Recommended: 5.
Optional filter criteria for the search.
Show child attributes
Show child attributes
Optional array of contextual information to provide to the assistant.
Show child attributes
Show child attributes
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
Message generated successfully
Streaming response compatible with AI SDK v5. Use the useChat hook from @ai-sdk/react to handle the response stream.
⌘I
Create assistant message
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": [
{
"value": "<string>",
"path": "<string>",
"elementId": "<string>"
}
],
"currentPath": "<string>"
}
'import requests
url = "https://api.mintlify.com/discovery/v2/assistant/{domain}/message"
payload = {
"fp": "<string>",
"messages": [
{
"id": "foobar",
"role": "user",
"parts": [
{
"type": "text",
"text": "How do I get started"
}
]
}
],
"threadId": None,
"retrievalPageSize": 5,
"filter": None,
"context": [
{
"value": "<string>",
"path": "<string>",
"elementId": "<string>"
}
],
"currentPath": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fp: '<string>',
messages: [
{
id: 'foobar',
role: 'user',
parts: [{type: 'text', text: 'How do I get started'}]
}
],
threadId: null,
retrievalPageSize: 5,
filter: null,
context: [{value: '<string>', path: '<string>', elementId: '<string>'}],
currentPath: '<string>'
})
};
fetch('https://api.mintlify.com/discovery/v2/assistant/{domain}/message', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mintlify.com/discovery/v2/assistant/{domain}/message",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'fp' => '<string>',
'messages' => [
[
'id' => 'foobar',
'role' => 'user',
'parts' => [
[
'type' => 'text',
'text' => 'How do I get started'
]
]
]
],
'threadId' => null,
'retrievalPageSize' => 5,
'filter' => null,
'context' => [
[
'value' => '<string>',
'path' => '<string>',
'elementId' => '<string>'
]
],
'currentPath' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mintlify.com/discovery/v2/assistant/{domain}/message"
payload := strings.NewReader("{\n \"fp\": \"<string>\",\n \"messages\": [\n {\n \"id\": \"foobar\",\n \"role\": \"user\",\n \"parts\": [\n {\n \"type\": \"text\",\n \"text\": \"How do I get started\"\n }\n ]\n }\n ],\n \"threadId\": null,\n \"retrievalPageSize\": 5,\n \"filter\": null,\n \"context\": [\n {\n \"value\": \"<string>\",\n \"path\": \"<string>\",\n \"elementId\": \"<string>\"\n }\n ],\n \"currentPath\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mintlify.com/discovery/v2/assistant/{domain}/message")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"fp\": \"<string>\",\n \"messages\": [\n {\n \"id\": \"foobar\",\n \"role\": \"user\",\n \"parts\": [\n {\n \"type\": \"text\",\n \"text\": \"How do I get started\"\n }\n ]\n }\n ],\n \"threadId\": null,\n \"retrievalPageSize\": 5,\n \"filter\": null,\n \"context\": [\n {\n \"value\": \"<string>\",\n \"path\": \"<string>\",\n \"elementId\": \"<string>\"\n }\n ],\n \"currentPath\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mintlify.com/discovery/v2/assistant/{domain}/message")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"fp\": \"<string>\",\n \"messages\": [\n {\n \"id\": \"foobar\",\n \"role\": \"user\",\n \"parts\": [\n {\n \"type\": \"text\",\n \"text\": \"How do I get started\"\n }\n ]\n }\n ],\n \"threadId\": null,\n \"retrievalPageSize\": 5,\n \"filter\": null,\n \"context\": [\n {\n \"value\": \"<string>\",\n \"path\": \"<string>\",\n \"elementId\": \"<string>\"\n }\n ],\n \"currentPath\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{}