From 73e9e85ba47d376b2c5fc2b126f07e564b55d865 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:41:37 +0000 Subject: [PATCH 1/6] docs: document universal search API --- api/introduction.mdx | 18 +- api/universal-search/search.mdx | 15 ++ docs.json | 7 + es.json | 7 + es/api/universal-search/search.mdx | 15 ++ es/universal-search-openapi.json | 276 +++++++++++++++++++++++++++++ fr.json | 7 + fr/api/universal-search/search.mdx | 15 ++ fr/universal-search-openapi.json | 276 +++++++++++++++++++++++++++++ gt.config.json | 13 +- universal-search-openapi.json | 276 +++++++++++++++++++++++++++++ zh.json | 7 + zh/api/universal-search/search.mdx | 15 ++ zh/universal-search-openapi.json | 276 +++++++++++++++++++++++++++++ 14 files changed, 1216 insertions(+), 7 deletions(-) create mode 100644 api/universal-search/search.mdx create mode 100644 es/api/universal-search/search.mdx create mode 100644 es/universal-search-openapi.json create mode 100644 fr/api/universal-search/search.mdx create mode 100644 fr/universal-search-openapi.json create mode 100644 universal-search-openapi.json create mode 100644 zh/api/universal-search/search.mdx create mode 100644 zh/universal-search-openapi.json diff --git a/api/introduction.mdx b/api/introduction.mdx index e27b578335..495b68381b 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -23,6 +23,7 @@ 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. - [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 +48,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 +98,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/search.mdx b/api/universal-search/search.mdx new file mode 100644 index 0000000000..0c4ff65fab --- /dev/null +++ b/api/universal-search/search.mdx @@ -0,0 +1,15 @@ +--- +title: "Universal search" +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..7cbb316242 100644 --- a/docs.json +++ b/docs.json @@ -407,6 +407,13 @@ "api/assistant/get-page-content" ] }, + { + "group": "Universal search", + "icon": "globe", + "pages": [ + "api/universal-search/search" + ] + }, { "group": "Analytics", "icon": "chart-line", diff --git a/es.json b/es.json index 8641f475d3..232e5361c0 100644 --- a/es.json +++ b/es.json @@ -386,6 +386,13 @@ "es/api/assistant/get-page-content" ] }, + { + "group": "Búsqueda universal", + "icon": "globe", + "pages": [ + "es/api/universal-search/search" + ] + }, { "group": "Analytics", "icon": "chart-line", diff --git a/es/api/universal-search/search.mdx b/es/api/universal-search/search.mdx new file mode 100644 index 0000000000..7b7880b8c0 --- /dev/null +++ b/es/api/universal-search/search.mdx @@ -0,0 +1,15 @@ +--- +title: "Búsqueda universal" +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..c5c4b9e340 --- /dev/null +++ b/es/universal-search-openapi.json @@ -0,0 +1,276 @@ +{ + "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": { + "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." + } + } + } + } + } + } + } + } + }, + "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" + } + } + } + } + } + } + } + }, + "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." + } + } + } + } + } +} diff --git a/fr.json b/fr.json index 723b354ec6..8d5a0b3503 100644 --- a/fr.json +++ b/fr.json @@ -386,6 +386,13 @@ "fr/api/assistant/get-page-content" ] }, + { + "group": "Recherche universelle", + "icon": "globe", + "pages": [ + "fr/api/universal-search/search" + ] + }, { "group": "Analytics", "icon": "chart-line", diff --git a/fr/api/universal-search/search.mdx b/fr/api/universal-search/search.mdx new file mode 100644 index 0000000000..69afb24ef1 --- /dev/null +++ b/fr/api/universal-search/search.mdx @@ -0,0 +1,15 @@ +--- +title: "Recherche universelle" +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..c5c4b9e340 --- /dev/null +++ b/fr/universal-search-openapi.json @@ -0,0 +1,276 @@ +{ + "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": { + "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." + } + } + } + } + } + } + } + } + }, + "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" + } + } + } + } + } + } + } + }, + "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." + } + } + } + } + } +} 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..c5c4b9e340 --- /dev/null +++ b/universal-search-openapi.json @@ -0,0 +1,276 @@ +{ + "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": { + "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." + } + } + } + } + } + } + } + } + }, + "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" + } + } + } + } + } + } + } + }, + "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." + } + } + } + } + } +} diff --git a/zh.json b/zh.json index 5233171112..0b0fb69971 100644 --- a/zh.json +++ b/zh.json @@ -381,6 +381,13 @@ "zh/api/assistant/get-page-content" ] }, + { + "group": "通用搜索", + "icon": "globe", + "pages": [ + "zh/api/universal-search/search" + ] + }, { "group": "数据分析", "icon": "chart-line", diff --git a/zh/api/universal-search/search.mdx b/zh/api/universal-search/search.mdx new file mode 100644 index 0000000000..4bf2be95d9 --- /dev/null +++ b/zh/api/universal-search/search.mdx @@ -0,0 +1,15 @@ +--- +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..c5c4b9e340 --- /dev/null +++ b/zh/universal-search-openapi.json @@ -0,0 +1,276 @@ +{ + "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": { + "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." + } + } + } + } + } + } + } + } + }, + "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" + } + } + } + } + } + } + } + }, + "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." + } + } + } + } + } +} From 7d6df80bee3a87a441339a7ad14bdb7bd2ddadd1 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:46:43 +0000 Subject: [PATCH 2/6] docs: polish universal search page and mirror translations --- api/universal-search/search.mdx | 2 +- es/api/introduction.mdx | 9 +++++ es/api/universal-search/search.mdx | 6 ++- es/universal-search-openapi.json | 62 +++++++++++++++--------------- fr/api/introduction.mdx | 9 +++++ fr/api/universal-search/search.mdx | 4 +- fr/universal-search-openapi.json | 62 +++++++++++++++--------------- zh/api/introduction.mdx | 9 +++++ zh/api/universal-search/search.mdx | 4 +- zh/universal-search-openapi.json | 62 +++++++++++++++--------------- 10 files changed, 131 insertions(+), 98 deletions(-) diff --git a/api/universal-search/search.mdx b/api/universal-search/search.mdx index 0c4ff65fab..01cf2a73b5 100644 --- a/api/universal-search/search.mdx +++ b/api/universal-search/search.mdx @@ -1,5 +1,5 @@ --- -title: "Universal search" +title: "Search across documentation and the web" openapi: "/universal-search-openapi.json POST /search" keywords: ["search", "universal search", "web search"] --- diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index 8b0bbeeff7..01591fe9f8 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -25,6 +25,7 @@ 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. * [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 +82,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/search.mdx b/es/api/universal-search/search.mdx index 7b7880b8c0..4a7af1a059 100644 --- a/es/api/universal-search/search.mdx +++ b/es/api/universal-search/search.mdx @@ -1,14 +1,16 @@ --- -title: "Búsqueda universal" +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 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. diff --git a/es/universal-search-openapi.json b/es/universal-search-openapi.json index c5c4b9e340..d420585d64 100644 --- a/es/universal-search-openapi.json +++ b/es/universal-search-openapi.json @@ -1,8 +1,8 @@ { "openapi": "3.0.1", "info": { - "title": "Mintlify Universal Search API", - "description": "Search across Mintlify-hosted documentation and the wider web with a single query.", + "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": [ @@ -18,8 +18,8 @@ "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.", + "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": { @@ -33,16 +33,16 @@ "properties": { "query": { "type": "string", - "description": "The search query to run. Must be a non-empty 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": "The maximum number of results to return. Must be between 1 and 20." + "description": "Número máximo de resultados que se van a devolver. Debe estar entre 1 y 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.", + "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" @@ -56,7 +56,7 @@ "maxCharacters": { "type": "integer", "minimum": 1, - "description": "The maximum number of characters of page content to return per result." + "description": "Número máximo de caracteres del contenido de la página que se devuelve por resultado." } } } @@ -68,7 +68,7 @@ "items": { "type": "string" }, - "description": "Restrict web results to these domains. Mintlify-hosted results are unaffected." + "description": "Restringe los resultados web a estos dominios. Los resultados alojados en Mintlify no se ven afectados." }, "excludeDomains": { "type": "array", @@ -76,13 +76,13 @@ "items": { "type": "string" }, - "description": "Exclude web results from these domains. Mintlify-hosted results are unaffected." + "description": "Excluye los resultados web de estos dominios. Los resultados alojados en Mintlify no se ven afectados." } } }, "examples": { "basic": { - "summary": "Basic search with truncated page content", + "summary": "Búsqueda básica con contenido de página truncado", "value": { "query": "How do I create a Stripe charge?", "numResults": 10, @@ -92,7 +92,7 @@ } }, "filtered": { - "summary": "Filter web results by domain", + "summary": "Filtrar resultados web por dominio", "value": { "query": "authentication setup", "numResults": 10, @@ -108,7 +108,7 @@ } }, "fullText": { - "summary": "Return complete page content", + "summary": "Devolver el contenido completo de la página", "value": { "query": "How do I create a Stripe charge?", "numResults": 10, @@ -121,7 +121,7 @@ }, "responses": { "200": { - "description": "Search results.", + "description": "Resultados de la búsqueda.", "content": { "application/json": { "schema": { @@ -133,11 +133,11 @@ "properties": { "requestId": { "type": "string", - "description": "A unique identifier for this request. Include when contacting support." + "description": "Un identificador único para esta solicitud. Inclúyelo cuando contactes con soporte." }, "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.", + "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": { "type": "object", "required": [ @@ -154,24 +154,24 @@ "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." + "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": "The canonical URL of the result." + "description": "La URL canónica del resultado." }, "title": { "type": "string", - "description": "The title of the page." + "description": "El título de la página." }, "text": { "type": "string", - "description": "The page content. Empty when `text` was omitted or set to `false`. Truncated when `text.maxCharacters` was provided." + "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": "The relevance score for this result." + "description": "La puntuación de relevancia de este resultado." }, "source": { "type": "string", @@ -179,24 +179,24 @@ "mintlify", "web" ], - "description": "Where the result came from." + "description": "De dónde proviene el resultado." }, "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." + "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": "The navigation breadcrumbs for the page. Only populated for Mintlify results." + "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": "The publication date reported by the source, when available." + "description": "La fecha de publicación informada por la fuente, cuando esté disponible." } } } @@ -207,7 +207,7 @@ } }, "400": { - "description": "Invalid request body.", + "description": "Cuerpo de la solicitud no válido.", "content": { "application/json": { "schema": { @@ -217,7 +217,7 @@ } }, "401": { - "description": "Missing or invalid API key.", + "description": "Clave API ausente o no válida.", "content": { "application/json": { "schema": { @@ -227,7 +227,7 @@ } }, "429": { - "description": "Rate limit exceeded.", + "description": "Se superó el límite de tasa.", "content": { "application/json": { "schema": { @@ -237,7 +237,7 @@ } }, "500": { - "description": "Search failed.", + "description": "La búsqueda falló.", "content": { "application/json": { "schema": { @@ -255,7 +255,7 @@ "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." + "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": { @@ -267,7 +267,7 @@ "properties": { "error": { "type": "string", - "description": "A human-readable description of the error." + "description": "Descripción legible por humanos del error." } } } diff --git a/fr/api/introduction.mdx b/fr/api/introduction.mdx index c2070222b4..924844d2dd 100644 --- a/fr/api/introduction.mdx +++ b/fr/api/introduction.mdx @@ -25,6 +25,7 @@ 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. * [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 +82,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/search.mdx b/fr/api/universal-search/search.mdx index 69afb24ef1..06fd59c7b5 100644 --- a/fr/api/universal-search/search.mdx +++ b/fr/api/universal-search/search.mdx @@ -1,5 +1,5 @@ --- -title: "Recherche universelle" +title: "Rechercher dans la documentation et sur le web" openapi: "/fr/universal-search-openapi.json POST /search" keywords: ["recherche", "recherche universelle", "recherche web"] --- @@ -8,7 +8,9 @@ La recherche universelle exécute une seule requête sur la documentation héber 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. diff --git a/fr/universal-search-openapi.json b/fr/universal-search-openapi.json index c5c4b9e340..6b6fdd6202 100644 --- a/fr/universal-search-openapi.json +++ b/fr/universal-search-openapi.json @@ -1,8 +1,8 @@ { "openapi": "3.0.1", "info": { - "title": "Mintlify Universal Search API", - "description": "Search across Mintlify-hosted documentation and the wider web with a single query.", + "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": [ @@ -18,8 +18,8 @@ "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.", + "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": { @@ -33,16 +33,16 @@ "properties": { "query": { "type": "string", - "description": "The search query to run. Must be a non-empty string." + "description": "La requête de recherche à exécuter. Doit être une chaîne non vide." }, "numResults": { "type": "integer", "minimum": 1, "maximum": 20, - "description": "The maximum number of results to return. Must be between 1 and 20." + "description": "Le nombre maximum de résultats à renvoyer. Doit être compris entre 1 et 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.", + "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" @@ -56,7 +56,7 @@ "maxCharacters": { "type": "integer", "minimum": 1, - "description": "The maximum number of characters of page content to return per result." + "description": "Le nombre maximum de caractères du contenu de la page renvoyé par résultat." } } } @@ -68,7 +68,7 @@ "items": { "type": "string" }, - "description": "Restrict web results to these domains. Mintlify-hosted results are unaffected." + "description": "Restreindre les résultats web à ces domaines. Les résultats hébergés par Mintlify ne sont pas affectés." }, "excludeDomains": { "type": "array", @@ -76,13 +76,13 @@ "items": { "type": "string" }, - "description": "Exclude web results from these domains. Mintlify-hosted results are unaffected." + "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": "Basic search with truncated page content", + "summary": "Recherche de base avec contenu de page tronqué", "value": { "query": "How do I create a Stripe charge?", "numResults": 10, @@ -92,7 +92,7 @@ } }, "filtered": { - "summary": "Filter web results by domain", + "summary": "Filtrer les résultats web par domaine", "value": { "query": "authentication setup", "numResults": 10, @@ -108,7 +108,7 @@ } }, "fullText": { - "summary": "Return complete page content", + "summary": "Renvoyer le contenu complet de la page", "value": { "query": "How do I create a Stripe charge?", "numResults": 10, @@ -121,7 +121,7 @@ }, "responses": { "200": { - "description": "Search results.", + "description": "Résultats de la recherche.", "content": { "application/json": { "schema": { @@ -133,11 +133,11 @@ "properties": { "requestId": { "type": "string", - "description": "A unique identifier for this request. Include when contacting support." + "description": "Un identifiant unique pour cette requête. Incluez-le lorsque vous contactez le 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.", + "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": { "type": "object", "required": [ @@ -154,24 +154,24 @@ "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." + "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": "The canonical URL of the result." + "description": "L'URL canonique du résultat." }, "title": { "type": "string", - "description": "The title of the page." + "description": "Le titre de la page." }, "text": { "type": "string", - "description": "The page content. Empty when `text` was omitted or set to `false`. Truncated when `text.maxCharacters` was provided." + "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": "The relevance score for this result." + "description": "Le score de pertinence de ce résultat." }, "source": { "type": "string", @@ -179,24 +179,24 @@ "mintlify", "web" ], - "description": "Where the result came from." + "description": "D'où provient le résultat." }, "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." + "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": "The navigation breadcrumbs for the page. Only populated for Mintlify results." + "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": "The publication date reported by the source, when available." + "description": "La date de publication indiquée par la source, lorsque disponible." } } } @@ -207,7 +207,7 @@ } }, "400": { - "description": "Invalid request body.", + "description": "Corps de requête invalide.", "content": { "application/json": { "schema": { @@ -217,7 +217,7 @@ } }, "401": { - "description": "Missing or invalid API key.", + "description": "Clé d'API manquante ou invalide.", "content": { "application/json": { "schema": { @@ -227,7 +227,7 @@ } }, "429": { - "description": "Rate limit exceeded.", + "description": "Limite de débit dépassée.", "content": { "application/json": { "schema": { @@ -237,7 +237,7 @@ } }, "500": { - "description": "Search failed.", + "description": "La recherche a échoué.", "content": { "application/json": { "schema": { @@ -255,7 +255,7 @@ "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." + "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": { @@ -267,7 +267,7 @@ "properties": { "error": { "type": "string", - "description": "A human-readable description of the error." + "description": "Description lisible de l'erreur." } } } diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index cc1bd34b3f..87ea3adb04 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -25,6 +25,7 @@ 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 托管的文档和网络内容。 * [获取用户反馈](/zh/api/analytics/feedback)：从您的文档中导出用户反馈。 * [获取 AI 助手会话](/zh/api/analytics/assistant-conversations)：导出 AI 助手的会话历史。 * [Get assistant caller stats](/zh/api/analytics/assistant-caller-stats)：获取按调用方类型划分的助手查询次数明细。 @@ -81,3 +82,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/search.mdx b/zh/api/universal-search/search.mdx index 4bf2be95d9..a593ff6324 100644 --- a/zh/api/universal-search/search.mdx +++ b/zh/api/universal-search/search.mdx @@ -1,5 +1,5 @@ --- -title: "通用搜索" +title: "在文档和网络中搜索" openapi: "/zh/universal-search-openapi.json POST /search" keywords: ["搜索", "通用搜索", "网络搜索"] --- @@ -8,7 +8,9 @@ keywords: ["搜索", "通用搜索", "网络搜索"] 通用搜索需要 Universal Search 权限。请[联系销售](https://mintlify.com/enterprise)为你的组织启用该权限。 +
## 身份验证 +
使用通用搜索 API 密钥进行身份验证。在仪表板的 [API 密钥页面](https://app.mintlify.com/settings/organization/api-keys)生成一个。 diff --git a/zh/universal-search-openapi.json b/zh/universal-search-openapi.json index c5c4b9e340..974a65beee 100644 --- a/zh/universal-search-openapi.json +++ b/zh/universal-search-openapi.json @@ -1,8 +1,8 @@ { "openapi": "3.0.1", "info": { - "title": "Mintlify Universal Search API", - "description": "Search across Mintlify-hosted documentation and the wider web with a single query.", + "title": "Mintlify 通用搜索 API", + "description": "使用单个查询同时搜索 Mintlify 托管的文档和整个网络。", "version": "1.0.0" }, "servers": [ @@ -18,8 +18,8 @@ "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.", + "summary": "在文档和网络中搜索", + "description": "使用单个查询同时搜索 Mintlify 托管的文档和网络搜索提供商，合并结果并按相关性排序返回。可选择返回每个结果的完整页面内容。\n\n使用通用搜索 API key 进行身份验证。", "requestBody": { "required": true, "content": { @@ -33,16 +33,16 @@ "properties": { "query": { "type": "string", - "description": "The search query to run. Must be a non-empty string." + "description": "要运行的搜索查询。必须为非空字符串。" }, "numResults": { "type": "integer", "minimum": 1, "maximum": 20, - "description": "The maximum number of results to return. Must be between 1 and 20." + "description": "返回的最大结果数。必须在 1 到 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.", + "description": "控制是否随每个结果返回页面内容。省略或设置为 `false` 时仅返回元数据。设置为 `true` 时返回完整的页面内容。传递带 `maxCharacters` 的对象可将内容截断到字符上限。截断会闭合未关闭的代码块，保持 Markdown 有效。", "oneOf": [ { "type": "boolean" @@ -56,7 +56,7 @@ "maxCharacters": { "type": "integer", "minimum": 1, - "description": "The maximum number of characters of page content to return per result." + "description": "每个结果返回的页面内容的最大字符数。" } } } @@ -68,7 +68,7 @@ "items": { "type": "string" }, - "description": "Restrict web results to these domains. Mintlify-hosted results are unaffected." + "description": "将网络结果限制在这些域名内。Mintlify 托管的结果不受影响。" }, "excludeDomains": { "type": "array", @@ -76,13 +76,13 @@ "items": { "type": "string" }, - "description": "Exclude web results from these domains. Mintlify-hosted results are unaffected." + "description": "排除这些域名的网络结果。Mintlify 托管的结果不受影响。" } } }, "examples": { "basic": { - "summary": "Basic search with truncated page content", + "summary": "带截断页面内容的基本搜索", "value": { "query": "How do I create a Stripe charge?", "numResults": 10, @@ -92,7 +92,7 @@ } }, "filtered": { - "summary": "Filter web results by domain", + "summary": "按域名过滤网络结果", "value": { "query": "authentication setup", "numResults": 10, @@ -108,7 +108,7 @@ } }, "fullText": { - "summary": "Return complete page content", + "summary": "返回完整的页面内容", "value": { "query": "How do I create a Stripe charge?", "numResults": 10, @@ -121,7 +121,7 @@ }, "responses": { "200": { - "description": "Search results.", + "description": "搜索结果。", "content": { "application/json": { "schema": { @@ -133,11 +133,11 @@ "properties": { "requestId": { "type": "string", - "description": "A unique identifier for this request. Include when contacting support." + "description": "此请求的唯一标识符。联系支持时请附带此值。" }, "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.", + "description": "合并后的结果列表，按相关性排序。`source: \"mintlify\"` 的结果来自 Mintlify 托管的文档；`source: \"web\"` 的结果来自互联网。", "items": { "type": "object", "required": [ @@ -154,24 +154,24 @@ "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." + "description": "结果的稳定标识符。对于 Mintlify 结果，此值为页面分组 ID；对于网络结果，此值为 URL。" }, "url": { "type": "string", "format": "uri", - "description": "The canonical URL of the result." + "description": "结果的规范 URL。" }, "title": { "type": "string", - "description": "The title of the page." + "description": "页面的标题。" }, "text": { "type": "string", - "description": "The page content. Empty when `text` was omitted or set to `false`. Truncated when `text.maxCharacters` was provided." + "description": "页面内容。当 `text` 被省略或设置为 `false` 时为空。当提供 `text.maxCharacters` 时会被截断。" }, "score": { "type": "number", - "description": "The relevance score for this result." + "description": "此结果的相关性得分。" }, "source": { "type": "string", @@ -179,24 +179,24 @@ "mintlify", "web" ], - "description": "Where the result came from." + "description": "结果的来源。" }, "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." + "description": "结果所属站点的名称。对于 Mintlify 结果，此值为部署子域名；对于网络结果，此值为主机名。" }, "breadcrumbs": { "type": "array", "items": { "type": "string" }, - "description": "The navigation breadcrumbs for the page. Only populated for Mintlify results." + "description": "页面的导航面包屑。仅针对 Mintlify 结果填充。" }, "publishedDate": { "type": "string", "format": "date-time", "nullable": true, - "description": "The publication date reported by the source, when available." + "description": "来源报告的发布日期（如果可用）。" } } } @@ -207,7 +207,7 @@ } }, "400": { - "description": "Invalid request body.", + "description": "请求体无效。", "content": { "application/json": { "schema": { @@ -217,7 +217,7 @@ } }, "401": { - "description": "Missing or invalid API key.", + "description": "缺少或无效的 API key。", "content": { "application/json": { "schema": { @@ -227,7 +227,7 @@ } }, "429": { - "description": "Rate limit exceeded.", + "description": "超出速率限制。", "content": { "application/json": { "schema": { @@ -237,7 +237,7 @@ } }, "500": { - "description": "Search failed.", + "description": "搜索失败。", "content": { "application/json": { "schema": { @@ -255,7 +255,7 @@ "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." + "description": "Authorization 请求头需要 Bearer token。请使用通用搜索 API key。在仪表板的 [API 密钥页面](https://app.mintlify.com/settings/organization/api-keys) 生成一个。" } }, "schemas": { @@ -267,7 +267,7 @@ "properties": { "error": { "type": "string", - "description": "A human-readable description of the error." + "description": "错误的可读描述。" } } } From 2b43b3fa64b2e904adc8f07d31c7f413118c88ed Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 15 Jul 2026 21:30:04 +0000 Subject: [PATCH 3/6] docs: document universal search contents endpoint --- api/introduction.mdx | 1 + api/universal-search/contents.mdx | 20 ++ docs.json | 3 +- es.json | 3 +- es/api/introduction.mdx | 1 + es/api/universal-search/contents.mdx | 22 ++ es/universal-search-openapi.json | 318 ++++++++++++++++++++++----- fr.json | 3 +- fr/api/introduction.mdx | 1 + fr/api/universal-search/contents.mdx | 22 ++ fr/universal-search-openapi.json | 318 ++++++++++++++++++++++----- universal-search-openapi.json | 318 ++++++++++++++++++++++----- zh.json | 3 +- zh/api/introduction.mdx | 1 + zh/api/universal-search/contents.mdx | 22 ++ zh/universal-search-openapi.json | 318 ++++++++++++++++++++++----- 16 files changed, 1130 insertions(+), 244 deletions(-) create mode 100644 api/universal-search/contents.mdx create mode 100644 es/api/universal-search/contents.mdx create mode 100644 fr/api/universal-search/contents.mdx create mode 100644 zh/api/universal-search/contents.mdx diff --git a/api/introduction.mdx b/api/introduction.mdx index 495b68381b..50d01b13e1 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -24,6 +24,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - [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. +- [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. 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/docs.json b/docs.json index 7cbb316242..ee516594d5 100644 --- a/docs.json +++ b/docs.json @@ -411,7 +411,8 @@ "group": "Universal search", "icon": "globe", "pages": [ - "api/universal-search/search" + "api/universal-search/search", + "api/universal-search/contents" ] }, { diff --git a/es.json b/es.json index 232e5361c0..03f60fdfd7 100644 --- a/es.json +++ b/es.json @@ -390,7 +390,8 @@ "group": "Búsqueda universal", "icon": "globe", "pages": [ - "es/api/universal-search/search" + "es/api/universal-search/search", + "es/api/universal-search/contents" ] }, { diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index 01591fe9f8..1e22c735cc 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -26,6 +26,7 @@ La REST (Representational State Transfer) API de Mintlify te permite interactuar * [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. +* [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. 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/universal-search-openapi.json b/es/universal-search-openapi.json index d420585d64..1ed0a1790e 100644 --- a/es/universal-search-openapi.json +++ b/es/universal-search-openapi.json @@ -139,66 +139,7 @@ "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": { - "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." - } - } + "$ref": "#/components/schemas/Result" } } } @@ -248,6 +189,201 @@ } } } + }, + "/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": { @@ -270,6 +406,68 @@ "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 8d5a0b3503..21585ec911 100644 --- a/fr.json +++ b/fr.json @@ -390,7 +390,8 @@ "group": "Recherche universelle", "icon": "globe", "pages": [ - "fr/api/universal-search/search" + "fr/api/universal-search/search", + "fr/api/universal-search/contents" ] }, { diff --git a/fr/api/introduction.mdx b/fr/api/introduction.mdx index 924844d2dd..b942187593 100644 --- a/fr/api/introduction.mdx +++ b/fr/api/introduction.mdx @@ -26,6 +26,7 @@ L'API REST (Representational State Transfer) de Mintlify vous permet d'interagir * [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. +* [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. 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/universal-search-openapi.json b/fr/universal-search-openapi.json index 6b6fdd6202..951432545e 100644 --- a/fr/universal-search-openapi.json +++ b/fr/universal-search-openapi.json @@ -139,66 +139,7 @@ "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": { - "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." - } - } + "$ref": "#/components/schemas/Result" } } } @@ -248,6 +189,201 @@ } } } + }, + "/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": { @@ -270,6 +406,68 @@ "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/universal-search-openapi.json b/universal-search-openapi.json index c5c4b9e340..f37681397e 100644 --- a/universal-search-openapi.json +++ b/universal-search-openapi.json @@ -139,66 +139,7 @@ "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": { - "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." - } - } + "$ref": "#/components/schemas/Result" } } } @@ -248,6 +189,201 @@ } } } + }, + "/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": { @@ -270,6 +406,68 @@ "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 0b0fb69971..51c958a8bb 100644 --- a/zh.json +++ b/zh.json @@ -385,7 +385,8 @@ "group": "通用搜索", "icon": "globe", "pages": [ - "zh/api/universal-search/search" + "zh/api/universal-search/search", + "zh/api/universal-search/contents" ] }, { diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index 87ea3adb04..cf43957f41 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -26,6 +26,7 @@ Mintlify 的 REST（Representational State Transfer）API 让你可以以编程 * [搜索文档](/zh/api/assistant/search)：搜索您的文档。 * [获取页面内容](/zh/api/assistant/get-page-content)：检索文档页面的完整文本内容。 * [通用搜索](/zh/api/universal-search/search)：使用单个查询同时搜索 Mintlify 托管的文档和网络内容。 +* [获取搜索结果的页面内容](/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)：获取按调用方类型划分的助手查询次数明细。 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/universal-search-openapi.json b/zh/universal-search-openapi.json index 974a65beee..bc161c9aa4 100644 --- a/zh/universal-search-openapi.json +++ b/zh/universal-search-openapi.json @@ -139,66 +139,7 @@ "type": "array", "description": "合并后的结果列表，按相关性排序。`source: \"mintlify\"` 的结果来自 Mintlify 托管的文档；`source: \"web\"` 的结果来自互联网。", "items": { - "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": "来源报告的发布日期（如果可用）。" - } - } + "$ref": "#/components/schemas/Result" } } } @@ -248,6 +189,201 @@ } } } + }, + "/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": { @@ -270,6 +406,68 @@ "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": "来源报告的发布日期（如果可用）。" + } + } } } } From 50a36ef5a57c4bb5ed60879f4797cf2d466fa5d9 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 15 Jul 2026 22:19:42 +0000 Subject: [PATCH 4/6] docs: document universal search context endpoint --- api/introduction.mdx | 1 + api/universal-search/context.mdx | 16 ++++ docs.json | 1 + es.json | 1 + es/api/introduction.mdx | 1 + es/api/universal-search/context.mdx | 16 ++++ es/universal-search-openapi.json | 138 ++++++++++++++++++++++++++++ fr.json | 1 + fr/api/introduction.mdx | 1 + fr/api/universal-search/context.mdx | 16 ++++ fr/universal-search-openapi.json | 138 ++++++++++++++++++++++++++++ universal-search-openapi.json | 138 ++++++++++++++++++++++++++++ zh.json | 1 + zh/api/introduction.mdx | 1 + zh/api/universal-search/context.mdx | 16 ++++ zh/universal-search-openapi.json | 138 ++++++++++++++++++++++++++++ 16 files changed, 624 insertions(+) create mode 100644 api/universal-search/context.mdx create mode 100644 es/api/universal-search/context.mdx create mode 100644 fr/api/universal-search/context.mdx create mode 100644 zh/api/universal-search/context.mdx diff --git a/api/introduction.mdx b/api/introduction.mdx index 50d01b13e1..7e2e3d145d 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -24,6 +24,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - [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. 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/docs.json b/docs.json index ee516594d5..5a30d08d6b 100644 --- a/docs.json +++ b/docs.json @@ -412,6 +412,7 @@ "icon": "globe", "pages": [ "api/universal-search/search", + "api/universal-search/context", "api/universal-search/contents" ] }, diff --git a/es.json b/es.json index 03f60fdfd7..e3f02bb9d5 100644 --- a/es.json +++ b/es.json @@ -391,6 +391,7 @@ "icon": "globe", "pages": [ "es/api/universal-search/search", + "es/api/universal-search/context", "es/api/universal-search/contents" ] }, diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index 1e22c735cc..ceb06e25d3 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -26,6 +26,7 @@ La REST (Representational State Transfer) API de Mintlify te permite interactuar * [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. 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/universal-search-openapi.json b/es/universal-search-openapi.json index 1ed0a1790e..33ee7189c2 100644 --- a/es/universal-search-openapi.json +++ b/es/universal-search-openapi.json @@ -190,6 +190,144 @@ } } }, + "/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", diff --git a/fr.json b/fr.json index 21585ec911..0cac26bd38 100644 --- a/fr.json +++ b/fr.json @@ -391,6 +391,7 @@ "icon": "globe", "pages": [ "fr/api/universal-search/search", + "fr/api/universal-search/context", "fr/api/universal-search/contents" ] }, diff --git a/fr/api/introduction.mdx b/fr/api/introduction.mdx index b942187593..d762522538 100644 --- a/fr/api/introduction.mdx +++ b/fr/api/introduction.mdx @@ -26,6 +26,7 @@ L'API REST (Representational State Transfer) de Mintlify vous permet d'interagir * [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. 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/universal-search-openapi.json b/fr/universal-search-openapi.json index 951432545e..d1cd426a51 100644 --- a/fr/universal-search-openapi.json +++ b/fr/universal-search-openapi.json @@ -190,6 +190,144 @@ } } }, + "/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", diff --git a/universal-search-openapi.json b/universal-search-openapi.json index f37681397e..d695d31946 100644 --- a/universal-search-openapi.json +++ b/universal-search-openapi.json @@ -190,6 +190,144 @@ } } }, + "/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", diff --git a/zh.json b/zh.json index 51c958a8bb..5d67b90647 100644 --- a/zh.json +++ b/zh.json @@ -386,6 +386,7 @@ "icon": "globe", "pages": [ "zh/api/universal-search/search", + "zh/api/universal-search/context", "zh/api/universal-search/contents" ] }, diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index cf43957f41..9416171f2d 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -26,6 +26,7 @@ Mintlify 的 REST（Representational State Transfer）API 让你可以以编程 * [搜索文档](/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 助手的会话历史。 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/universal-search-openapi.json b/zh/universal-search-openapi.json index bc161c9aa4..5227cab1a8 100644 --- a/zh/universal-search-openapi.json +++ b/zh/universal-search-openapi.json @@ -190,6 +190,144 @@ } } }, + "/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 获取页面内容", From c149804e074d3d4a6cab9ea3c77c6f6f06d058db Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 22:04:24 +0000 Subject: [PATCH 5/6] docs: document universal search MCP endpoint and result truncation fields --- api/introduction.mdx | 1 + api/universal-search/mcp.mdx | 73 +++++++++++++++++++++++++++ docs.json | 3 +- es.json | 3 +- es/api/introduction.mdx | 1 + es/api/universal-search/mcp.mdx | 85 ++++++++++++++++++++++++++++++++ es/universal-search-openapi.json | 13 +++++ fr.json | 3 +- fr/api/introduction.mdx | 1 + fr/api/universal-search/mcp.mdx | 85 ++++++++++++++++++++++++++++++++ fr/universal-search-openapi.json | 13 +++++ universal-search-openapi.json | 13 +++++ zh.json | 3 +- zh/api/introduction.mdx | 1 + zh/api/universal-search/mcp.mdx | 85 ++++++++++++++++++++++++++++++++ zh/universal-search-openapi.json | 13 +++++ 16 files changed, 392 insertions(+), 4 deletions(-) create mode 100644 api/universal-search/mcp.mdx create mode 100644 es/api/universal-search/mcp.mdx create mode 100644 fr/api/universal-search/mcp.mdx create mode 100644 zh/api/universal-search/mcp.mdx diff --git a/api/introduction.mdx b/api/introduction.mdx index 7e2e3d145d..922c8348d5 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -26,6 +26,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - [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. +- [MCP server](/api/universal-search/mcp): Expose universal search as tools to Claude Code and other Model Context Protocol clients. - [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. diff --git a/api/universal-search/mcp.mdx b/api/universal-search/mcp.mdx new file mode 100644 index 0000000000..2891db50cb --- /dev/null +++ b/api/universal-search/mcp.mdx @@ -0,0 +1,73 @@ +--- +title: "MCP server" +description: "Connect Claude Code and other MCP clients to Universal Search over a single streamable HTTP endpoint that exposes search, context, and contents as tools." +keywords: ["MCP", "Model Context Protocol", "Claude Code", "universal search"] +--- + +The Universal Search MCP server exposes the same `search`, `context`, and `contents` operations as the REST API through the [Model Context Protocol](https://modelcontextprotocol.io/), so agents like Claude Code can call them as tools without stitching together HTTP requests. + +## Endpoint + +``` +POST https://api.mintlify.com/universal-search/v1/mcp +``` + +The server implements the streamable HTTP transport and is stateless — send one JSON-RPC request per POST. `GET` and `DELETE` are also accepted by the transport; JSON-RPC batching is rejected with a `-32600` error. + +## Authentication + +Authenticate with the same universal search API key you use for the REST API. Pass it as a bearer token on every request: + +```http +Authorization: Bearer YOUR_UNIVERSAL_SEARCH_API_KEY +``` + +See [API keys](/api/introduction#api-keys) for how to create one. Access requires the Universal Search entitlement. + +## Tools + +The server registers three read-only tools. Each tool's input and output schemas mirror the REST endpoints, so the same request and response shapes apply. + + + Find documentation pages across Mintlify-hosted sites and the web. Each result carries the section that matched the query. Results include a `truncated` flag — when `false`, the returned text is the complete matched section and no follow-up call is needed. Mintlify results also report `totalCharacters` so agents can size follow-up requests. Body text is included by default and truncated to 2,000 characters per result; pass `text: false` for titles and URLs only, or `text: { maxCharacters: n }` to change the limit. + + + + Assemble a token-budgeted answer from several ranked sources at once. Prefer this over `search` for "how do I build X" questions — it usually needs no follow-up call. Returns a plain-text or JSON payload ready to hand to an LLM. + + + + Read the full page behind a URL or document ID returned by `search` or `context`. Only needed when a search result reported `truncated: true`. Pass `query` alongside `maxCharacters` to return the sections that match `query` instead of truncating from the top of the page — this is what makes a single hydration call enough on large reference pages. + + Input differs slightly from the REST endpoint: pass an `items` array of `{ type: "url", url }` or `{ type: "id", id }` objects (up to 20) instead of separate `urls` and `ids` arrays. + + +## Connect Claude Code + +Add the server to your Claude Code MCP configuration: + +```json +{ + "mcpServers": { + "mintlify-universal-search": { + "type": "http", + "url": "https://api.mintlify.com/universal-search/v1/mcp", + "headers": { + "Authorization": "Bearer ${MINTLIFY_UNIVERSAL_SEARCH_API_KEY}" + } + } + } +} +``` + +Set `MINTLIFY_UNIVERSAL_SEARCH_API_KEY` in your environment before starting Claude Code. + +## Rate limits + +The MCP endpoint enforces burst and hourly rate limits per client IP address. If you hit the limit, the server returns `429 Too Many Requests` — back off and retry. + +## Errors + +- `405 Method Not Allowed`: The request used an HTTP method other than `POST`, `GET`, or `DELETE`. +- `400 Bad Request` with JSON-RPC error `-32600`: The request body was a JSON-RPC batch. Send one request per POST. +- Tool-level failures: The tool response has `isError: true` and a `content` entry describing what failed. The HTTP status stays `200` so the MCP client can surface the error to the agent. diff --git a/docs.json b/docs.json index 5a30d08d6b..07ad26dd33 100644 --- a/docs.json +++ b/docs.json @@ -413,7 +413,8 @@ "pages": [ "api/universal-search/search", "api/universal-search/context", - "api/universal-search/contents" + "api/universal-search/contents", + "api/universal-search/mcp" ] }, { diff --git a/es.json b/es.json index e3f02bb9d5..2fbf8289d1 100644 --- a/es.json +++ b/es.json @@ -392,7 +392,8 @@ "pages": [ "es/api/universal-search/search", "es/api/universal-search/context", - "es/api/universal-search/contents" + "es/api/universal-search/contents", + "es/api/universal-search/mcp" ] }, { diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index ceb06e25d3..b41c6ba01a 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -28,6 +28,7 @@ La REST (Representational State Transfer) API de Mintlify te permite interactuar * [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. +* [MCP server](/es/api/universal-search/mcp): Expón la búsqueda universal como herramientas a Claude Code y otros clientes MCP a través de un único endpoint HTTP en streaming. * [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. diff --git a/es/api/universal-search/mcp.mdx b/es/api/universal-search/mcp.mdx new file mode 100644 index 0000000000..2197207e22 --- /dev/null +++ b/es/api/universal-search/mcp.mdx @@ -0,0 +1,85 @@ +--- +title: "Servidor MCP" +description: "Conecta Claude Code y otros clientes MCP con la búsqueda universal a través de un único endpoint HTTP en streaming que expone la búsqueda, el contexto y los contenidos como herramientas." +keywords: ["MCP", "Model Context Protocol", "Claude Code", "búsqueda universal"] +--- + +El servidor MCP de la búsqueda universal expone las mismas operaciones `search`, `context` y `contents` que la API REST a través del [Model Context Protocol](https://modelcontextprotocol.io/), para que agentes como Claude Code puedan llamarlas como herramientas sin tener que encadenar peticiones HTTP. + +
+## Endpoint +
+ +``` +POST https://api.mintlify.com/universal-search/v1/mcp +``` + +El servidor implementa el transporte HTTP en streaming y no mantiene estado: envía una única petición JSON-RPC por POST. El transporte también acepta `GET` y `DELETE`; el uso de lotes JSON-RPC se rechaza con un error `-32600`. + +
+## Autenticación +
+ +Autentícate con la misma clave API de búsqueda universal que usas para la API REST. Pásala como bearer token en cada petición: + +```http +Authorization: Bearer YOUR_UNIVERSAL_SEARCH_API_KEY +``` + +Consulta [claves API](/es/api/introduction#api-keys) para saber cómo crear una. El acceso requiere el permiso Universal Search. + +
+## Herramientas +
+ +El servidor registra tres herramientas de solo lectura. Los esquemas de entrada y salida de cada herramienta reflejan los endpoints REST, por lo que se aplican las mismas formas de petición y respuesta. + + + Encuentra páginas de documentación en sitios alojados en Mintlify y en la web. Cada resultado incluye la sección que coincidió con la consulta. Los resultados incluyen una marca `truncated`: cuando es `false`, el texto devuelto es la sección coincidente completa y no hace falta una llamada de seguimiento. Los resultados de Mintlify también informan de `totalCharacters` para que los agentes puedan dimensionar las peticiones de seguimiento. El texto del cuerpo se incluye por defecto y se trunca a 2.000 caracteres por resultado; pasa `text: false` para obtener solo los títulos y las URLs, o `text: { maxCharacters: n }` para cambiar el límite. + + + + Compone una respuesta ajustada a un presupuesto de tokens a partir de varias fuentes ordenadas por relevancia a la vez. Prefiere esta herramienta a `search` para preguntas del tipo «cómo hago X»: normalmente no requiere una llamada de seguimiento. Devuelve un payload en texto plano o JSON listo para entregar a un LLM. + + + + Lee la página completa detrás de una URL o de un ID de documento devuelto por `search` o `context`. Solo hace falta cuando un resultado de búsqueda indica `truncated: true`. Pasa `query` junto con `maxCharacters` para obtener las secciones que coinciden con `query` en lugar de truncar desde el principio de la página: esto es lo que hace que una única llamada de hidratación sea suficiente en páginas de referencia grandes. + + La entrada difiere ligeramente de la del endpoint REST: pasa un array `items` con objetos `{ type: "url", url }` o `{ type: "id", id }` (hasta 20) en lugar de arrays `urls` e `ids` separados. + + +
+## Conectar Claude Code +
+ +Añade el servidor a tu configuración MCP de Claude Code: + +```json +{ + "mcpServers": { + "mintlify-universal-search": { + "type": "http", + "url": "https://api.mintlify.com/universal-search/v1/mcp", + "headers": { + "Authorization": "Bearer ${MINTLIFY_UNIVERSAL_SEARCH_API_KEY}" + } + } + } +} +``` + +Define `MINTLIFY_UNIVERSAL_SEARCH_API_KEY` en tu entorno antes de iniciar Claude Code. + +
+## Límites de tasa +
+ +El endpoint MCP aplica límites de tasa por ráfaga y por hora según la dirección IP del cliente. Si alcanzas el límite, el servidor devuelve `429 Too Many Requests`: espera un momento y vuelve a intentarlo. + +
+## Errores +
+ +- `405 Method Not Allowed`: La petición usó un método HTTP distinto de `POST`, `GET` o `DELETE`. +- `400 Bad Request` con error JSON-RPC `-32600`: El cuerpo de la petición era un lote JSON-RPC. Envía una única petición por POST. +- Errores a nivel de herramienta: La respuesta de la herramienta tiene `isError: true` y una entrada `content` que describe qué falló. El estado HTTP se mantiene en `200` para que el cliente MCP pueda mostrar el error al agente. diff --git a/es/universal-search-openapi.json b/es/universal-search-openapi.json index 33ee7189c2..e0aaedfdd2 100644 --- a/es/universal-search-openapi.json +++ b/es/universal-search-openapi.json @@ -363,6 +363,10 @@ "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." + }, + "query": { + "type": "string", + "description": "Lo que estás buscando en la página. Cuando se establece junto con `maxCharacters`, el endpoint devuelve las secciones que mejor coinciden con `query` en lugar de truncar desde el principio. Recomendado para páginas de referencia grandes." } } }, @@ -576,6 +580,15 @@ "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`." }, + "truncated": { + "type": "boolean", + "description": "Indica si `text` se truncó para ajustarse a `text.maxCharacters`. Cuando es `false`, `text` contiene la sección coincidente completa y llamar a `/contents` para este resultado no devuelve contenido nuevo. Solo está presente cuando el texto del cuerpo se incluye en la respuesta." + }, + "totalCharacters": { + "type": "integer", + "minimum": 0, + "description": "La longitud total en caracteres del contenido subyacente de la página, antes de cualquier truncado. Solo está presente para los resultados de `mintlify`; los proveedores web limitan el texto antes de que Mintlify lo vea." + }, "score": { "type": "number", "description": "La puntuación de relevancia de este resultado." diff --git a/fr.json b/fr.json index 0cac26bd38..6056c68893 100644 --- a/fr.json +++ b/fr.json @@ -392,7 +392,8 @@ "pages": [ "fr/api/universal-search/search", "fr/api/universal-search/context", - "fr/api/universal-search/contents" + "fr/api/universal-search/contents", + "fr/api/universal-search/mcp" ] }, { diff --git a/fr/api/introduction.mdx b/fr/api/introduction.mdx index d762522538..454aecffb6 100644 --- a/fr/api/introduction.mdx +++ b/fr/api/introduction.mdx @@ -28,6 +28,7 @@ L'API REST (Representational State Transfer) de Mintlify vous permet d'interagir * [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. +* [MCP server](/fr/api/universal-search/mcp): Exposez la recherche universelle sous forme d'outils à Claude Code et à d'autres clients MCP via un seul endpoint HTTP streamable. * [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. diff --git a/fr/api/universal-search/mcp.mdx b/fr/api/universal-search/mcp.mdx new file mode 100644 index 0000000000..5b923884e5 --- /dev/null +++ b/fr/api/universal-search/mcp.mdx @@ -0,0 +1,85 @@ +--- +title: "Serveur MCP" +description: "Connectez Claude Code et d'autres clients MCP à la recherche universelle via un seul endpoint HTTP streamable qui expose la recherche, le contexte et le contenu sous forme d'outils." +keywords: ["MCP", "Model Context Protocol", "Claude Code", "recherche universelle"] +--- + +Le serveur MCP de recherche universelle expose les mêmes opérations `search`, `context` et `contents` que l'API REST via le [Model Context Protocol](https://modelcontextprotocol.io/), afin que des agents comme Claude Code puissent les appeler comme des outils sans avoir à assembler eux-mêmes des requêtes HTTP. + +
+## Endpoint +
+ +``` +POST https://api.mintlify.com/universal-search/v1/mcp +``` + +Le serveur implémente le transport HTTP streamable et est sans état — envoyez une seule requête JSON-RPC par POST. `GET` et `DELETE` sont également acceptés par le transport ; le batching JSON-RPC est rejeté avec une erreur `-32600`. + +
+## Authentification +
+ +Authentifiez-vous avec la même clé API de recherche universelle que celle utilisée pour l'API REST. Passez-la comme token bearer sur chaque requête : + +```http +Authorization: Bearer YOUR_UNIVERSAL_SEARCH_API_KEY +``` + +Consultez [Clés API](/fr/api/introduction#api-keys) pour savoir comment en créer une. L'accès nécessite l'entitlement Universal Search. + +
+## Outils +
+ +Le serveur enregistre trois outils en lecture seule. Les schémas d'entrée et de sortie de chaque outil reprennent ceux des endpoints REST, si bien que les mêmes formes de requête et de réponse s'appliquent. + + + Trouvez des pages de documentation à travers les sites hébergés par Mintlify et le web. Chaque résultat contient la section qui correspond à la requête. Les résultats incluent un indicateur `truncated` — lorsqu'il vaut `false`, le texte renvoyé est la section correspondante complète et aucun appel supplémentaire n'est nécessaire. Les résultats Mintlify indiquent également `totalCharacters` afin que les agents puissent dimensionner les requêtes de suivi. Le texte du corps est inclus par défaut et tronqué à 2 000 caractères par résultat ; passez `text: false` pour n'obtenir que les titres et les URL, ou `text: { maxCharacters: n }` pour modifier la limite. + + + + Assemblez une réponse calibrée en jetons à partir de plusieurs sources classées en une seule fois. Préférez cet outil à `search` pour les questions du type « comment construire X » — il ne nécessite généralement aucun appel de suivi. Renvoie une charge utile en texte brut ou en JSON prête à être transmise à un LLM. + + + + Lisez la page complète derrière une URL ou un ID de document renvoyé par `search` ou `context`. Nécessaire uniquement lorsqu'un résultat de recherche indique `truncated: true`. Passez `query` en même temps que `maxCharacters` pour renvoyer les sections qui correspondent à `query` au lieu de tronquer depuis le haut de la page — c'est ce qui permet qu'un seul appel d'hydratation suffise sur les pages de référence volumineuses. + + L'entrée diffère légèrement de l'endpoint REST : passez un tableau `items` d'objets `{ type: "url", url }` ou `{ type: "id", id }` (jusqu'à 20) au lieu de tableaux `urls` et `ids` séparés. + + +
+## Connecter Claude Code +
+ +Ajoutez le serveur à votre configuration MCP de Claude Code : + +```json +{ + "mcpServers": { + "mintlify-universal-search": { + "type": "http", + "url": "https://api.mintlify.com/universal-search/v1/mcp", + "headers": { + "Authorization": "Bearer ${MINTLIFY_UNIVERSAL_SEARCH_API_KEY}" + } + } + } +} +``` + +Définissez `MINTLIFY_UNIVERSAL_SEARCH_API_KEY` dans votre environnement avant de démarrer Claude Code. + +
+## Limites de débit +
+ +L'endpoint MCP applique des limites de débit en rafale et horaires par adresse IP client. Si vous atteignez la limite, le serveur renvoie `429 Too Many Requests` — patientez avant de réessayer. + +
+## Erreurs +
+ +- `405 Method Not Allowed` : la requête a utilisé une méthode HTTP autre que `POST`, `GET` ou `DELETE`. +- `400 Bad Request` avec l'erreur JSON-RPC `-32600` : le corps de la requête était un batch JSON-RPC. Envoyez une seule requête par POST. +- Échecs au niveau de l'outil : la réponse de l'outil contient `isError: true` et une entrée `content` décrivant ce qui a échoué. Le statut HTTP reste `200` afin que le client MCP puisse remonter l'erreur à l'agent. diff --git a/fr/universal-search-openapi.json b/fr/universal-search-openapi.json index d1cd426a51..45475f6699 100644 --- a/fr/universal-search-openapi.json +++ b/fr/universal-search-openapi.json @@ -363,6 +363,10 @@ "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." + }, + "query": { + "type": "string", + "description": "Ce que vous recherchez sur la page. Lorsqu'il est défini en même temps que `maxCharacters`, l'endpoint renvoie les sections qui correspondent le mieux à `query` au lieu de tronquer depuis le haut. Recommandé pour les pages de référence volumineuses." } } }, @@ -576,6 +580,15 @@ "type": "string", "description": "Le contenu de la page. Vide lorsque `text` est omis ou défini sur `false`. Tronqué lorsque `text.maxCharacters` est fourni." }, + "truncated": { + "type": "boolean", + "description": "Indique si `text` a été tronqué pour tenir dans `text.maxCharacters`. Lorsqu'il vaut `false`, `text` contient la section correspondante complète et appeler `/contents` pour ce résultat ne renvoie aucun nouveau contenu. Présent uniquement lorsque le texte du corps est inclus dans la réponse." + }, + "totalCharacters": { + "type": "integer", + "minimum": 0, + "description": "La longueur totale en caractères du contenu sous-jacent de la page, avant toute troncature. Présent uniquement pour les résultats `mintlify` ; les fournisseurs web plafonnent le texte avant que Mintlify ne le voie." + }, "score": { "type": "number", "description": "Le score de pertinence de ce résultat." diff --git a/universal-search-openapi.json b/universal-search-openapi.json index d695d31946..a98bf79017 100644 --- a/universal-search-openapi.json +++ b/universal-search-openapi.json @@ -363,6 +363,10 @@ "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." + }, + "query": { + "type": "string", + "description": "What you are looking for on the page. When set together with `maxCharacters`, the endpoint returns the sections that best match `query` instead of truncating from the top. Recommended for large reference pages." } } }, @@ -576,6 +580,15 @@ "type": "string", "description": "The page content. Empty when `text` was omitted or set to `false`. Truncated when `text.maxCharacters` was provided." }, + "truncated": { + "type": "boolean", + "description": "Whether `text` was truncated to fit `text.maxCharacters`. When `false`, `text` contains the complete matched section and calling `/contents` for this result returns no new content. Only present when body text is included in the response." + }, + "totalCharacters": { + "type": "integer", + "minimum": 0, + "description": "The total character length of the underlying page content, before any truncation. Only present for `mintlify` results; web providers cap text before Mintlify sees it." + }, "score": { "type": "number", "description": "The relevance score for this result." diff --git a/zh.json b/zh.json index 5d67b90647..272dfaa805 100644 --- a/zh.json +++ b/zh.json @@ -387,7 +387,8 @@ "pages": [ "zh/api/universal-search/search", "zh/api/universal-search/context", - "zh/api/universal-search/contents" + "zh/api/universal-search/contents", + "zh/api/universal-search/mcp" ] }, { diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index 9416171f2d..a1b9e19a98 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -28,6 +28,7 @@ Mintlify 的 REST（Representational State Transfer）API 让你可以以编程 * [通用搜索](/zh/api/universal-search/search)：使用单个查询同时搜索 Mintlify 托管的文档和网络内容。 * [为 RAG 组装上下文负载](/zh/api/universal-search/context)：为检索增强生成流水线组装符合 token 预算的上下文负载。 * [获取搜索结果的页面内容](/zh/api/universal-search/contents)：检索通用搜索返回页面的完整 Markdown。 +* [MCP 服务器](/zh/api/universal-search/mcp)：通过 Model Context Protocol 将通用搜索作为工具暴露给 Claude Code 和其他 MCP 客户端。 * [获取用户反馈](/zh/api/analytics/feedback)：从您的文档中导出用户反馈。 * [获取 AI 助手会话](/zh/api/analytics/assistant-conversations)：导出 AI 助手的会话历史。 * [Get assistant caller stats](/zh/api/analytics/assistant-caller-stats)：获取按调用方类型划分的助手查询次数明细。 diff --git a/zh/api/universal-search/mcp.mdx b/zh/api/universal-search/mcp.mdx new file mode 100644 index 0000000000..90bdc647ab --- /dev/null +++ b/zh/api/universal-search/mcp.mdx @@ -0,0 +1,85 @@ +--- +title: "MCP 服务器" +description: "通过单个流式 HTTP 端点将 Claude Code 和其他 MCP 客户端连接到通用搜索，将 search、context 和 contents 作为工具暴露出来。" +keywords: ["MCP", "Model Context Protocol", "Claude Code", "通用搜索"] +--- + +通用搜索 MCP 服务器通过 [Model Context Protocol](https://modelcontextprotocol.io/) 暴露与 REST API 相同的 `search`、`context` 和 `contents` 操作，因此像 Claude Code 这样的代理可以将它们作为工具调用，而无需自行拼接 HTTP 请求。 + +
+## 端点 +
+ +``` +POST https://api.mintlify.com/universal-search/v1/mcp +``` + +该服务器实现了流式 HTTP 传输，且为无状态——每个 POST 只发送一个 JSON-RPC 请求。传输层也接受 `GET` 和 `DELETE`；JSON-RPC 批处理会以 `-32600` 错误被拒绝。 + +
+## 身份验证 +
+ +使用与 REST API 相同的通用搜索 API 密钥进行身份验证。在每个请求中将其作为 bearer token 传递： + +```http +Authorization: Bearer YOUR_UNIVERSAL_SEARCH_API_KEY +``` + +有关如何创建密钥，请参阅 [API 密钥](/zh/api/introduction#api-keys)。访问需要 Universal Search 权限。 + +
+## 工具 +
+ +该服务器注册了三个只读工具。每个工具的输入和输出模式都与 REST 端点保持一致，因此请求和响应结构相同。 + + + 在 Mintlify 托管的站点和网络中查找文档页面。每个结果都包含匹配查询的部分。结果中包含 `truncated` 标记——当其为 `false` 时，返回的文本即为完整匹配部分，无需再次调用。Mintlify 结果还会报告 `totalCharacters`，以便代理确定后续请求的大小。默认包含正文文本，并被截断为每个结果 2,000 个字符；传入 `text: false` 可仅返回标题和 URL，或传入 `text: { maxCharacters: n }` 以调整上限。 + + + + 一次性从多个排序过的来源组装出符合 token 预算的答案。对于"我该如何构建 X"这类问题，请优先选择此工具而非 `search`——通常无需再次调用。返回可直接交给 LLM 使用的纯文本或 JSON 负载。 + + + + 读取 `search` 或 `context` 返回的 URL 或文档 ID 背后的完整页面。仅在搜索结果报告 `truncated: true` 时才需要。将 `query` 与 `maxCharacters` 一起传递，即可返回匹配 `query` 的部分，而非从页面顶部截断——这正是在大型参考页面上一次补齐调用就够用的关键。 + + 输入与 REST 端点略有不同：传递 `items` 数组，包含 `{ type: "url", url }` 或 `{ type: "id", id }` 对象（最多 20 个），而不是分开的 `urls` 和 `ids` 数组。 + + +
+## 连接 Claude Code +
+ +将该服务器添加到你的 Claude Code MCP 配置中： + +```json +{ + "mcpServers": { + "mintlify-universal-search": { + "type": "http", + "url": "https://api.mintlify.com/universal-search/v1/mcp", + "headers": { + "Authorization": "Bearer ${MINTLIFY_UNIVERSAL_SEARCH_API_KEY}" + } + } + } +} +``` + +在启动 Claude Code 之前，请在你的环境中设置 `MINTLIFY_UNIVERSAL_SEARCH_API_KEY`。 + +
+## 速率限制 +
+ +MCP 端点对每个客户端 IP 地址实施突发和每小时速率限制。如果你达到上限，服务器会返回 `429 Too Many Requests`——请退避后重试。 + +
+## 错误 +
+ +- `405 Method Not Allowed`：请求使用了 `POST`、`GET` 或 `DELETE` 之外的 HTTP 方法。 +- `400 Bad Request` 且 JSON-RPC 错误为 `-32600`：请求体是 JSON-RPC 批处理。请每个 POST 只发送一个请求。 +- 工具级失败：工具响应中包含 `isError: true` 以及描述失败原因的 `content` 条目。HTTP 状态保持为 `200`，以便 MCP 客户端将错误呈现给代理。 diff --git a/zh/universal-search-openapi.json b/zh/universal-search-openapi.json index 5227cab1a8..0de5aee289 100644 --- a/zh/universal-search-openapi.json +++ b/zh/universal-search-openapi.json @@ -363,6 +363,10 @@ "type": "integer", "minimum": 1, "description": "每个结果返回的页面内容的最大字符数。截断会闭合未关闭的代码块，保持 Markdown 有效。" + }, + "query": { + "type": "string", + "description": "你在页面上要查找的内容。当与 `maxCharacters` 一起设置时，端点会返回最匹配 `query` 的部分，而不是从顶部截断。推荐用于大型参考页面。" } } }, @@ -576,6 +580,15 @@ "type": "string", "description": "页面内容。当 `text` 被省略或设置为 `false` 时为空。当提供 `text.maxCharacters` 时会被截断。" }, + "truncated": { + "type": "boolean", + "description": "`text` 是否被截断以满足 `text.maxCharacters`。当为 `false` 时，`text` 包含完整的匹配部分，针对该结果调用 `/contents` 不会返回新内容。仅在响应中包含正文文本时出现。" + }, + "totalCharacters": { + "type": "integer", + "minimum": 0, + "description": "底层页面内容在任何截断之前的总字符长度。仅对 `mintlify` 结果出现；网络提供商在 Mintlify 收到内容之前就已对文本进行了截断。" + }, "score": { "type": "number", "description": "此结果的相关性得分。" From 3a74d423014fc450eced143ed084a98ffdc11d3b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 22:06:34 +0000 Subject: [PATCH 6/6] docs: sharpen MCP page title and trim description for SEO --- api/universal-search/mcp.mdx | 4 ++-- es/api/universal-search/mcp.mdx | 4 ++-- fr/api/universal-search/mcp.mdx | 4 ++-- zh/api/universal-search/mcp.mdx | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/api/universal-search/mcp.mdx b/api/universal-search/mcp.mdx index 2891db50cb..b069b41132 100644 --- a/api/universal-search/mcp.mdx +++ b/api/universal-search/mcp.mdx @@ -1,6 +1,6 @@ --- -title: "MCP server" -description: "Connect Claude Code and other MCP clients to Universal Search over a single streamable HTTP endpoint that exposes search, context, and contents as tools." +title: "Universal Search MCP server" +description: "Connect Claude Code and other MCP clients to Universal Search over a streamable HTTP endpoint exposing search, context, and contents tools." keywords: ["MCP", "Model Context Protocol", "Claude Code", "universal search"] --- diff --git a/es/api/universal-search/mcp.mdx b/es/api/universal-search/mcp.mdx index 2197207e22..3d9ebf1645 100644 --- a/es/api/universal-search/mcp.mdx +++ b/es/api/universal-search/mcp.mdx @@ -1,6 +1,6 @@ --- -title: "Servidor MCP" -description: "Conecta Claude Code y otros clientes MCP con la búsqueda universal a través de un único endpoint HTTP en streaming que expone la búsqueda, el contexto y los contenidos como herramientas." +title: "Servidor MCP de búsqueda universal" +description: "Conecta Claude Code y otros clientes MCP con la búsqueda universal mediante un endpoint HTTP en streaming que expone las herramientas search, context y contents." keywords: ["MCP", "Model Context Protocol", "Claude Code", "búsqueda universal"] --- diff --git a/fr/api/universal-search/mcp.mdx b/fr/api/universal-search/mcp.mdx index 5b923884e5..d540b8f6ae 100644 --- a/fr/api/universal-search/mcp.mdx +++ b/fr/api/universal-search/mcp.mdx @@ -1,6 +1,6 @@ --- -title: "Serveur MCP" -description: "Connectez Claude Code et d'autres clients MCP à la recherche universelle via un seul endpoint HTTP streamable qui expose la recherche, le contexte et le contenu sous forme d'outils." +title: "Serveur MCP de recherche universelle" +description: "Connectez Claude Code et d'autres clients MCP à la recherche universelle via un endpoint HTTP streamable exposant les outils search, context et contents." keywords: ["MCP", "Model Context Protocol", "Claude Code", "recherche universelle"] --- diff --git a/zh/api/universal-search/mcp.mdx b/zh/api/universal-search/mcp.mdx index 90bdc647ab..86a7bedc72 100644 --- a/zh/api/universal-search/mcp.mdx +++ b/zh/api/universal-search/mcp.mdx @@ -1,6 +1,6 @@ --- -title: "MCP 服务器" -description: "通过单个流式 HTTP 端点将 Claude Code 和其他 MCP 客户端连接到通用搜索，将 search、context 和 contents 作为工具暴露出来。" +title: "通用搜索 MCP 服务器" +description: "通过流式 HTTP 端点将 Claude Code 和其他 MCP 客户端连接到通用搜索，端点将 search、context 和 contents 作为工具暴露出来。" keywords: ["MCP", "Model Context Protocol", "Claude Code", "通用搜索"] ---