mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
0ea1a427cc
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
716 lines
23 KiB
JSON
716 lines
23 KiB
JSON
{
|
|
"openapi": "3.0.1",
|
|
"info": {
|
|
"title": "API de Mintlify Index",
|
|
"description": "Busca y recupera documentación técnica y contexto web para aplicaciones y agentes.",
|
|
"version": "1.0.0"
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://leaves.mintlify.com/api/universal-search"
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"paths": {
|
|
"/v1/context": {
|
|
"post": {
|
|
"operationId": "buildIndexContext",
|
|
"summary": "Crear contexto de implementación",
|
|
"description": "Busca en Mintlify Index y devuelve contenido con fuentes citadas reunido dentro de un presupuesto de tokens. Usa este endpoint cuando una aplicación o agente necesite contexto listo para usar en una sola solicitud.",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ContextRequest"
|
|
},
|
|
"example": {
|
|
"query": "¿Cómo debo configurar el almacenamiento en caché en Next.js 16?",
|
|
"product": "Next.js",
|
|
"format": "txt",
|
|
"tokenBudget": 3000
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "El contexto se creó correctamente.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ContextResponse"
|
|
},
|
|
"example": {
|
|
"requestId": "7f2ab8d1-3bea-4a29-bc51-c05a8d3a3e3c",
|
|
"query": "¿Cómo debo configurar el almacenamiento en caché en Next.js 16?",
|
|
"response": "### Almacenamiento en caché y revalidación\n\nFuente: https://nextjs.org/docs/app/getting-started/caching-and-revalidating\n\nUsa las API de almacenamiento en caché actuales descritas en esta guía.\n\n--------------------------------",
|
|
"resultsCount": 3,
|
|
"outputTokens": 1842
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
},
|
|
"500": {
|
|
"$ref": "#/components/responses/InternalError"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/search": {
|
|
"post": {
|
|
"operationId": "searchIndex",
|
|
"summary": "Buscar conocimientos técnicos",
|
|
"description": "Devuelve resultados clasificados de documentación mantenida por sus editores o de la web. Usa los ID de resultados de Mintlify o cualquier URL de resultado con el endpoint de contenido cuando necesites más contenido.",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SearchRequest"
|
|
},
|
|
"example": {
|
|
"query": "Almacenamiento en caché y revalidación en Next.js 16",
|
|
"numResults": 5,
|
|
"text": {
|
|
"maxCharacters": 4000
|
|
},
|
|
"includeDomains": [
|
|
"nextjs.org"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "La búsqueda se completó correctamente.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SearchResponse"
|
|
},
|
|
"example": {
|
|
"requestId": "3d8ed0aa-c21c-4a18-b995-207aa6315ea8",
|
|
"results": [
|
|
{
|
|
"id": "nextjs:/docs/app/getting-started/caching-and-revalidating",
|
|
"url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating",
|
|
"title": "Almacenamiento en caché y revalidación",
|
|
"text": "El almacenamiento en caché es una técnica para guardar el resultado de la obtención de datos y otros cálculos.",
|
|
"truncated": false,
|
|
"totalCharacters": 92,
|
|
"score": 0.91,
|
|
"source": "mintlify",
|
|
"siteName": "nextjs",
|
|
"breadcrumbs": [
|
|
"Enrutador de aplicaciones",
|
|
"Primeros pasos"
|
|
],
|
|
"publishedDate": null
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
},
|
|
"500": {
|
|
"$ref": "#/components/responses/InternalError"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/contents": {
|
|
"post": {
|
|
"operationId": "getIndexContents",
|
|
"summary": "Obtener contenido de resultados",
|
|
"description": "Recupera contenido para los ID de resultados de Mintlify o las URL de resultados devueltos por el endpoint de búsqueda. Una solicitud puede incluir hasta 20 elementos entre ambos campos.",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ContentsRequest"
|
|
},
|
|
"example": {
|
|
"ids": [
|
|
"nextjs:/docs/app/getting-started/caching-and-revalidating"
|
|
],
|
|
"query": "revalidar datos almacenados en caché",
|
|
"maxCharacters": 12000
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"400": {
|
|
"description": "El cuerpo de la solicitud no es válido.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"example": {
|
|
"error": "Una solicitud puede hacer referencia como máximo a 20 elementos entre urls e ids"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"200": {
|
|
"description": "La recuperación de contenido se completó. Comprueba cada estado para determinar si el elemento se procesó correctamente.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ContentsResponse"
|
|
},
|
|
"example": {
|
|
"requestId": "6bf694e4-76cb-4d31-a222-c94b2d9b198a",
|
|
"results": [
|
|
{
|
|
"id": "nextjs:/docs/app/getting-started/caching-and-revalidating",
|
|
"url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating",
|
|
"title": "Almacenamiento en caché y revalidación",
|
|
"text": "# Almacenamiento en caché y revalidación\n\nUsa las API de revalidación para actualizar los datos almacenados en caché.",
|
|
"truncated": false,
|
|
"totalCharacters": 78,
|
|
"score": 0,
|
|
"source": "mintlify",
|
|
"siteName": "nextjs",
|
|
"breadcrumbs": [
|
|
"Enrutador de aplicaciones",
|
|
"Primeros pasos"
|
|
],
|
|
"publishedDate": null
|
|
}
|
|
],
|
|
"statuses": [
|
|
{
|
|
"id": "nextjs:/docs/app/getting-started/caching-and-revalidating",
|
|
"status": "success"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
},
|
|
"500": {
|
|
"$ref": "#/components/responses/InternalError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"securitySchemes": {
|
|
"bearerAuth": {
|
|
"type": "http",
|
|
"scheme": "bearer",
|
|
"bearerFormat": "Clave de API de Mintlify Index",
|
|
"description": "Clave de API de Mintlify Index con el prefijo `mint_us_`."
|
|
}
|
|
},
|
|
"responses": {
|
|
"BadRequest": {
|
|
"description": "El cuerpo de la solicitud no es válido.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"example": {
|
|
"error": "Cuerpo de solicitud no válido"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Unauthorized": {
|
|
"description": "Falta la clave de API, no es válida o la organización no tiene acceso a la API REST de Index.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"example": {
|
|
"error": "No autorizado"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Forbidden": {
|
|
"description": "La IP de la solicitud no está permitida por la clave de API.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"example": {
|
|
"error": "La dirección IP no está permitida para esta clave de API"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"RateLimited": {
|
|
"description": "La organización superó un límite de uso.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"example": {
|
|
"error": "Límite de uso superado. Vuelve a intentarlo más tarde"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"InternalError": {
|
|
"description": "Index no pudo completar la solicitud.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"schemas": {
|
|
"ContextRequest": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"query",
|
|
"format"
|
|
],
|
|
"properties": {
|
|
"query": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Pregunta de implementación que se investigará."
|
|
},
|
|
"product": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Nombre del producto o empresa que se usará como indicio adicional de recuperación."
|
|
},
|
|
"format": {
|
|
"type": "string",
|
|
"enum": [
|
|
"txt",
|
|
"json"
|
|
],
|
|
"description": "Formato de la cadena `response`. `txt` devuelve secciones Markdown. `json` devuelve un objeto JSON serializado que contiene elementos de resultados."
|
|
},
|
|
"includeDomains": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"items": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"description": "Dominios que se incluirán en la recuperación."
|
|
},
|
|
"excludeDomains": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"items": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"description": "Dominios que se excluirán de la recuperación."
|
|
},
|
|
"tokenBudget": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 6000,
|
|
"default": 3000,
|
|
"description": "Número máximo de tokens de salida."
|
|
}
|
|
}
|
|
},
|
|
"ContextResponse": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"requestId",
|
|
"query",
|
|
"response",
|
|
"resultsCount",
|
|
"outputTokens"
|
|
],
|
|
"properties": {
|
|
"requestId": {
|
|
"type": "string",
|
|
"description": "Identificador único de la solicitud."
|
|
},
|
|
"query": {
|
|
"type": "string",
|
|
"description": "Consulta original de la solicitud."
|
|
},
|
|
"response": {
|
|
"type": "string",
|
|
"description": "Contenido de fuentes reunido. El valor es Markdown para solicitudes `txt` y JSON serializado para solicitudes `json`. La cadena puede estar vacía cuando ningún contenido cabe en el presupuesto de tokens."
|
|
},
|
|
"resultsCount": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Número de fragmentos de fuentes incluidos en la respuesta."
|
|
},
|
|
"outputTokens": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Número de tokens de la respuesta reunida."
|
|
}
|
|
}
|
|
},
|
|
"SearchRequest": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"query",
|
|
"numResults"
|
|
],
|
|
"properties": {
|
|
"query": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Consulta de búsqueda."
|
|
},
|
|
"numResults": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 20,
|
|
"description": "Número máximo de resultados que se devolverán."
|
|
},
|
|
"text": {
|
|
"default": false,
|
|
"description": "Controla el contenido de los resultados. Establécelo en `true` para incluir contenido coincidente, en `false` para omitirlo o proporciona `maxCharacters` para incluir contenido truncado. Si se omite, el valor predeterminado es `false`.",
|
|
"oneOf": [
|
|
{
|
|
"type": "boolean"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"maxCharacters"
|
|
],
|
|
"properties": {
|
|
"maxCharacters": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"description": "Número máximo de caracteres de contenido que se incluirán por resultado."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"includeDomains": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"items": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"description": "Dominios que se incluirán en los resultados de búsqueda."
|
|
},
|
|
"excludeDomains": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"items": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"description": "Dominios que se excluirán de los resultados de búsqueda."
|
|
}
|
|
}
|
|
},
|
|
"SearchResponse": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"requestId",
|
|
"results"
|
|
],
|
|
"properties": {
|
|
"requestId": {
|
|
"type": "string",
|
|
"description": "Identificador único de la solicitud."
|
|
},
|
|
"results": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/SearchResult"
|
|
},
|
|
"description": "Resultados de búsqueda clasificados."
|
|
}
|
|
}
|
|
},
|
|
"SearchResult": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"id",
|
|
"url",
|
|
"title",
|
|
"text",
|
|
"score",
|
|
"source",
|
|
"siteName",
|
|
"breadcrumbs",
|
|
"publishedDate"
|
|
],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Identificador del resultado. Pasa los ID de resultados de Mintlify en el campo `ids` de la solicitud de contenido. Para resultados web, pasa la URL del resultado en `urls`."
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"description": "URL canónica de la fuente."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Título de la fuente."
|
|
},
|
|
"text": {
|
|
"type": "string",
|
|
"description": "Contenido coincidente cuando se solicita. De lo contrario, una cadena vacía."
|
|
},
|
|
"truncated": {
|
|
"type": "boolean",
|
|
"description": "Indica si el contenido devuelto es más corto que el contenido disponible."
|
|
},
|
|
"totalCharacters": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Número de caracteres disponibles antes del truncamiento. Está presente cuando está disponible."
|
|
},
|
|
"score": {
|
|
"type": "number",
|
|
"description": "Puntuación de relevancia relativa. Las respuestas de contenido usan `0` porque recuperan elementos seleccionados en lugar de clasificar resultados."
|
|
},
|
|
"source": {
|
|
"type": "string",
|
|
"enum": [
|
|
"mintlify",
|
|
"web"
|
|
],
|
|
"description": "Fuente de recuperación."
|
|
},
|
|
"siteName": {
|
|
"type": "string",
|
|
"description": "Sitio de documentación o hostname web."
|
|
},
|
|
"breadcrumbs": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Jerarquía de documentación del resultado."
|
|
},
|
|
"publishedDate": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Fecha de publicación cuando la fuente proporciona una; de lo contrario, `null`. Los resultados de `search` la normalizan a una marca de tiempo ISO 8601 completa. Los resultados de `contents` recuperados mediante `urls` transmiten la cadena de fecha original de la fuente sin normalizarla, que puede ser una marca de tiempo completa o una cadena que solo contenga la fecha."
|
|
}
|
|
}
|
|
},
|
|
"ContentsRequest": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"description": "Proporciona al menos un ID de resultado de Mintlify o una URL de resultado. Puedes combinar ambos campos, con un máximo total de 20 elementos.",
|
|
"anyOf": [
|
|
{
|
|
"required": [
|
|
"urls"
|
|
]
|
|
},
|
|
{
|
|
"required": [
|
|
"ids"
|
|
]
|
|
}
|
|
],
|
|
"properties": {
|
|
"urls": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"maxItems": 20,
|
|
"items": {
|
|
"type": "string",
|
|
"format": "uri"
|
|
},
|
|
"description": "URL de resultados que se recuperarán. Usa este campo para resultados web."
|
|
},
|
|
"ids": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"maxItems": 20,
|
|
"items": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"description": "ID de resultados de Mintlify que se recuperarán."
|
|
},
|
|
"maxCharacters": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"description": "Número máximo de caracteres de contenido que se devolverán por resultado."
|
|
},
|
|
"query": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Consulta que se usará para seleccionar las secciones más relevantes cuando el contenido supere `maxCharacters`."
|
|
}
|
|
}
|
|
},
|
|
"ContentsResponse": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"requestId",
|
|
"results",
|
|
"statuses"
|
|
],
|
|
"properties": {
|
|
"requestId": {
|
|
"type": "string",
|
|
"description": "Identificador único de la solicitud."
|
|
},
|
|
"results": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/SearchResult"
|
|
},
|
|
"description": "Resultados recuperados correctamente."
|
|
},
|
|
"statuses": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ContentStatus"
|
|
},
|
|
"description": "Estado de recuperación de cada elemento solicitado."
|
|
}
|
|
}
|
|
},
|
|
"ContentStatus": {
|
|
"oneOf": [
|
|
{
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"id",
|
|
"status"
|
|
],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "ID o URL solicitados."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"success"
|
|
],
|
|
"description": "Estado de recuperación."
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"id",
|
|
"status",
|
|
"error"
|
|
],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "ID o URL solicitados."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"error"
|
|
],
|
|
"description": "Estado de recuperación."
|
|
},
|
|
"error": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"tag",
|
|
"httpStatusCode"
|
|
],
|
|
"properties": {
|
|
"tag": {
|
|
"type": "string",
|
|
"description": "Categoría de error legible por máquinas."
|
|
},
|
|
"httpStatusCode": {
|
|
"type": "integer",
|
|
"nullable": true,
|
|
"description": "Código de estado HTTP del upstream cuando está disponible."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"Error": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"error"
|
|
],
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Mensaje de error."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|