Skip to main content
POST
/
v2
/
assistant
/
{domain}
/
message
Mensaje del assistant 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>"
    }
  ]
}
'
{}
El endpoint de mensaje de assistant v2 es compatible con AI SDK v5 o superior. Si usas AI SDK v4, utiliza en su lugar el endpoint de mensaje de assistant v1.

Integración con useChat

El hook useChat del AI SDK de Vercel es la forma recomendada de integrar la assistant API en tu aplicación.
1

Instalar AI SDK

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

Usar el 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>
  );
}
Configuración obligatoria:
  • transport - Usa DefaultChatTransport para configurar la conexión con la API.
  • body.fp - Identificador de huella digital (usa 'anonymous' o un identificador único de usuario).
  • body.retrievalPageSize - Número de resultados de búsqueda que se usarán (recomendado: 5).
Configuración opcional:
  • body.context - Array de información contextual que se le proporciona al assistant. Cada objeto de contexto contiene:
    • type - Puede ser 'code' o 'textSelection'.
    • value - El fragmento de código o el contenido de texto seleccionado.
    • path (opcional) - Ruta al archivo o a la página de origen.
    • elementId (opcional) - Identificador del elemento de la interfaz de usuario que contiene el contexto.
Consulta useChat y Transport en la documentación del AI SDK para más detalles.

Límites de uso

La API del assistant tiene los siguientes límites:
  • 10.000 usos por key al mes
  • 10.000 solicitudes por organización de Mintlify por hora
  • 10.000 solicitudes por IP por día

Authorizations

Authorization
string
header
required

La cabecera Authorization espera un token de tipo Bearer. Usa una clave de API para assistant (con el prefijo mint_dsc_). Esta es una clave pública segura para utilizar en código del lado del cliente. Genérala desde la página de claves de API de tu dashboard.

Path Parameters

domain
string
required

El identificador de domain de tu URL, por ejemplo domain.mintlify.app. Puedes encontrarlo 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
fp
string
required

Identificador de huella (fingerprint) para realizar el seguimiento de las sesiones de conversación. Usa anonymous para usuarios anónimos o proporciona un identificador de usuario único.

messages
object[]
required

Array de mensajes de la conversación. Usa la función handleSubmit del hook useChat del paquete @ai-sdk/react para gestionar los mensajes y las respuestas en streaming.

threadId
string

Un identificador opcional que se utiliza para mantener la continuidad de la conversación a través 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'.

retrievalPageSize
number
default:5

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.

filter
object

Criterios de filtrado opcionales para la búsqueda.

context
object[]

Array opcional de información contextual para proporcionar al assistant.

Response

200 - application/json

Mensaje generado con éxito

Streaming de respuestas compatible con AI SDK v5. Usa el hook useChat de @ai-sdk/react para gestionar el flujo de la respuesta.