mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
19d89bf8eb
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
517 lines
22 KiB
JSON
517 lines
22 KiB
JSON
{
|
|
"openapi": "3.0.1",
|
|
"info": {
|
|
"title": "Mintlify Assistant API",
|
|
"description": "Una API para integrar las funciones de descubrimiento de Mintlify en tu producto.",
|
|
"version": "1.0.0"
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://api.mintlify.com/discovery/v1"
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"paths": {
|
|
"/assistant/{domain}/message": {
|
|
"post": {
|
|
"summary": "Mensaje del assistant",
|
|
"description": "Genera un mensaje de respuesta del assistant para el dominio especificado.",
|
|
"parameters": [
|
|
{
|
|
"name": "domain",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "El identificador de dominio de tu URL `domain.mintlify.app`. Puedes encontrarlo al final de la URL de tu dashboard. Por ejemplo, `dashboard.mintlify.com/organization/domain` tiene como identificador de dominio `domain`."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"fp",
|
|
"messages"
|
|
],
|
|
"properties": {
|
|
"fp": {
|
|
"type": "string",
|
|
"description": "Identificador de huella digital para rastrear sesiones de conversación. Usa 'anonymous' para usuarios anónimos o proporciona un identificador de usuario único."
|
|
},
|
|
"threadId": {
|
|
"default": null,
|
|
"type": "string",
|
|
"description": "Un identificador opcional que se utiliza para mantener la continuidad de la conversación a lo largo de varios mensajes. Cuando se proporciona, 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'."
|
|
},
|
|
"messages": {
|
|
"type": "array",
|
|
"default": [
|
|
{
|
|
"id": "foobar",
|
|
"role": "user",
|
|
"content": "how do i get started",
|
|
"parts": [
|
|
{
|
|
"type": "text",
|
|
"text": "How do I get started"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Identificador único del mensaje"
|
|
},
|
|
"role": {
|
|
"type": "string",
|
|
"enum": [
|
|
"system",
|
|
"assistant",
|
|
"data",
|
|
"user"
|
|
],
|
|
"description": "El rol del remitente del mensaje"
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Marca de tiempo de creación del mensaje"
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "El contenido del mensaje"
|
|
},
|
|
"annotations": {
|
|
"type": "array",
|
|
"items": {},
|
|
"description": "Arreglo opcional de anotaciones para el mensaje"
|
|
},
|
|
"parts": {
|
|
"type": "array",
|
|
"items": {
|
|
"oneOf": [
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"text"
|
|
]
|
|
},
|
|
"text": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"text"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"reasoning"
|
|
]
|
|
},
|
|
"reasoning": {
|
|
"type": "string"
|
|
},
|
|
"details": {
|
|
"type": "array",
|
|
"items": {
|
|
"oneOf": [
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"text"
|
|
]
|
|
},
|
|
"text": {
|
|
"type": "string"
|
|
},
|
|
"signature": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"text"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"redacted"
|
|
]
|
|
},
|
|
"data": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"data"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"reasoning",
|
|
"details"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"step-start"
|
|
]
|
|
}
|
|
},
|
|
"required": [
|
|
"type"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"source"
|
|
]
|
|
},
|
|
"source": {
|
|
"type": "object",
|
|
"properties": {
|
|
"sourceType": {
|
|
"type": "string",
|
|
"enum": [
|
|
"url"
|
|
]
|
|
},
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"url": {
|
|
"type": "string"
|
|
},
|
|
"title": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"sourceType",
|
|
"id",
|
|
"url"
|
|
]
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"source"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"tool-invocation"
|
|
]
|
|
},
|
|
"toolInvocation": {
|
|
"oneOf": [
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"state": {
|
|
"type": "string",
|
|
"enum": [
|
|
"partial-call"
|
|
]
|
|
},
|
|
"step": {
|
|
"type": "number"
|
|
},
|
|
"toolCallId": {
|
|
"type": "string"
|
|
},
|
|
"toolName": {
|
|
"type": "string"
|
|
},
|
|
"args": {}
|
|
},
|
|
"required": [
|
|
"state",
|
|
"toolCallId",
|
|
"toolName",
|
|
"args"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"state": {
|
|
"type": "string",
|
|
"enum": [
|
|
"call"
|
|
]
|
|
},
|
|
"step": {
|
|
"type": "number"
|
|
},
|
|
"toolCallId": {
|
|
"type": "string"
|
|
},
|
|
"toolName": {
|
|
"type": "string"
|
|
},
|
|
"args": {}
|
|
},
|
|
"required": [
|
|
"state",
|
|
"toolCallId",
|
|
"toolName",
|
|
"args"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"state": {
|
|
"type": "string",
|
|
"enum": [
|
|
"result"
|
|
]
|
|
},
|
|
"step": {
|
|
"type": "number"
|
|
},
|
|
"toolCallId": {
|
|
"type": "string"
|
|
},
|
|
"toolName": {
|
|
"type": "string"
|
|
},
|
|
"args": {},
|
|
"result": {}
|
|
},
|
|
"required": [
|
|
"state",
|
|
"toolCallId",
|
|
"toolName",
|
|
"args",
|
|
"result"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"toolInvocation"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
"description": "Array de partes de mensaje con distintos tipos, incluidos texto, razonamiento, fuentes e invocaciones de herramientas"
|
|
},
|
|
"experimental_attachments": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"contentType": {
|
|
"type": "string"
|
|
},
|
|
"url": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"url"
|
|
]
|
|
},
|
|
"description": "Array opcional de archivos adjuntos experimentales para el mensaje"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"role",
|
|
"content",
|
|
"parts"
|
|
]
|
|
},
|
|
"description": "Array de mensajes de la conversación. En el frontend, probablemente querrás usar la función handleSubmit del hook useChat del paquete @ai-sdk para agregar los mensajes del usuario y manejar las respuestas en streaming, en lugar de definir manualmente los objetos de este array, ya que tienen tantos parámetros."
|
|
},
|
|
"retrievalPageSize": {
|
|
"type": "number",
|
|
"default": 5,
|
|
"description": "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": {
|
|
"type": "object",
|
|
"default": null,
|
|
"properties": {
|
|
"version": {
|
|
"type": "string",
|
|
"description": "Filtro opcional de versión"
|
|
},
|
|
"language": {
|
|
"type": "string",
|
|
"description": "Filtro de idioma opcional"
|
|
}
|
|
},
|
|
"description": "Criterios de filtrado opcionales para la búsqueda"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Mensaje generado con éxito",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"description": "Objeto de respuesta que transmite partes de un flujo de datos con formato con el estado, los encabezados y el contenido especificados. Esto coincide con lo que se espera del SDK de IA, tal como se documenta en [ai-sdk.dev/docs/ai-sdk-ui/streaming-data](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data). En lugar de escribir tu propio parser, se recomienda usar el [hook useChat de ai-sdk, tal como se documenta aquí](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/search/{domain}": {
|
|
"post": {
|
|
"x-mint": {
|
|
"mcp": {
|
|
"enabled": true
|
|
}
|
|
},
|
|
"summary": "Buscar en la documentación",
|
|
"description": "Realiza búsquedas semánticas y por palabras clave en tu documentación, con filtros y paginación configurables.",
|
|
"parameters": [
|
|
{
|
|
"name": "domain",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "El identificador de dominio de tu URL `domain.mintlify.app`. Puedes encontrarlo al final de la URL de tu dashboard. Por ejemplo, `dashboard.mintlify.com/organization/domain` tiene un identificador de dominio de `domain`."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"query"
|
|
],
|
|
"properties": {
|
|
"query": {
|
|
"type": "string",
|
|
"description": "La búsqueda que se ejecutará en el contenido de tu documentación."
|
|
},
|
|
"pageSize": {
|
|
"type": "number",
|
|
"default": 10,
|
|
"description": "Número de resultados de búsqueda que se devolverán. Si no se especifica, el valor predeterminado es 10."
|
|
},
|
|
"filter": {
|
|
"type": "object",
|
|
"description": "Parámetros de filtrado opcionales para refinar los resultados de búsqueda.",
|
|
"properties": {
|
|
"version": {
|
|
"type": "string",
|
|
"description": "Filtrar resultados por versión de la documentación."
|
|
},
|
|
"language": {
|
|
"type": "string",
|
|
"description": "Filtrar los resultados por idioma del contenido."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Resultados de búsqueda",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"description": "El contenido correspondiente de tu documentación."
|
|
},
|
|
"path": {
|
|
"type": "string",
|
|
"description": "Ruta o URL al documento de origen."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"description": "Metadatos adicionales sobre el resultado de la búsqueda."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"securitySchemes": {
|
|
"bearerAuth": {
|
|
"type": "http",
|
|
"scheme": "bearer",
|
|
"description": "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](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard."
|
|
}
|
|
}
|
|
}
|
|
} |