Crear mensaje del assistant (v1)
Genera un mensaje de respuesta del assistant para el domain especificado. Compatible con AI SDK v4.
Autentícate con una clave de API del assistant.
POST
/
v1
/
assistant
/
{domain}
/
message
Crear mensaje del assistant (v1)
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>"
}
'import requests
url = "https://api.mintlify.com/discovery/v1/assistant/{domain}/message"
payload = {
"fp": "<string>",
"messages": [
{
"id": "foobar",
"role": "user",
"content": "how do i get started",
"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',
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>'
})
};
fetch('https://api.mintlify.com/discovery/v1/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/v1/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',
'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>'
]),
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/v1/assistant/{domain}/message"
payload := strings.NewReader("{\n \"fp\": \"<string>\",\n \"messages\": [\n {\n \"id\": \"foobar\",\n \"role\": \"user\",\n \"content\": \"how do i get started\",\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/v1/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 \"content\": \"how do i get started\",\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/v1/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 \"content\": \"how do i get started\",\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{}En desuso
Integración con
El hook Configuración obligatoria para Mintlify:
Consulta useChat en la documentación del AI SDK para obtener más información.
La API del assistant tiene el siguiente límite:
El endpoint assistant message v1 es compatible con AI SDK v4. Si utilizas AI SDK v5 o posterior, usa en su lugar el endpoint assistant message v2.
Integración con useChat
useChat del AI SDK de Vercel es la forma recomendada de integrar la API del assistant en tu aplicación.
1
Instalar el AI SDK v4
npm i ai@^4.1.15
2
Usar el 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' ? 'Usuario: ' : 'Assistant: '}
{message.content}
</div>
))}
<form onSubmit={handleSubmit}>
<input value={input} onChange={handleInputChange} />
<button type="submit">Enviar</button>
</form>
</div>
);
}
streamProtocol: 'data'- Obligatorio para respuestas en streaming.sendExtraMessageFields: true- Obligatorio para enviar metadatos de los mensajes.body.fp- Identificador de huella digital (usa ‘anonymous’ o un identificador de usuario).body.retrievalPageSize- Número de resultados de búsqueda que se usarán (recomendado: 5).
body.context- Array de información contextual que se proporciona al assistant. Cada objeto de contexto incluye:type- Puede ser'code'o'textSelection'.value- El fragmento de código o el contenido de texto seleccionado.elementId(opcional) - Identificador del elemento de la interfaz de usuario que contiene el contexto.
body.currentPath- La ruta de la página que el usuario está viendo actualmente. Cuando se proporciona, el assistant utiliza este contexto para ofrecer respuestas más relevantes. Longitud máxima: 200 caracteres.
Límites de uso
- 10,000 solicitudes por organización de Mintlify por hora
Authorizations
El encabezado Authorization requiere un token de tipo Bearer. Usa una clave de API del assistant. Genérala desde la página de claves de API de tu dashboard. En producción, envía las solicitudes a través de tu backend en lugar de incrustar la clave en el código del lado del cliente.
Path Parameters
El identificador de domain de tu URL domain.mintlify.site. Se puede encontrar al final de la URL de tu dashboard. Por ejemplo, en dashboard.mintlify.com/organization/domain, el identificador de domain es domain.
Body
application/json
Identificador de huella para el seguimiento de sesiones de conversación. Usa “anonymous” para usuarios anónimos o proporciona un identificador de usuario único.
Array de mensajes de la conversación. En el frontend, probablemente quieras usar la función handleSubmit del hook useChat del paquete @ai-sdk para añadir los mensajes del usuario y gestionar las respuestas en streaming, en lugar de definir manualmente los objetos de este array, ya que tienen tantos parámetros.
Show child attributes
Show child attributes
Un identificador opcional que se utiliza para mantener la continuidad de la conversación a lo largo de varios mensajes. Cuando se incluye, permite que el sistema asocie los mensajes posteriores con el mismo hilo de conversación. El threadId se devuelve en la respuesta como event.threadId cuando event.type === 'finish'.
Número de resultados de búsqueda en la documentación que se utilizarán para generar la respuesta. Valores más altos proporcionan más contexto, pero pueden aumentar el tiempo de respuesta. Recomendado: 5.
Criterios de filtrado opcionales para la búsqueda.
Show child attributes
Show child attributes
Matriz opcional de información contextual que se proporcionará al assistant.
Show child attributes
Show child attributes
La ruta de la página que el usuario está viendo actualmente. Cuando se proporciona, el assistant usa este contexto para ofrecer respuestas más relevantes. Longitud máxima: 200 caracteres.
Response
Mensaje generado correctamente.
Objeto de respuesta con segmentos de datos en flujo formateados con el estado, los encabezados y el contenido especificados. Para más información, consulta la documentación de AI SDK en ai-sdk.dev/docs/ai-sdk-ui/streaming-data. Usa el hook useChat de AI SDK para gestionar el flujo de la respuesta.
⌘I
Crear mensaje del assistant (v1)
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>"
}
'import requests
url = "https://api.mintlify.com/discovery/v1/assistant/{domain}/message"
payload = {
"fp": "<string>",
"messages": [
{
"id": "foobar",
"role": "user",
"content": "how do i get started",
"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',
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>'
})
};
fetch('https://api.mintlify.com/discovery/v1/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/v1/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',
'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>'
]),
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/v1/assistant/{domain}/message"
payload := strings.NewReader("{\n \"fp\": \"<string>\",\n \"messages\": [\n {\n \"id\": \"foobar\",\n \"role\": \"user\",\n \"content\": \"how do i get started\",\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/v1/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 \"content\": \"how do i get started\",\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/v1/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 \"content\": \"how do i get started\",\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{}