mintlify · mintlify · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026
diff --git a/api/introduction.mdx b/api/introduction.mdx
@@ -23,6 +23,10 @@ The Mintlify REST (Representational State Transfer) API enables you to programma
 - [Create assistant message](/api/assistant/create-assistant-message-v2): Embed the assistant, trained on your docs, into any application of your choosing.
 - [Search documentation](/api/assistant/search): Search through your documentation.
 - [Get page content](/api/assistant/get-page-content): Retrieve the full text content of a documentation page.
+- [Universal search](/api/universal-search/search): Search across Mintlify-hosted documentation and the wider web with a single query.
+- [Assemble a context payload for RAG](/api/universal-search/context): Assemble a token-budgeted retrieval-augmented generation context payload.
+- [Fetch page content for search results](/api/universal-search/contents): Retrieve the stitched Markdown for pages returned by universal search.
+- [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.
@@ -47,12 +51,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 +101,9 @@ Assistant API keys begin with the `mint_dsc_` prefix.
 <Note>
   Calls using the assistant API token can incur costs: either using your assistant credits or incurring overages.
 </Note>
+
+### Universal search API key
+
+Use the universal search API key for the [Universal search](/api/universal-search/search) endpoint.
+
+Universal search is a paid add-on. [Contact sales](https://mintlify.com/enterprise) to enable the Universal Search entitlement for your organization before generating a key.
diff --git a/api/universal-search/contents.mdx b/api/universal-search/contents.mdx
@@ -0,0 +1,20 @@
+---
+title: "Fetch page content for search results"
+openapi: "/universal-search-openapi.json POST /contents"
+keywords: ["contents", "page content", "universal search"]
+---
+
+Use this endpoint after [Search across documentation and the web](/api/universal-search/search) when you want the full stitched Markdown for specific pages without repeating the query. Pass the `id` returned from a previous search, the canonical URL of a Mintlify-hosted page, or a mix of both.
+
+A single request can reference at most 20 items across `urls` and `ids` combined. When you provide `maxCharacters`, each page is truncated to that length while keeping the Markdown valid (open code fences are closed).
+
+## Partial success
+
+The response always returns `200` when the request body is well-formed. Inspect the `statuses` array to see which inputs resolved successfully and which failed. `results` only contains the pages whose status is `success`.
+
+Error `tag` values:
+
+- `not_found`: The URL or ID did not match any indexed page.
+- `not_synced`: The source deployment has not been indexed for universal search.
+- `invalid_id`: The ID was malformed.
+- `fetch_error`: The lookup failed unexpectedly. Retry the request or contact support with the `requestId`.
diff --git a/api/universal-search/context.mdx b/api/universal-search/context.mdx
@@ -0,0 +1,16 @@
+---
+title: "Assemble a context payload for RAG"
+openapi: "/universal-search-openapi.json POST /context"
+keywords: ["context", "RAG", "retrieval", "universal search"]
+---
+
+Use this endpoint to build a ready-to-use context payload for a retrieval-augmented generation (RAG) pipeline. It runs a ranked universal search behind the scenes, deduplicates and truncates snippets so each page contributes a fair share, and returns a token-budgeted result you can hand directly to an LLM.
+
+Choose the shape of the payload with `format`:
+
+- `txt`: A single plain-text string with source URLs interleaved. Best for passing straight into a prompt.
+- `json`: A JSON-encoded string of the form `{"results":[...]}` with one entry per snippet. Best when your application needs to render or attribute individual sources.
+
+Set `product` to bias retrieval toward a specific product or subject when the same query could match multiple domains.
+
+The response caps `outputTokens` at 10,000 and reports `resultsCount` so you can see how many snippets were included after the budget was applied.
diff --git a/api/universal-search/mcp.mdx b/api/universal-search/mcp.mdx
@@ -0,0 +1,73 @@
+---
+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"]
+---
+
+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.
+
+<Card title="search" icon="magnifying-glass" href="/api/universal-search/search">
+  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.
+</Card>
+
+<Card title="context" icon="layer-group" href="/api/universal-search/context">
+  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.
+</Card>
+
+<Card title="contents" icon="file-lines" href="/api/universal-search/contents">
+  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.
+</Card>
+
+## 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/api/universal-search/search.mdx b/api/universal-search/search.mdx
@@ -0,0 +1,15 @@
+---
+title: "Search across documentation and the web"
+openapi: "/universal-search-openapi.json POST /search"
+keywords: ["search", "universal search", "web search"]
+---
+
+Universal search runs a single query against Mintlify-hosted documentation and the wider web, then returns a merged, ranked list of results. Use it to power in-product search experiences, agent tools, or retrieval pipelines that need to reach beyond a single deployment.
+
+Universal search requires the Universal Search entitlement. [Contact sales](https://mintlify.com/enterprise) to enable it for your organization.
+
+## Authentication
+
+Authenticate with a universal search API key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard.
+
+Universal search API keys are separate from admin and assistant API keys and are only accepted at `/universal-search/v1` endpoints.
diff --git a/docs.json b/docs.json
@@ -407,6 +407,16 @@
                   "api/assistant/get-page-content"
                 ]
               },
+              {
+                "group": "Universal search",
+                "icon": "globe",
+                "pages": [
+                  "api/universal-search/search",
+                  "api/universal-search/context",
+                  "api/universal-search/contents",
+                  "api/universal-search/mcp"
+                ]
+              },
               {
                 "group": "Analytics",
                 "icon": "chart-line",

diff --git a/es.json b/es.json
@@ -386,6 +386,16 @@
             "es/api/assistant/get-page-content"
           ]
         },
+        {
+          "group": "Búsqueda universal",
+          "icon": "globe",
+          "pages": [
+            "es/api/universal-search/search",
+            "es/api/universal-search/context",
+            "es/api/universal-search/contents",
+            "es/api/universal-search/mcp"
+          ]
+        },
         {
           "group": "Analytics",
           "icon": "chart-line",

diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx
@@ -25,6 +25,10 @@ La REST (Representational State Transfer) API de Mintlify te permite interactuar
 * [Create assistant message](/es/api/assistant/create-assistant-message-v2): Integra el assistant, entrenado con tu documentación, en cualquier aplicación que elijas.
 * [Search documentation](/es/api/assistant/search): Busca en tu documentación.
 * [Get page content](/es/api/assistant/get-page-content): Recupera el contenido de texto completo de una página de documentación.
+* [Universal search](/es/api/universal-search/search): Busca en la documentación alojada en Mintlify y en la web con una única consulta.
+* [Assemble a context payload for RAG](/es/api/universal-search/context): Crea un payload de contexto ajustado a un presupuesto de tokens y listo para usar en un pipeline de generación aumentada por recuperación (RAG).
+* [Fetch page content for search results](/es/api/universal-search/contents): Recupera el Markdown completo de las páginas devueltas por la búsqueda universal.
+* [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.
@@ -81,3 +85,11 @@ Las keys del Assistant API comienzan con el prefijo `mint_dsc_`.
 <Note>
   Las llamadas que usan el token del Assistant API pueden generar costos: ya sea usando tus créditos del assistant o incurriendo en excedentes.
 </Note>
+
+<div id="universal-search-api-key">
+  ### Clave de la API de búsqueda universal
+</div>
+
+Usa la clave de la API de búsqueda universal para el endpoint [Universal search](/es/api/universal-search/search).
+
+La búsqueda universal es un complemento de pago. [Contacta con ventas](https://mintlify.com/enterprise) para habilitar el permiso Universal Search en tu organización antes de generar una clave.
diff --git a/es/api/universal-search/contents.mdx b/es/api/universal-search/contents.mdx
@@ -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).
+
+<div id="partial-success">
+## Éxito parcial
+</div>
+
+La respuesta siempre devuelve `200` cuando el cuerpo de la solicitud está bien formado. Inspecciona el array `statuses` para ver qué entradas se resolvieron correctamente y cuáles fallaron. `results` solo contiene las páginas cuyo estado es `success`.
+
+Valores de `tag` de error:
+
+- `not_found`: La URL o el ID no coincide con ninguna página indexada.
+- `not_synced`: La implementación de origen no ha sido indexada para la búsqueda universal.
+- `invalid_id`: El ID tenía un formato incorrecto.
+- `fetch_error`: La consulta falló inesperadamente. Reintenta la solicitud o contacta con soporte con el `requestId`.
diff --git a/es/api/universal-search/context.mdx b/es/api/universal-search/context.mdx
@@ -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.