diff --git a/api/introduction.mdx b/api/introduction.mdx index e27b578335..7e2e3d145d 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -23,6 +23,9 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - [Create assistant message](/api/assistant/create-assistant-message-v2): Embed the assistant, trained on your docs, into any application of your choosing. - [Search documentation](/api/assistant/search): Search through your documentation. - [Get page content](/api/assistant/get-page-content): Retrieve the full text content of a documentation page. +- [Universal search](/api/universal-search/search): Search across Mintlify-hosted documentation and the wider web with a single query. +- [Assemble a context payload for RAG](/api/universal-search/context): Assemble a token-budgeted retrieval-augmented generation context payload. +- [Fetch page content for search results](/api/universal-search/contents): Retrieve the stitched Markdown for pages returned by universal search. - [Get user feedback](/api/analytics/feedback): Export user feedback from your documentation. - [Get feedback by page](/api/analytics/feedback-by-page): Export feedback counts aggregated by page. - [Get assistant conversations](/api/analytics/assistant-conversations): Export AI assistant conversation history. @@ -47,12 +50,13 @@ Generate API keys on the [API keys page](https://app.mintlify.com/settings/organ You can create up to 10 API keys per hour per organization. -Mintlify uses two types of API keys, each scoped to a different set of endpoints: +Mintlify uses three types of API keys, each scoped to a different set of endpoints: -| Key type | Prefix | Use for | -| --------------- | ----------- | ------------------------------------------------------------------------------------ | -| Admin API key | `mint_` | Updates, agent jobs, and analytics exports. Server-side only. | -| Assistant API key | `mint_dsc_` | Assistant endpoints (create message, search, get page content). Proxy in production. | +| Key type | Prefix | Use for | +| ------------------------ | ----------- | ------------------------------------------------------------------------------------ | +| Admin API key | `mint_` | Updates, agent jobs, and analytics exports. Server-side only. | +| Assistant API key | `mint_dsc_` | Assistant endpoints (create message, search, get page content). Proxy in production. | +| Universal search API key | — | Universal search endpoint. Available with the Universal Search entitlement. | ### Admin API key @@ -96,3 +100,9 @@ Assistant API keys begin with the `mint_dsc_` prefix. Calls using the assistant API token can incur costs: either using your assistant credits or incurring overages. + +### Universal search API key + +Use the universal search API key for the [Universal search](/api/universal-search/search) endpoint. + +Universal search is a paid add-on. [Contact sales](https://mintlify.com/enterprise) to enable the Universal Search entitlement for your organization before generating a key. diff --git a/api/universal-search/contents.mdx b/api/universal-search/contents.mdx new file mode 100644 index 0000000000..aeb977c93d --- /dev/null +++ b/api/universal-search/contents.mdx @@ -0,0 +1,20 @@ +--- +title: "Fetch page content for search results" +openapi: "/universal-search-openapi.json POST /contents" +keywords: ["contents", "page content", "universal search"] +--- + +Use this endpoint after [Search across documentation and the web](/api/universal-search/search) when you want the full stitched Markdown for specific pages without repeating the query. Pass the `id` returned from a previous search, the canonical URL of a Mintlify-hosted page, or a mix of both. + +A single request can reference at most 20 items across `urls` and `ids` combined. When you provide `maxCharacters`, each page is truncated to that length while keeping the Markdown valid (open code fences are closed). + +## Partial success + +The response always returns `200` when the request body is well-formed. Inspect the `statuses` array to see which inputs resolved successfully and which failed. `results` only contains the pages whose status is `success`. + +Error `tag` values: + +- `not_found`: The URL or ID did not match any indexed page. +- `not_synced`: The source deployment has not been indexed for universal search. +- `invalid_id`: The ID was malformed. +- `fetch_error`: The lookup failed unexpectedly. Retry the request or contact support with the `requestId`. diff --git a/api/universal-search/context.mdx b/api/universal-search/context.mdx new file mode 100644 index 0000000000..4ebe1fca84 --- /dev/null +++ b/api/universal-search/context.mdx @@ -0,0 +1,16 @@ +--- +title: "Assemble a context payload for RAG" +openapi: "/universal-search-openapi.json POST /context" +keywords: ["context", "RAG", "retrieval", "universal search"] +--- + +Use this endpoint to build a ready-to-use context payload for a retrieval-augmented generation (RAG) pipeline. It runs a ranked universal search behind the scenes, deduplicates and truncates snippets so each page contributes a fair share, and returns a token-budgeted result you can hand directly to an LLM. + +Choose the shape of the payload with `format`: + +- `txt`: A single plain-text string with source URLs interleaved. Best for passing straight into a prompt. +- `json`: A JSON-encoded string of the form `{"results":[...]}` with one entry per snippet. Best when your application needs to render or attribute individual sources. + +Set `product` to bias retrieval toward a specific product or subject when the same query could match multiple domains. + +The response caps `outputTokens` at 10,000 and reports `resultsCount` so you can see how many snippets were included after the budget was applied. diff --git a/api/universal-search/search.mdx b/api/universal-search/search.mdx new file mode 100644 index 0000000000..01cf2a73b5 --- /dev/null +++ b/api/universal-search/search.mdx @@ -0,0 +1,15 @@ +--- +title: "Search across documentation and the web" +openapi: "/universal-search-openapi.json POST /search" +keywords: ["search", "universal search", "web search"] +--- + +Universal search runs a single query against Mintlify-hosted documentation and the wider web, then returns a merged, ranked list of results. Use it to power in-product search experiences, agent tools, or retrieval pipelines that need to reach beyond a single deployment. + +Universal search requires the Universal Search entitlement. [Contact sales](https://mintlify.com/enterprise) to enable it for your organization. + +## Authentication + +Authenticate with a universal search API key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. + +Universal search API keys are separate from admin and assistant API keys and are only accepted at `/universal-search/v1` endpoints. diff --git a/docs.json b/docs.json index 82433ab6c5..5a30d08d6b 100644 --- a/docs.json +++ b/docs.json @@ -407,6 +407,15 @@ "api/assistant/get-page-content" ] }, + { + "group": "Universal search", + "icon": "globe", + "pages": [ + "api/universal-search/search", + "api/universal-search/context", + "api/universal-search/contents" + ] + }, { "group": "Analytics", "icon": "chart-line", diff --git a/es.json b/es.json index 8641f475d3..e3f02bb9d5 100644 --- a/es.json +++ b/es.json @@ -386,6 +386,15 @@ "es/api/assistant/get-page-content" ] }, + { + "group": "Búsqueda universal", + "icon": "globe", + "pages": [ + "es/api/universal-search/search", + "es/api/universal-search/context", + "es/api/universal-search/contents" + ] + }, { "group": "Analytics", "icon": "chart-line", diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index 8b0bbeeff7..ceb06e25d3 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -25,6 +25,9 @@ La REST (Representational State Transfer) API de Mintlify te permite interactuar * [Create assistant message](/es/api/assistant/create-assistant-message-v2): Integra el assistant, entrenado con tu documentación, en cualquier aplicación que elijas. * [Search documentation](/es/api/assistant/search): Busca en tu documentación. * [Get page content](/es/api/assistant/get-page-content): Recupera el contenido de texto completo de una página de documentación. +* [Universal search](/es/api/universal-search/search): Busca en la documentación alojada en Mintlify y en la web con una única consulta. +* [Assemble a context payload for RAG](/es/api/universal-search/context): Crea un payload de contexto ajustado a un presupuesto de tokens y listo para usar en un pipeline de generación aumentada por recuperación (RAG). +* [Fetch page content for search results](/es/api/universal-search/contents): Recupera el Markdown completo de las páginas devueltas por la búsqueda universal. * [Get user feedback](/es/api/analytics/feedback): Exporta los comentarios de los usuarios de tu documentación. * [Get assistant conversations](/es/api/analytics/assistant-conversations): Exporta el historial de conversaciones del Asistente de IA. * [Get assistant caller stats](/es/api/analytics/assistant-caller-stats): Obtén un desglose de los recuentos de consultas del assistant por tipo de origen. @@ -81,3 +84,11 @@ Las keys del Assistant API comienzan con el prefijo `mint_dsc_`. Las llamadas que usan el token del Assistant API pueden generar costos: ya sea usando tus créditos del assistant o incurriendo en excedentes. + +
+ ### Clave de la API de búsqueda universal +
+ +Usa la clave de la API de búsqueda universal para el endpoint [Universal search](/es/api/universal-search/search). + +La búsqueda universal es un complemento de pago. [Contacta con ventas](https://mintlify.com/enterprise) para habilitar el permiso Universal Search en tu organización antes de generar una clave. diff --git a/es/api/universal-search/contents.mdx b/es/api/universal-search/contents.mdx new file mode 100644 index 0000000000..2698942d15 --- /dev/null +++ b/es/api/universal-search/contents.mdx @@ -0,0 +1,22 @@ +--- +title: "Obtener el contenido de páginas para resultados de búsqueda" +openapi: "/es/universal-search-openapi.json POST /contents" +keywords: ["contents", "contenido de página", "búsqueda universal"] +--- + +Usa este endpoint después de [Buscar en la documentación y en la web](/es/api/universal-search/search) cuando quieras obtener el Markdown completo y unificado de páginas específicas sin repetir la consulta. Pasa el `id` devuelto por una búsqueda previa, la URL canónica de una página alojada en Mintlify, o una combinación de ambos. + +Una única solicitud puede referenciar como máximo 20 elementos en total entre `urls` e `ids` combinados. Cuando proporcionas `maxCharacters`, cada página se trunca a esa longitud manteniendo el Markdown válido (se cierran los bloques de código abiertos). + +
+## Éxito parcial +
+ +La respuesta siempre devuelve `200` cuando el cuerpo de la solicitud está bien formado. Inspecciona el array `statuses` para ver qué entradas se resolvieron correctamente y cuáles fallaron. `results` solo contiene las páginas cuyo estado es `success`. + +Valores de `tag` de error: + +- `not_found`: La URL o el ID no coincide con ninguna página indexada. +- `not_synced`: La implementación de origen no ha sido indexada para la búsqueda universal. +- `invalid_id`: El ID tenía un formato incorrecto. +- `fetch_error`: La consulta falló inesperadamente. Reintenta la solicitud o contacta con soporte con el `requestId`. diff --git a/es/api/universal-search/context.mdx b/es/api/universal-search/context.mdx new file mode 100644 index 0000000000..0531472536 --- /dev/null +++ b/es/api/universal-search/context.mdx @@ -0,0 +1,16 @@ +--- +title: "Ensamblar un payload de contexto para RAG" +openapi: "/es/universal-search-openapi.json POST /context" +keywords: ["context", "RAG", "recuperación", "búsqueda universal"] +--- + +Usa este endpoint para construir un payload de contexto listo para usar en un pipeline de generación aumentada por recuperación (RAG). Ejecuta por detrás una búsqueda universal ordenada, deduplica y trunca los fragmentos para que cada página aporte una parte equitativa, y devuelve un resultado ajustado a un presupuesto de tokens que puedes pasar directamente a un LLM. + +Elige la forma del payload con `format`: + +- `txt`: Una única cadena de texto plano con las URLs de origen intercaladas. Ideal para pasarla directamente a un prompt. +- `json`: Una cadena codificada en JSON con la forma `{"results":[...]}`, con una entrada por fragmento. Ideal cuando tu aplicación necesita mostrar o atribuir fuentes individuales. + +Establece `product` para inclinar la recuperación hacia un producto o tema específico cuando la misma consulta pueda coincidir con varios dominios. + +La respuesta limita `outputTokens` a 10.000 e informa de `resultsCount` para que veas cuántos fragmentos se incluyeron después de aplicar el presupuesto. diff --git a/es/api/universal-search/search.mdx b/es/api/universal-search/search.mdx new file mode 100644 index 0000000000..4a7af1a059 --- /dev/null +++ b/es/api/universal-search/search.mdx @@ -0,0 +1,17 @@ +--- +title: "Buscar en la documentación y en la web" +openapi: "/es/universal-search-openapi.json POST /search" +keywords: ["búsqueda", "búsqueda universal", "búsqueda web"] +--- + +La búsqueda universal ejecuta una única consulta contra la documentación alojada en Mintlify y la web abierta, y devuelve una lista combinada de resultados ordenados por relevancia. Úsala para impulsar experiencias de búsqueda dentro de tu producto, herramientas de agentes o flujos de recuperación que necesiten ir más allá de una única implementación. + +La búsqueda universal requiere el permiso Universal Search. [Contacta con ventas](https://mintlify.com/enterprise) para habilitarlo para tu organización. + +
+## Autenticación +
+ +Autentícate con una clave API de búsqueda universal. Genera una en la [página de claves API](https://app.mintlify.com/settings/organization/api-keys) de tu panel. + +Las claves API de búsqueda universal son distintas de las claves de administrador y del asistente, y solo se aceptan en los endpoints de `/universal-search/v1`. diff --git a/es/universal-search-openapi.json b/es/universal-search-openapi.json new file mode 100644 index 0000000000..33ee7189c2 --- /dev/null +++ b/es/universal-search-openapi.json @@ -0,0 +1,612 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "API de búsqueda universal de Mintlify", + "description": "Busca en la documentación alojada en Mintlify y en la web abierta con una única consulta.", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://api.mintlify.com/universal-search/v1" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/search": { + "post": { + "summary": "Buscar en la documentación y en la web", + "description": "Ejecuta una única consulta contra la documentación alojada en Mintlify y proveedores de búsqueda web, combina los resultados y los devuelve ordenados por relevancia. Opcionalmente devuelve el contenido completo de la página para cada resultado.\n\nAutentícate con una clave API de búsqueda universal.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query", + "numResults" + ], + "properties": { + "query": { + "type": "string", + "description": "La consulta de búsqueda que se va a ejecutar. Debe ser una cadena no vacía." + }, + "numResults": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "description": "Número máximo de resultados que se van a devolver. Debe estar entre 1 y 20." + }, + "text": { + "description": "Controla si se devuelve el contenido de la página con cada resultado. Omítelo o establécelo en `false` para devolver solo metadatos. Establécelo en `true` para devolver el contenido completo de la página. Pasa un objeto con `maxCharacters` para devolver el contenido truncado a un límite de caracteres. El truncado preserva Markdown válido cerrando los bloques de código abiertos.", + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "object", + "required": [ + "maxCharacters" + ], + "properties": { + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "Número máximo de caracteres del contenido de la página que se devuelve por resultado." + } + } + } + ] + }, + "includeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "description": "Restringe los resultados web a estos dominios. Los resultados alojados en Mintlify no se ven afectados." + }, + "excludeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "description": "Excluye los resultados web de estos dominios. Los resultados alojados en Mintlify no se ven afectados." + } + } + }, + "examples": { + "basic": { + "summary": "Búsqueda básica con contenido de página truncado", + "value": { + "query": "How do I create a Stripe charge?", + "numResults": 10, + "text": { + "maxCharacters": 4000 + } + } + }, + "filtered": { + "summary": "Filtrar resultados web por dominio", + "value": { + "query": "authentication setup", + "numResults": 10, + "text": { + "maxCharacters": 4000 + }, + "includeDomains": [ + "docs.stripe.com" + ], + "excludeDomains": [ + "example.com" + ] + } + }, + "fullText": { + "summary": "Devolver el contenido completo de la página", + "value": { + "query": "How do I create a Stripe charge?", + "numResults": 10, + "text": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Resultados de la búsqueda.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "results" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Un identificador único para esta solicitud. Inclúyelo cuando contactes con soporte." + }, + "results": { + "type": "array", + "description": "La lista combinada de resultados, ordenada por relevancia. Los resultados con `source: \"mintlify\"` provienen de documentación alojada en Mintlify; los resultados con `source: \"web\"` provienen de la web abierta.", + "items": { + "$ref": "#/components/schemas/Result" + } + } + } + } + } + } + }, + "400": { + "description": "Cuerpo de la solicitud no válido.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Clave API ausente o no válida.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "Se superó el límite de tasa.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "La búsqueda falló.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/context": { + "post": { + "summary": "Ensamblar un payload de contexto para generación aumentada por recuperación", + "description": "Ejecuta una búsqueda universal ordenada y devuelve un payload de contexto ajustado a un presupuesto de tokens, ensamblado a partir de los mejores resultados de Mintlify y de la web. Usa este endpoint para alimentar un pipeline de generación aumentada por recuperación (RAG) sin tener que unir los resultados por tu cuenta. Elige `txt` para obtener un contexto en texto plano listo para pasar a un LLM, o `json` para una lista estructurada que tu aplicación pueda mostrar.\n\nAutentícate con una clave API de búsqueda universal.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query", + "format" + ], + "properties": { + "query": { + "type": "string", + "description": "La pregunta o intención del usuario para la que se va a construir el contexto." + }, + "product": { + "type": "string", + "description": "Producto o tema opcional para inclinar la recuperación. Cuando se establece, se antepone a la consulta de recuperación." + }, + "format": { + "type": "string", + "enum": [ + "txt", + "json" + ], + "description": "Forma del campo `response`. `txt` devuelve un único payload de texto plano con las URLs de origen; `json` devuelve una cadena codificada en JSON con la forma `{\"results\":[...]}`, con una entrada por fragmento." + } + } + }, + "examples": { + "text": { + "summary": "Ensamblar un contexto en texto plano", + "value": { + "query": "How do I create a Stripe charge?", + "format": "txt" + } + }, + "json": { + "summary": "Ensamblar un contexto JSON estructurado inclinado hacia un producto", + "value": { + "query": "authentication setup", + "product": "Stripe", + "format": "json" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "El contexto ensamblado.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "query", + "response", + "resultsCount", + "outputTokens" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Un identificador único para esta solicitud. Inclúyelo cuando contactes con soporte." + }, + "query": { + "type": "string", + "description": "Eco de la `query` original (sin ningún prefijo `product` que se haya aplicado durante la recuperación)." + }, + "response": { + "type": "string", + "description": "El contexto ensamblado. Cuando `format` es `txt`, es un payload de texto plano con las URLs de origen. Cuando `format` es `json`, es una cadena codificada en JSON con la forma `{\"results\":[...]}` en la que cada resultado contiene la URL, el título y el Markdown del fragmento." + }, + "resultsCount": { + "type": "integer", + "minimum": 0, + "description": "El número de fragmentos incluidos en `response` después de aplicar el presupuesto de tokens." + }, + "outputTokens": { + "type": "integer", + "minimum": 0, + "description": "El recuento aproximado de tokens de `response`. El endpoint lo limita a 10.000 tokens." + } + } + } + } + } + }, + "400": { + "description": "Cuerpo de la solicitud no válido.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Clave API ausente o no válida.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "Se superó el límite de tasa.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Falló el ensamblado del contexto.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/contents": { + "post": { + "summary": "Obtener el contenido de una página por URL o ID", + "description": "Resuelve URLs o IDs a páginas de documentación alojadas en Mintlify y devuelve el contenido unificado de la página para cada una. Cada entrada recibe un estado por elemento, de modo que la respuesta puede informar de un éxito parcial sin fallar toda la solicitud.\n\nAutentícate con una clave API de búsqueda universal.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Se requiere al menos uno de `urls` o `ids`. Una única solicitud puede referenciar como máximo 20 elementos en total entre ambos campos combinados.", + "properties": { + "urls": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string", + "format": "uri" + }, + "description": "URLs canónicas de páginas alojadas en Mintlify que se van a obtener. Se emparejan tanto las variantes con `www` como sin `www`." + }, + "ids": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string" + }, + "description": "IDs de páginas que se van a obtener. Usa el `id` devuelto por [Buscar en la documentación y en la web](/es/api/universal-search/search)." + }, + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "Número máximo de caracteres del contenido de la página que se devuelve por resultado. El truncado preserva Markdown válido cerrando los bloques de código abiertos." + } + } + }, + "examples": { + "byIds": { + "summary": "Obtener páginas por ID", + "value": { + "ids": [ + "stripe-charges-guide", + "stripe-webhooks-guide" + ], + "maxCharacters": 4000 + } + }, + "byUrls": { + "summary": "Obtener páginas por URL canónica", + "value": { + "urls": [ + "https://docs.stripe.com/charges", + "https://docs.stripe.com/webhooks" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Se completó la consulta de contenido. Revisa `statuses` para ver el resultado por entrada; la respuesta puede incluir resultados parciales.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "results", + "statuses" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Un identificador único para esta solicitud. Inclúyelo cuando contactes con soporte." + }, + "results": { + "type": "array", + "description": "Páginas resueltas con éxito, con la misma forma que los resultados de búsqueda. Solo aparecen aquí las entradas cuya entrada correspondiente en `statuses` informa `success`.", + "items": { + "$ref": "#/components/schemas/Result" + } + }, + "statuses": { + "type": "array", + "description": "Una entrada por cada entrada de la solicitud, en el orden en que se proporcionaron las entradas. Cada entrada informa si la entrada se resolvió con éxito o, en caso contrario, un `tag` de error.", + "items": { + "oneOf": [ + { + "type": "object", + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "La URL o el ID de entrada al que corresponde este estado." + }, + "status": { + "type": "string", + "enum": [ + "success" + ] + } + } + }, + { + "type": "object", + "required": [ + "id", + "status", + "error" + ], + "properties": { + "id": { + "type": "string", + "description": "La URL o el ID de entrada al que corresponde este estado." + }, + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "object", + "required": [ + "tag", + "httpStatusCode" + ], + "properties": { + "tag": { + "type": "string", + "enum": [ + "not_found", + "not_synced", + "invalid_id", + "fetch_error" + ], + "description": "Etiqueta de error legible por máquina. `not_found` significa que la URL o el ID no coincidió con ninguna página. `not_synced` significa que la implementación de origen no ha sido indexada para la búsqueda universal. `invalid_id` significa que el ID tenía un formato incorrecto. `fetch_error` significa que la consulta falló inesperadamente." + }, + "httpStatusCode": { + "type": "integer", + "nullable": true, + "description": "Un código de estado HTTP que describe mejor el error, o `null` cuando no se aplica un único código." + } + } + } + } + } + ] + } + } + } + } + } + } + }, + "400": { + "description": "Cuerpo de la solicitud no válido.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Clave API ausente o no válida.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "Se superó el límite de tasa.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "description": "El encabezado Authorization espera un token Bearer. Usa una clave API de búsqueda universal. Genera una en la [página de claves API](https://app.mintlify.com/settings/organization/api-keys) de tu panel." + } + }, + "schemas": { + "ErrorResponse": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string", + "description": "Descripción legible por humanos del error." + } + } + }, + "Result": { + "type": "object", + "required": [ + "id", + "url", + "title", + "text", + "score", + "source", + "siteName", + "breadcrumbs", + "publishedDate" + ], + "properties": { + "id": { + "type": "string", + "description": "Un identificador estable para el resultado. Para los resultados de Mintlify, es el ID del grupo de páginas; para los resultados web, es la URL." + }, + "url": { + "type": "string", + "format": "uri", + "description": "La URL canónica del resultado." + }, + "title": { + "type": "string", + "description": "El título de la página." + }, + "text": { + "type": "string", + "description": "El contenido de la página. Vacío cuando `text` se omite o se establece en `false`. Truncado cuando se proporciona `text.maxCharacters`." + }, + "score": { + "type": "number", + "description": "La puntuación de relevancia de este resultado." + }, + "source": { + "type": "string", + "enum": [ + "mintlify", + "web" + ], + "description": "De dónde proviene el resultado." + }, + "siteName": { + "type": "string", + "description": "El nombre del sitio del que proviene el resultado. Para los resultados de Mintlify, es el subdominio de la implementación; para los resultados web, es el nombre de host." + }, + "breadcrumbs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Las migas de pan de navegación de la página. Solo se rellenan para los resultados de Mintlify." + }, + "publishedDate": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "La fecha de publicación informada por la fuente, cuando esté disponible." + } + } + } + } + } +} diff --git a/fr.json b/fr.json index 723b354ec6..0cac26bd38 100644 --- a/fr.json +++ b/fr.json @@ -386,6 +386,15 @@ "fr/api/assistant/get-page-content" ] }, + { + "group": "Recherche universelle", + "icon": "globe", + "pages": [ + "fr/api/universal-search/search", + "fr/api/universal-search/context", + "fr/api/universal-search/contents" + ] + }, { "group": "Analytics", "icon": "chart-line", diff --git a/fr/api/introduction.mdx b/fr/api/introduction.mdx index c2070222b4..d762522538 100644 --- a/fr/api/introduction.mdx +++ b/fr/api/introduction.mdx @@ -25,6 +25,9 @@ L'API REST (Representational State Transfer) de Mintlify vous permet d'interagir * [Create assistant message](/fr/api/assistant/create-assistant-message-v2): Intégrez l'Assistant, entraîné sur votre documentation, dans n'importe quelle application de votre choix. * [Search documentation](/fr/api/assistant/search): Effectuez une recherche dans votre documentation. * [Get page content](/fr/api/assistant/get-page-content): Récupérez le contenu textuel complet d'une page de documentation. +* [Universal search](/fr/api/universal-search/search): Recherchez dans la documentation hébergée par Mintlify et sur le web avec une seule requête. +* [Assemble a context payload for RAG](/fr/api/universal-search/context): Assemblez un contexte prêt à l'emploi pour un pipeline de génération augmentée par récupération (RAG). +* [Fetch page content for search results](/fr/api/universal-search/contents): Récupérez le Markdown complet des pages renvoyées par la recherche universelle. * [Get user feedback](/fr/api/analytics/feedback): Exportez les retours utilisateurs issus de votre documentation. * [Get assistant conversations](/fr/api/analytics/assistant-conversations): Exportez l'historique des conversations de l'Assistant IA. * [Get assistant caller stats](/fr/api/analytics/assistant-caller-stats): Récupérez une ventilation du nombre de requêtes de l'assistant par type d'appelant. @@ -81,3 +84,11 @@ Les clés d'API de l'Assistant commencent par le préfixe `mint_dsc_`. Les appels utilisant le token de l'API de l'Assistant peuvent entraîner des coûts : soit en utilisant vos crédits d'Assistant, soit en engendrant des dépassements. + +
+ ### Clé d'API de recherche universelle +
+ +Utilisez la clé d'API de recherche universelle pour le point de terminaison [Universal search](/fr/api/universal-search/search). + +La recherche universelle est un module complémentaire payant. [Contactez le service commercial](https://mintlify.com/enterprise) pour activer l'entitlement Universal Search dans votre organisation avant de générer une clé. diff --git a/fr/api/universal-search/contents.mdx b/fr/api/universal-search/contents.mdx new file mode 100644 index 0000000000..4867a3d665 --- /dev/null +++ b/fr/api/universal-search/contents.mdx @@ -0,0 +1,22 @@ +--- +title: "Récupérer le contenu des pages pour les résultats de recherche" +openapi: "/fr/universal-search-openapi.json POST /contents" +keywords: ["contents", "contenu de page", "recherche universelle"] +--- + +Utilisez cet endpoint après [Rechercher dans la documentation et sur le web](/fr/api/universal-search/search) lorsque vous souhaitez obtenir le Markdown complet et assemblé pour des pages spécifiques sans répéter la requête. Fournissez l'`id` renvoyé par une recherche précédente, l'URL canonique d'une page hébergée par Mintlify, ou un mélange des deux. + +Une seule requête peut référencer au maximum 20 éléments au total entre `urls` et `ids`. Lorsque vous fournissez `maxCharacters`, chaque page est tronquée à cette longueur tout en conservant un Markdown valide (les blocs de code ouverts sont fermés). + +
+## Succès partiel +
+ +La réponse renvoie toujours `200` lorsque le corps de la requête est bien formé. Inspectez le tableau `statuses` pour voir quelles entrées ont été résolues avec succès et lesquelles ont échoué. `results` ne contient que les pages dont le statut est `success`. + +Valeurs de `tag` d'erreur : + +- `not_found` : l'URL ou l'ID ne correspond à aucune page indexée. +- `not_synced` : le déploiement source n'a pas été indexé pour la recherche universelle. +- `invalid_id` : l'ID était mal formé. +- `fetch_error` : la recherche a échoué de manière inattendue. Réessayez la requête ou contactez le support en fournissant le `requestId`. diff --git a/fr/api/universal-search/context.mdx b/fr/api/universal-search/context.mdx new file mode 100644 index 0000000000..2d27d5f285 --- /dev/null +++ b/fr/api/universal-search/context.mdx @@ -0,0 +1,16 @@ +--- +title: "Assembler un contexte pour le RAG" +openapi: "/fr/universal-search-openapi.json POST /context" +keywords: ["contexte", "RAG", "récupération", "recherche universelle"] +--- + +Utilisez cet endpoint pour construire un contexte prêt à l'emploi pour un pipeline de génération augmentée par récupération (RAG). Il exécute en arrière-plan une recherche universelle classée par pertinence, déduplique et tronque les extraits pour que chaque page contribue de manière équilibrée, et renvoie un résultat calibré en jetons que vous pouvez transmettre directement à un LLM. + +Choisissez la forme du contexte avec `format` : + +- `txt` : Une seule chaîne en texte brut avec les URL sources intercalées. Idéal pour insertion directe dans un prompt. +- `json` : Une chaîne encodée en JSON de la forme `{"results":[...]}` avec une entrée par extrait. Idéal lorsque votre application doit afficher ou attribuer les sources individuellement. + +Définissez `product` pour orienter la récupération vers un produit ou un sujet spécifique lorsqu'une même requête pourrait correspondre à plusieurs domaines. + +La réponse plafonne `outputTokens` à 10 000 et indique `resultsCount` afin que vous puissiez voir combien d'extraits ont été inclus après application du budget. diff --git a/fr/api/universal-search/search.mdx b/fr/api/universal-search/search.mdx new file mode 100644 index 0000000000..06fd59c7b5 --- /dev/null +++ b/fr/api/universal-search/search.mdx @@ -0,0 +1,17 @@ +--- +title: "Rechercher dans la documentation et sur le web" +openapi: "/fr/universal-search-openapi.json POST /search" +keywords: ["recherche", "recherche universelle", "recherche web"] +--- + +La recherche universelle exécute une seule requête sur la documentation hébergée par Mintlify et sur le web, puis renvoie une liste combinée de résultats classés par pertinence. Utilisez-la pour alimenter des expériences de recherche intégrées à votre produit, des outils d'agents ou des pipelines de récupération qui doivent aller au-delà d'un seul déploiement. + +La recherche universelle nécessite l'entitlement Universal Search. [Contactez le service commercial](https://mintlify.com/enterprise) pour l'activer pour votre organisation. + +
+## Authentification +
+ +Authentifiez-vous avec une clé API de recherche universelle. Générez-en une sur la [page des clés API](https://app.mintlify.com/settings/organization/api-keys) de votre tableau de bord. + +Les clés API de recherche universelle sont distinctes des clés d'administration et d'assistant, et ne sont acceptées que sur les endpoints `/universal-search/v1`. diff --git a/fr/universal-search-openapi.json b/fr/universal-search-openapi.json new file mode 100644 index 0000000000..d1cd426a51 --- /dev/null +++ b/fr/universal-search-openapi.json @@ -0,0 +1,612 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "API de recherche universelle Mintlify", + "description": "Recherchez dans la documentation hébergée par Mintlify et sur le web avec une seule requête.", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://api.mintlify.com/universal-search/v1" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/search": { + "post": { + "summary": "Rechercher dans la documentation et sur le web", + "description": "Exécute une seule requête sur la documentation hébergée par Mintlify et sur des fournisseurs de recherche web, fusionne les résultats et les renvoie classés par pertinence. Renvoie éventuellement le contenu complet de la page pour chaque résultat.\n\nAuthentifiez-vous avec une clé d'API de recherche universelle.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query", + "numResults" + ], + "properties": { + "query": { + "type": "string", + "description": "La requête de recherche à exécuter. Doit être une chaîne non vide." + }, + "numResults": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "description": "Le nombre maximum de résultats à renvoyer. Doit être compris entre 1 et 20." + }, + "text": { + "description": "Contrôle si le contenu de la page est renvoyé avec chaque résultat. Omettez-le ou définissez-le sur `false` pour ne renvoyer que les métadonnées. Définissez-le sur `true` pour renvoyer le contenu complet de la page. Passez un objet avec `maxCharacters` pour renvoyer le contenu tronqué à une limite de caractères. La troncature préserve un Markdown valide en fermant les blocs de code ouverts.", + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "object", + "required": [ + "maxCharacters" + ], + "properties": { + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "Le nombre maximum de caractères du contenu de la page renvoyé par résultat." + } + } + } + ] + }, + "includeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "description": "Restreindre les résultats web à ces domaines. Les résultats hébergés par Mintlify ne sont pas affectés." + }, + "excludeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "description": "Exclure les résultats web de ces domaines. Les résultats hébergés par Mintlify ne sont pas affectés." + } + } + }, + "examples": { + "basic": { + "summary": "Recherche de base avec contenu de page tronqué", + "value": { + "query": "How do I create a Stripe charge?", + "numResults": 10, + "text": { + "maxCharacters": 4000 + } + } + }, + "filtered": { + "summary": "Filtrer les résultats web par domaine", + "value": { + "query": "authentication setup", + "numResults": 10, + "text": { + "maxCharacters": 4000 + }, + "includeDomains": [ + "docs.stripe.com" + ], + "excludeDomains": [ + "example.com" + ] + } + }, + "fullText": { + "summary": "Renvoyer le contenu complet de la page", + "value": { + "query": "How do I create a Stripe charge?", + "numResults": 10, + "text": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Résultats de la recherche.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "results" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Un identifiant unique pour cette requête. Incluez-le lorsque vous contactez le support." + }, + "results": { + "type": "array", + "description": "La liste fusionnée des résultats, classée par pertinence. Les résultats avec `source: \"mintlify\"` proviennent de la documentation hébergée par Mintlify ; les résultats avec `source: \"web\"` proviennent du web.", + "items": { + "$ref": "#/components/schemas/Result" + } + } + } + } + } + } + }, + "400": { + "description": "Corps de requête invalide.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Clé d'API manquante ou invalide.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "Limite de débit dépassée.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "La recherche a échoué.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/context": { + "post": { + "summary": "Assembler un contexte pour la génération augmentée par récupération", + "description": "Exécute une recherche universelle classée par pertinence et renvoie un contexte calibré en jetons, assemblé à partir des meilleurs résultats Mintlify et web. Utilisez cet endpoint pour alimenter un pipeline de génération augmentée par récupération (RAG) sans avoir à assembler vous-même les résultats. Choisissez `txt` pour un contexte en texte brut prêt à être transmis à un LLM, ou `json` pour une liste structurée que votre application peut afficher.\n\nAuthentifiez-vous avec une clé d'API de recherche universelle.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query", + "format" + ], + "properties": { + "query": { + "type": "string", + "description": "La question ou l'intention de l'utilisateur pour laquelle construire le contexte." + }, + "product": { + "type": "string", + "description": "Produit ou sujet facultatif vers lequel orienter la récupération. Lorsqu'il est défini, il est ajouté au début de la requête de récupération." + }, + "format": { + "type": "string", + "enum": [ + "txt", + "json" + ], + "description": "Forme du champ `response`. `txt` renvoie une charge utile unique en texte brut avec les URL sources ; `json` renvoie une chaîne encodée en JSON de la forme `{\"results\":[...]}` avec une entrée par extrait." + } + } + }, + "examples": { + "text": { + "summary": "Assembler un contexte en texte brut", + "value": { + "query": "How do I create a Stripe charge?", + "format": "txt" + } + }, + "json": { + "summary": "Assembler un contexte JSON structuré orienté vers un produit", + "value": { + "query": "authentication setup", + "product": "Stripe", + "format": "json" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Le contexte assemblé.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "query", + "response", + "resultsCount", + "outputTokens" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Un identifiant unique pour cette requête. Incluez-le lorsque vous contactez le support." + }, + "query": { + "type": "string", + "description": "Reprise de la `query` d'origine (sans le préfixe `product` éventuellement appliqué lors de la récupération)." + }, + "response": { + "type": "string", + "description": "Le contexte assemblé. Lorsque `format` vaut `txt`, il s'agit d'une charge utile en texte brut avec les URL sources. Lorsque `format` vaut `json`, il s'agit d'une chaîne encodée en JSON de la forme `{\"results\":[...]}` où chaque résultat contient l'URL, le titre et le Markdown de l'extrait." + }, + "resultsCount": { + "type": "integer", + "minimum": 0, + "description": "Le nombre d'extraits inclus dans `response` après application du budget de jetons." + }, + "outputTokens": { + "type": "integer", + "minimum": 0, + "description": "Le nombre approximatif de jetons de `response`. L'endpoint plafonne cette valeur à 10 000 jetons." + } + } + } + } + } + }, + "400": { + "description": "Corps de requête invalide.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Clé d'API manquante ou invalide.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "Limite de débit dépassée.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "L'assemblage du contexte a échoué.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/contents": { + "post": { + "summary": "Récupérer le contenu d'une page par URL ou ID", + "description": "Résout des URL ou des ID en pages de documentation hébergées par Mintlify et renvoie le contenu assemblé de chaque page. Chaque entrée reçoit un statut individuel afin que la réponse puisse signaler un succès partiel sans faire échouer l'ensemble de la requête.\n\nAuthentifiez-vous avec une clé d'API de recherche universelle.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Au moins un des champs `urls` ou `ids` est requis. Une seule requête peut référencer au maximum 20 éléments au total entre les deux champs.", + "properties": { + "urls": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string", + "format": "uri" + }, + "description": "URL canoniques des pages hébergées par Mintlify à récupérer. Les variantes `www` et sans `www` sont toutes deux prises en compte." + }, + "ids": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string" + }, + "description": "ID des pages à récupérer. Utilisez l'`id` renvoyé par [Rechercher dans la documentation et sur le web](/fr/api/universal-search/search)." + }, + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "Nombre maximum de caractères du contenu de la page renvoyé par résultat. La troncature préserve un Markdown valide en fermant les blocs de code ouverts." + } + } + }, + "examples": { + "byIds": { + "summary": "Récupérer des pages par ID", + "value": { + "ids": [ + "stripe-charges-guide", + "stripe-webhooks-guide" + ], + "maxCharacters": 4000 + } + }, + "byUrls": { + "summary": "Récupérer des pages par URL canonique", + "value": { + "urls": [ + "https://docs.stripe.com/charges", + "https://docs.stripe.com/webhooks" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Recherche de contenu terminée. Consultez `statuses` pour connaître le résultat de chaque entrée ; la réponse peut contenir des résultats partiels.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "results", + "statuses" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Un identifiant unique pour cette requête. Incluez-le lorsque vous contactez le support." + }, + "results": { + "type": "array", + "description": "Pages résolues avec succès, dans le même format que les résultats de recherche. Seules les entrées dont l'entrée correspondante dans `statuses` indique `success` apparaissent ici.", + "items": { + "$ref": "#/components/schemas/Result" + } + }, + "statuses": { + "type": "array", + "description": "Une entrée par élément fourni dans la requête, dans l'ordre où les entrées ont été fournies. Chaque entrée indique si l'élément a été résolu avec succès ou, dans le cas contraire, un `tag` d'erreur.", + "items": { + "oneOf": [ + { + "type": "object", + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "L'URL ou l'ID d'entrée auquel ce statut correspond." + }, + "status": { + "type": "string", + "enum": [ + "success" + ] + } + } + }, + { + "type": "object", + "required": [ + "id", + "status", + "error" + ], + "properties": { + "id": { + "type": "string", + "description": "L'URL ou l'ID d'entrée auquel ce statut correspond." + }, + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "object", + "required": [ + "tag", + "httpStatusCode" + ], + "properties": { + "tag": { + "type": "string", + "enum": [ + "not_found", + "not_synced", + "invalid_id", + "fetch_error" + ], + "description": "Tag d'erreur lisible par machine. `not_found` signifie que l'URL ou l'ID ne correspond à aucune page. `not_synced` signifie que le déploiement source n'a pas été indexé pour la recherche universelle. `invalid_id` signifie que l'ID était mal formé. `fetch_error` signifie que la recherche a échoué de manière inattendue." + }, + "httpStatusCode": { + "type": "integer", + "nullable": true, + "description": "Un code de statut HTTP décrivant au mieux l'erreur, ou `null` lorsqu'aucun code unique ne s'applique." + } + } + } + } + } + ] + } + } + } + } + } + } + }, + "400": { + "description": "Corps de requête invalide.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Clé d'API manquante ou invalide.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "Limite de débit dépassée.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "description": "L'en-tête Authorization attend un token Bearer. Utilisez une clé d'API de recherche universelle. Générez-en une sur la [page des clés API](https://app.mintlify.com/settings/organization/api-keys) de votre tableau de bord." + } + }, + "schemas": { + "ErrorResponse": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string", + "description": "Description lisible de l'erreur." + } + } + }, + "Result": { + "type": "object", + "required": [ + "id", + "url", + "title", + "text", + "score", + "source", + "siteName", + "breadcrumbs", + "publishedDate" + ], + "properties": { + "id": { + "type": "string", + "description": "Un identifiant stable pour le résultat. Pour les résultats Mintlify, il s'agit de l'ID de groupe de la page ; pour les résultats web, il s'agit de l'URL." + }, + "url": { + "type": "string", + "format": "uri", + "description": "L'URL canonique du résultat." + }, + "title": { + "type": "string", + "description": "Le titre de la page." + }, + "text": { + "type": "string", + "description": "Le contenu de la page. Vide lorsque `text` est omis ou défini sur `false`. Tronqué lorsque `text.maxCharacters` est fourni." + }, + "score": { + "type": "number", + "description": "Le score de pertinence de ce résultat." + }, + "source": { + "type": "string", + "enum": [ + "mintlify", + "web" + ], + "description": "D'où provient le résultat." + }, + "siteName": { + "type": "string", + "description": "Le nom du site d'où provient le résultat. Pour les résultats Mintlify, il s'agit du sous-domaine du déploiement ; pour les résultats web, il s'agit du nom d'hôte." + }, + "breadcrumbs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Le fil d'Ariane de navigation de la page. Renseigné uniquement pour les résultats Mintlify." + }, + "publishedDate": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "La date de publication indiquée par la source, lorsque disponible." + } + } + } + } + } +} diff --git a/gt.config.json b/gt.config.json index 8bda848b07..ffd18e6060 100644 --- a/gt.config.json +++ b/gt.config.json @@ -7,7 +7,8 @@ "./admin-openapi.json", "./discovery-openapi.json", "./openapi.json", - "./analytics.openapi.json" + "./analytics.openapi.json", + "./universal-search-openapi.json" ], "transform": [ { @@ -25,6 +26,10 @@ { "match": "^openapi.json$", "replace": "{locale}/openapi.json" + }, + { + "match": "^universal-search-openapi.json$", + "replace": "{locale}/universal-search-openapi.json" } ] }, @@ -88,6 +93,9 @@ }, "./analytics.openapi.json": { "preset": "openapi" + }, + "./universal-search-openapi.json": { + "preset": "openapi" } }, "docsUrlPattern": "/[locale]", @@ -105,7 +113,8 @@ "./admin-openapi.json", "./analytics.openapi.json", "./discovery-openapi.json", - "./openapi.json" + "./openapi.json", + "./universal-search-openapi.json" ] } } diff --git a/universal-search-openapi.json b/universal-search-openapi.json new file mode 100644 index 0000000000..d695d31946 --- /dev/null +++ b/universal-search-openapi.json @@ -0,0 +1,612 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "Mintlify Universal Search API", + "description": "Search across Mintlify-hosted documentation and the wider web with a single query.", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://api.mintlify.com/universal-search/v1" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/search": { + "post": { + "summary": "Search across documentation and the web", + "description": "Runs a single query against Mintlify-hosted documentation and web search providers, merges the results, and returns them ranked by relevance. Optionally returns the full stitched page content for each result.\n\nAuthenticate with a universal search API key.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query", + "numResults" + ], + "properties": { + "query": { + "type": "string", + "description": "The search query to run. Must be a non-empty string." + }, + "numResults": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "description": "The maximum number of results to return. Must be between 1 and 20." + }, + "text": { + "description": "Controls whether page content is returned with each result. Omit or set to `false` to return only metadata. Set to `true` to return the full stitched page content. Pass an object with `maxCharacters` to return content truncated to a character limit. Truncation preserves valid Markdown by closing open code fences.", + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "object", + "required": [ + "maxCharacters" + ], + "properties": { + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "The maximum number of characters of page content to return per result." + } + } + } + ] + }, + "includeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "description": "Restrict web results to these domains. Mintlify-hosted results are unaffected." + }, + "excludeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "description": "Exclude web results from these domains. Mintlify-hosted results are unaffected." + } + } + }, + "examples": { + "basic": { + "summary": "Basic search with truncated page content", + "value": { + "query": "How do I create a Stripe charge?", + "numResults": 10, + "text": { + "maxCharacters": 4000 + } + } + }, + "filtered": { + "summary": "Filter web results by domain", + "value": { + "query": "authentication setup", + "numResults": 10, + "text": { + "maxCharacters": 4000 + }, + "includeDomains": [ + "docs.stripe.com" + ], + "excludeDomains": [ + "example.com" + ] + } + }, + "fullText": { + "summary": "Return complete page content", + "value": { + "query": "How do I create a Stripe charge?", + "numResults": 10, + "text": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Search results.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "results" + ], + "properties": { + "requestId": { + "type": "string", + "description": "A unique identifier for this request. Include when contacting support." + }, + "results": { + "type": "array", + "description": "The merged list of results, ranked by relevance. Results with `source: \"mintlify\"` come from Mintlify-hosted documentation; results with `source: \"web\"` come from the wider web.", + "items": { + "$ref": "#/components/schemas/Result" + } + } + } + } + } + } + }, + "400": { + "description": "Invalid request body.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Missing or invalid API key.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Search failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/context": { + "post": { + "summary": "Assemble a context payload for retrieval-augmented generation", + "description": "Runs a ranked universal search and returns a token-budgeted context payload assembled from the top Mintlify and web results. Use this endpoint to feed a retrieval-augmented generation (RAG) pipeline without stitching results yourself. Choose `txt` for a plain-text context ready to pass to an LLM, or `json` for a structured list your application can render.\n\nAuthenticate with a universal search API key.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query", + "format" + ], + "properties": { + "query": { + "type": "string", + "description": "The user question or intent to build context for." + }, + "product": { + "type": "string", + "description": "Optional product or subject to bias retrieval toward. When set, it is prepended to the retrieval query." + }, + "format": { + "type": "string", + "enum": [ + "txt", + "json" + ], + "description": "Shape of the `response` field. `txt` returns a single plain-text payload with source URLs; `json` returns a JSON-encoded string of the form `{\"results\":[...]}` with one entry per snippet." + } + } + }, + "examples": { + "text": { + "summary": "Assemble a plain-text context", + "value": { + "query": "How do I create a Stripe charge?", + "format": "txt" + } + }, + "json": { + "summary": "Assemble a structured JSON context biased toward a product", + "value": { + "query": "authentication setup", + "product": "Stripe", + "format": "json" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The assembled context.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "query", + "response", + "resultsCount", + "outputTokens" + ], + "properties": { + "requestId": { + "type": "string", + "description": "A unique identifier for this request. Include when contacting support." + }, + "query": { + "type": "string", + "description": "Echo of the original `query` (without any `product` prefix that was applied during retrieval)." + }, + "response": { + "type": "string", + "description": "The assembled context. When `format` is `txt`, this is a plain-text payload with source URLs. When `format` is `json`, this is a JSON-encoded string of the form `{\"results\":[...]}` where each result contains the snippet's URL, title, and Markdown." + }, + "resultsCount": { + "type": "integer", + "minimum": 0, + "description": "The number of snippets included in `response` after the token budget was applied." + }, + "outputTokens": { + "type": "integer", + "minimum": 0, + "description": "The approximate token count of `response`. The endpoint caps this at 10,000 tokens." + } + } + } + } + } + }, + "400": { + "description": "Invalid request body.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Missing or invalid API key.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Context assembly failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/contents": { + "post": { + "summary": "Fetch page content by URL or ID", + "description": "Resolves URLs or IDs to Mintlify-hosted documentation pages and returns the stitched page content for each. Each input receives a per-item status so the response can report partial success without failing the whole request.\n\nAuthenticate with a universal search API key.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "At least one of `urls` or `ids` is required. A single request can reference at most 20 items across both fields combined.", + "properties": { + "urls": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string", + "format": "uri" + }, + "description": "Canonical URLs of Mintlify-hosted pages to fetch. `www` and non-`www` variants are both matched." + }, + "ids": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string" + }, + "description": "Page IDs to fetch. Use the `id` returned by [Search across documentation and the web](/api/universal-search/search)." + }, + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "Maximum number of characters of page content to return per result. Truncation preserves valid Markdown by closing open code fences." + } + } + }, + "examples": { + "byIds": { + "summary": "Fetch pages by ID", + "value": { + "ids": [ + "stripe-charges-guide", + "stripe-webhooks-guide" + ], + "maxCharacters": 4000 + } + }, + "byUrls": { + "summary": "Fetch pages by canonical URL", + "value": { + "urls": [ + "https://docs.stripe.com/charges", + "https://docs.stripe.com/webhooks" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Content lookup completed. Check `statuses` for per-input outcomes; the response can include partial results.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "results", + "statuses" + ], + "properties": { + "requestId": { + "type": "string", + "description": "A unique identifier for this request. Include when contacting support." + }, + "results": { + "type": "array", + "description": "Successfully resolved pages, in the same shape as search results. Only inputs whose corresponding entry in `statuses` reports `success` appear here.", + "items": { + "$ref": "#/components/schemas/Result" + } + }, + "statuses": { + "type": "array", + "description": "One entry per input in the request, in the order the inputs were provided. Each entry reports whether the input resolved successfully or, if not, an error `tag`.", + "items": { + "oneOf": [ + { + "type": "object", + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "The input URL or ID this status corresponds to." + }, + "status": { + "type": "string", + "enum": [ + "success" + ] + } + } + }, + { + "type": "object", + "required": [ + "id", + "status", + "error" + ], + "properties": { + "id": { + "type": "string", + "description": "The input URL or ID this status corresponds to." + }, + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "object", + "required": [ + "tag", + "httpStatusCode" + ], + "properties": { + "tag": { + "type": "string", + "enum": [ + "not_found", + "not_synced", + "invalid_id", + "fetch_error" + ], + "description": "Machine-readable error tag. `not_found` means the URL or ID did not match any page. `not_synced` means the source deployment has not been indexed for universal search. `invalid_id` means the ID was malformed. `fetch_error` means the lookup failed unexpectedly." + }, + "httpStatusCode": { + "type": "integer", + "nullable": true, + "description": "An HTTP status code that best describes the error, or `null` when no single code applies." + } + } + } + } + } + ] + } + } + } + } + } + } + }, + "400": { + "description": "Invalid request body.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Missing or invalid API key.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "description": "The Authorization header expects a Bearer token. Use a universal search API key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard." + } + }, + "schemas": { + "ErrorResponse": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string", + "description": "A human-readable description of the error." + } + } + }, + "Result": { + "type": "object", + "required": [ + "id", + "url", + "title", + "text", + "score", + "source", + "siteName", + "breadcrumbs", + "publishedDate" + ], + "properties": { + "id": { + "type": "string", + "description": "A stable identifier for the result. For Mintlify results this is the page group ID; for web results this is the URL." + }, + "url": { + "type": "string", + "format": "uri", + "description": "The canonical URL of the result." + }, + "title": { + "type": "string", + "description": "The title of the page." + }, + "text": { + "type": "string", + "description": "The page content. Empty when `text` was omitted or set to `false`. Truncated when `text.maxCharacters` was provided." + }, + "score": { + "type": "number", + "description": "The relevance score for this result." + }, + "source": { + "type": "string", + "enum": [ + "mintlify", + "web" + ], + "description": "Where the result came from." + }, + "siteName": { + "type": "string", + "description": "The name of the site the result came from. For Mintlify results this is the deployment subdomain; for web results this is the hostname." + }, + "breadcrumbs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The navigation breadcrumbs for the page. Only populated for Mintlify results." + }, + "publishedDate": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "The publication date reported by the source, when available." + } + } + } + } + } +} diff --git a/zh.json b/zh.json index 5233171112..5d67b90647 100644 --- a/zh.json +++ b/zh.json @@ -381,6 +381,15 @@ "zh/api/assistant/get-page-content" ] }, + { + "group": "通用搜索", + "icon": "globe", + "pages": [ + "zh/api/universal-search/search", + "zh/api/universal-search/context", + "zh/api/universal-search/contents" + ] + }, { "group": "数据分析", "icon": "chart-line", diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index cc1bd34b3f..9416171f2d 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -25,6 +25,9 @@ Mintlify 的 REST（Representational State Transfer）API 让你可以以编程 * [Create assistant message](/zh/api/assistant/create-assistant-message-v2)：将基于您的文档训练的 AI 助手嵌入到任意您选择的应用中。 * [搜索文档](/zh/api/assistant/search)：搜索您的文档。 * [获取页面内容](/zh/api/assistant/get-page-content)：检索文档页面的完整文本内容。 +* [通用搜索](/zh/api/universal-search/search)：使用单个查询同时搜索 Mintlify 托管的文档和网络内容。 +* [为 RAG 组装上下文负载](/zh/api/universal-search/context)：为检索增强生成流水线组装符合 token 预算的上下文负载。 +* [获取搜索结果的页面内容](/zh/api/universal-search/contents)：检索通用搜索返回页面的完整 Markdown。 * [获取用户反馈](/zh/api/analytics/feedback)：从您的文档中导出用户反馈。 * [获取 AI 助手会话](/zh/api/analytics/assistant-conversations)：导出 AI 助手的会话历史。 * [Get assistant caller stats](/zh/api/analytics/assistant-caller-stats)：获取按调用方类型划分的助手查询次数明细。 @@ -81,3 +84,11 @@ assistant API key 以 `mint_dsc_` 前缀开头。 使用 assistant API token 进行的调用可能会产生费用：可能会消耗你的助手额度，或产生超额费用。 + +
+ ### 通用搜索 API key +
+ +使用通用搜索 API key 调用 [Universal search](/zh/api/universal-search/search) 端点。 + +通用搜索是付费附加功能。生成密钥之前，请[联系销售](https://mintlify.com/enterprise)为你的组织启用 Universal Search 权限。 diff --git a/zh/api/universal-search/contents.mdx b/zh/api/universal-search/contents.mdx new file mode 100644 index 0000000000..169a6a4646 --- /dev/null +++ b/zh/api/universal-search/contents.mdx @@ -0,0 +1,22 @@ +--- +title: "获取搜索结果的页面内容" +openapi: "/zh/universal-search-openapi.json POST /contents" +keywords: ["contents", "页面内容", "通用搜索"] +--- + +在使用[在文档和网络中搜索](/zh/api/universal-search/search)之后，如果你希望获取特定页面完整拼接后的 Markdown 内容而无需重复执行查询，可以使用此端点。传入先前搜索返回的 `id`、Mintlify 托管页面的规范 URL，或两者的组合。 + +单次请求最多可以引用 20 个项目（`urls` 和 `ids` 合计）。当你提供 `maxCharacters` 时，每个页面都会被截断到该长度，同时保持 Markdown 有效（未闭合的代码块会被闭合）。 + +
+## 部分成功 +
+ +当请求体格式正确时，响应始终返回 `200`。请检查 `statuses` 数组以查看哪些输入解析成功、哪些失败。`results` 仅包含状态为 `success` 的页面。 + +错误 `tag` 的取值： + +- `not_found`：URL 或 ID 未匹配到任何已建立索引的页面。 +- `not_synced`：源部署尚未为通用搜索建立索引。 +- `invalid_id`：ID 格式不正确。 +- `fetch_error`：查询意外失败。请重试请求，或联系支持并附带 `requestId`。 diff --git a/zh/api/universal-search/context.mdx b/zh/api/universal-search/context.mdx new file mode 100644 index 0000000000..4e732d3076 --- /dev/null +++ b/zh/api/universal-search/context.mdx @@ -0,0 +1,16 @@ +--- +title: "为 RAG 组装上下文负载" +openapi: "/zh/universal-search-openapi.json POST /context" +keywords: ["context", "RAG", "检索", "通用搜索"] +--- + +使用此端点可为检索增强生成（RAG）流水线构建可直接使用的上下文负载。它会在后台运行按相关性排序的通用搜索，对片段进行去重和截断以确保每个页面都能公平地贡献内容，并返回一个符合 token 预算的结果，你可以直接将其交给 LLM。 + +使用 `format` 选择负载的形式： + +- `txt`：单个纯文本字符串，其中穿插了来源 URL。最适合直接传入到 prompt 中。 +- `json`：形如 `{"results":[...]}` 的 JSON 编码字符串，每个片段对应一个条目。当你的应用需要单独渲染或标注各个来源时，此格式最合适。 + +当同一查询可能匹配多个领域时，可设置 `product` 以将检索偏向特定的产品或主题。 + +响应会将 `outputTokens` 上限设为 10,000，并通过 `resultsCount` 报告在应用预算之后包含了多少个片段。 diff --git a/zh/api/universal-search/search.mdx b/zh/api/universal-search/search.mdx new file mode 100644 index 0000000000..a593ff6324 --- /dev/null +++ b/zh/api/universal-search/search.mdx @@ -0,0 +1,17 @@ +--- +title: "在文档和网络中搜索" +openapi: "/zh/universal-search-openapi.json POST /search" +keywords: ["搜索", "通用搜索", "网络搜索"] +--- + +通用搜索使用单个查询同时搜索 Mintlify 托管的文档和整个网络，并返回按相关性排序的合并结果列表。使用它可以为你产品内的搜索体验、代理工具或需要超越单个部署范围的检索管道提供支持。 + +通用搜索需要 Universal Search 权限。请[联系销售](https://mintlify.com/enterprise)为你的组织启用该权限。 + +
+## 身份验证 +
+ +使用通用搜索 API 密钥进行身份验证。在仪表板的 [API 密钥页面](https://app.mintlify.com/settings/organization/api-keys)生成一个。 + +通用搜索 API 密钥与管理员和助手 API 密钥不同，仅在 `/universal-search/v1` 端点上被接受。 diff --git a/zh/universal-search-openapi.json b/zh/universal-search-openapi.json new file mode 100644 index 0000000000..5227cab1a8 --- /dev/null +++ b/zh/universal-search-openapi.json @@ -0,0 +1,612 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "Mintlify 通用搜索 API", + "description": "使用单个查询同时搜索 Mintlify 托管的文档和整个网络。", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://api.mintlify.com/universal-search/v1" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/search": { + "post": { + "summary": "在文档和网络中搜索", + "description": "使用单个查询同时搜索 Mintlify 托管的文档和网络搜索提供商，合并结果并按相关性排序返回。可选择返回每个结果的完整页面内容。\n\n使用通用搜索 API key 进行身份验证。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query", + "numResults" + ], + "properties": { + "query": { + "type": "string", + "description": "要运行的搜索查询。必须为非空字符串。" + }, + "numResults": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "description": "返回的最大结果数。必须在 1 到 20 之间。" + }, + "text": { + "description": "控制是否随每个结果返回页面内容。省略或设置为 `false` 时仅返回元数据。设置为 `true` 时返回完整的页面内容。传递带 `maxCharacters` 的对象可将内容截断到字符上限。截断会闭合未关闭的代码块，保持 Markdown 有效。", + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "object", + "required": [ + "maxCharacters" + ], + "properties": { + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "每个结果返回的页面内容的最大字符数。" + } + } + } + ] + }, + "includeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "description": "将网络结果限制在这些域名内。Mintlify 托管的结果不受影响。" + }, + "excludeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "description": "排除这些域名的网络结果。Mintlify 托管的结果不受影响。" + } + } + }, + "examples": { + "basic": { + "summary": "带截断页面内容的基本搜索", + "value": { + "query": "How do I create a Stripe charge?", + "numResults": 10, + "text": { + "maxCharacters": 4000 + } + } + }, + "filtered": { + "summary": "按域名过滤网络结果", + "value": { + "query": "authentication setup", + "numResults": 10, + "text": { + "maxCharacters": 4000 + }, + "includeDomains": [ + "docs.stripe.com" + ], + "excludeDomains": [ + "example.com" + ] + } + }, + "fullText": { + "summary": "返回完整的页面内容", + "value": { + "query": "How do I create a Stripe charge?", + "numResults": 10, + "text": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "搜索结果。", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "results" + ], + "properties": { + "requestId": { + "type": "string", + "description": "此请求的唯一标识符。联系支持时请附带此值。" + }, + "results": { + "type": "array", + "description": "合并后的结果列表，按相关性排序。`source: \"mintlify\"` 的结果来自 Mintlify 托管的文档；`source: \"web\"` 的结果来自互联网。", + "items": { + "$ref": "#/components/schemas/Result" + } + } + } + } + } + } + }, + "400": { + "description": "请求体无效。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "缺少或无效的 API key。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "超出速率限制。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "搜索失败。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/context": { + "post": { + "summary": "为检索增强生成组装上下文负载", + "description": "运行按相关性排序的通用搜索，并根据排名靠前的 Mintlify 结果和网络结果，返回符合 token 预算的上下文负载。使用此端点可以为检索增强生成（RAG）流水线提供输入，而无需自行拼接结果。选择 `txt` 可获得直接传入 LLM 的纯文本上下文；选择 `json` 可获得应用可渲染的结构化列表。\n\n使用通用搜索 API key 进行身份验证。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query", + "format" + ], + "properties": { + "query": { + "type": "string", + "description": "要为其构建上下文的用户问题或意图。" + }, + "product": { + "type": "string", + "description": "可选的产品或主题，用于让检索偏向该方向。设置后，它会被前置到检索查询中。" + }, + "format": { + "type": "string", + "enum": [ + "txt", + "json" + ], + "description": "`response` 字段的形式。`txt` 返回带来源 URL 的单个纯文本负载；`json` 返回形如 `{\"results\":[...]}` 的 JSON 编码字符串，每个片段对应一个条目。" + } + } + }, + "examples": { + "text": { + "summary": "组装纯文本上下文", + "value": { + "query": "How do I create a Stripe charge?", + "format": "txt" + } + }, + "json": { + "summary": "组装偏向某个产品的结构化 JSON 上下文", + "value": { + "query": "authentication setup", + "product": "Stripe", + "format": "json" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "已组装的上下文。", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "query", + "response", + "resultsCount", + "outputTokens" + ], + "properties": { + "requestId": { + "type": "string", + "description": "此请求的唯一标识符。联系支持时请附带此值。" + }, + "query": { + "type": "string", + "description": "原始 `query` 的回显（不包含在检索期间应用的任何 `product` 前缀）。" + }, + "response": { + "type": "string", + "description": "已组装的上下文。当 `format` 为 `txt` 时，为带来源 URL 的纯文本负载。当 `format` 为 `json` 时，为形如 `{\"results\":[...]}` 的 JSON 编码字符串，其中每个结果包含片段的 URL、标题和 Markdown。" + }, + "resultsCount": { + "type": "integer", + "minimum": 0, + "description": "在应用 token 预算后包含在 `response` 中的片段数量。" + }, + "outputTokens": { + "type": "integer", + "minimum": 0, + "description": "`response` 的近似 token 数。此端点将其上限设置为 10,000 个 token。" + } + } + } + } + } + }, + "400": { + "description": "请求体无效。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "缺少或无效的 API key。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "超出速率限制。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "上下文组装失败。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/contents": { + "post": { + "summary": "按 URL 或 ID 获取页面内容", + "description": "将 URL 或 ID 解析为 Mintlify 托管的文档页面，并返回每个页面拼接后的内容。每个输入都有独立的状态项，使响应能够报告部分成功而不会导致整个请求失败。\n\n使用通用搜索 API key 进行身份验证。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "`urls` 或 `ids` 至少需要提供其中一个。单次请求最多可以引用 20 个项目（两个字段合计）。", + "properties": { + "urls": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string", + "format": "uri" + }, + "description": "要获取的 Mintlify 托管页面的规范 URL。`www` 和非 `www` 的变体都会被匹配。" + }, + "ids": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string" + }, + "description": "要获取的页面 ID。使用[在文档和网络中搜索](/zh/api/universal-search/search)返回的 `id`。" + }, + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "每个结果返回的页面内容的最大字符数。截断会闭合未关闭的代码块，保持 Markdown 有效。" + } + } + }, + "examples": { + "byIds": { + "summary": "按 ID 获取页面", + "value": { + "ids": [ + "stripe-charges-guide", + "stripe-webhooks-guide" + ], + "maxCharacters": 4000 + } + }, + "byUrls": { + "summary": "按规范 URL 获取页面", + "value": { + "urls": [ + "https://docs.stripe.com/charges", + "https://docs.stripe.com/webhooks" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "内容查询已完成。请检查 `statuses` 以了解每个输入的结果；响应可能包含部分结果。", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "requestId", + "results", + "statuses" + ], + "properties": { + "requestId": { + "type": "string", + "description": "此请求的唯一标识符。联系支持时请附带此值。" + }, + "results": { + "type": "array", + "description": "已成功解析的页面，结构与搜索结果相同。仅当输入在 `statuses` 中对应条目报告为 `success` 时，才会出现在此处。", + "items": { + "$ref": "#/components/schemas/Result" + } + }, + "statuses": { + "type": "array", + "description": "请求中每个输入对应一个条目，顺序与输入的提供顺序一致。每个条目报告该输入是否解析成功；若未成功，则包含一个错误 `tag`。", + "items": { + "oneOf": [ + { + "type": "object", + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "此状态对应的输入 URL 或 ID。" + }, + "status": { + "type": "string", + "enum": [ + "success" + ] + } + } + }, + { + "type": "object", + "required": [ + "id", + "status", + "error" + ], + "properties": { + "id": { + "type": "string", + "description": "此状态对应的输入 URL 或 ID。" + }, + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "object", + "required": [ + "tag", + "httpStatusCode" + ], + "properties": { + "tag": { + "type": "string", + "enum": [ + "not_found", + "not_synced", + "invalid_id", + "fetch_error" + ], + "description": "机器可读的错误标签。`not_found` 表示 URL 或 ID 未匹配到任何页面。`not_synced` 表示源部署尚未为通用搜索建立索引。`invalid_id` 表示 ID 格式不正确。`fetch_error` 表示查询意外失败。" + }, + "httpStatusCode": { + "type": "integer", + "nullable": true, + "description": "最能描述该错误的 HTTP 状态码；当没有合适的单一状态码时为 `null`。" + } + } + } + } + } + ] + } + } + } + } + } + } + }, + "400": { + "description": "请求体无效。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "缺少或无效的 API key。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "description": "超出速率限制。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "description": "Authorization 请求头需要 Bearer token。请使用通用搜索 API key。在仪表板的 [API 密钥页面](https://app.mintlify.com/settings/organization/api-keys) 生成一个。" + } + }, + "schemas": { + "ErrorResponse": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string", + "description": "错误的可读描述。" + } + } + }, + "Result": { + "type": "object", + "required": [ + "id", + "url", + "title", + "text", + "score", + "source", + "siteName", + "breadcrumbs", + "publishedDate" + ], + "properties": { + "id": { + "type": "string", + "description": "结果的稳定标识符。对于 Mintlify 结果，此值为页面分组 ID；对于网络结果，此值为 URL。" + }, + "url": { + "type": "string", + "format": "uri", + "description": "结果的规范 URL。" + }, + "title": { + "type": "string", + "description": "页面的标题。" + }, + "text": { + "type": "string", + "description": "页面内容。当 `text` 被省略或设置为 `false` 时为空。当提供 `text.maxCharacters` 时会被截断。" + }, + "score": { + "type": "number", + "description": "此结果的相关性得分。" + }, + "source": { + "type": "string", + "enum": [ + "mintlify", + "web" + ], + "description": "结果的来源。" + }, + "siteName": { + "type": "string", + "description": "结果所属站点的名称。对于 Mintlify 结果，此值为部署子域名；对于网络结果，此值为主机名。" + }, + "breadcrumbs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "页面的导航面包屑。仅针对 Mintlify 结果填充。" + }, + "publishedDate": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "来源报告的发布日期（如果可用）。" + } + } + } + } + } +}