diff --git a/ai-native.mdx b/ai-native.mdx
index 006a2fc9c2..6606049d52 100644
--- a/ai-native.mdx
+++ b/ai-native.mdx
@@ -39,6 +39,8 @@ Mintlify hosts `llms.txt` and `skill.md` files for your documentation. These ind
Your documentation site also hosts an MCP server that lets users connect your documentation directly to their AI tools for up-to-date information about your product directly where they want it.
+For implementation questions that span multiple products or require web search, [Mintlify Index](/search-index) gives coding agents one MCP server and REST API for retrieving context from publisher-maintained documentation and the web.
+
Full-text search and semantic understanding help users and AI tools find relevant information quickly. Search understands user intent rather than just matching keywords. And if a user encounters a 404 error, your site suggests related pages to help them find what they're looking for. No configuration required.
## Enable AI features
diff --git a/ai/mintlify-mcp.mdx b/ai/mintlify-mcp.mdx
index fe5fa9c5ae..e6a665d03e 100644
--- a/ai/mintlify-mcp.mdx
+++ b/ai/mintlify-mcp.mdx
@@ -17,14 +17,16 @@ Connect any MCP client like Claude, Claude Code, ChatGPT, or Cursor to the admin
The admin MCP is a hosted Mintlify service at `https://mcp.mintlify.com`. Every client connects to the same endpoint and authenticates with your Mintlify account.
-### How the admin MCP differs from the search MCP
-
-| | Admin MCP | Search MCP |
-| :-- | :-- | :-- |
-| **Audience** | Your team | Your end users |
-| **Access** | Read, edit, restructure, save, create workflows, manage settings | Read and search published pages |
-| **Endpoints** | Hosted by Mintlify, scoped to your project | `/mcp` on your site domain |
-| **Output** | Content edits, navigation changes, pull requests, workflow runs | Search results and page content |
+### How the admin MCP differs from other Mintlify MCP servers
+
+| | Admin MCP | Search MCP | Index MCP |
+| :-- | :-- | :-- | :-- |
+| **Audience** | Your team | Your end users | All developers and agents |
+| **Access** | Read, edit, restructure, save, create workflows, manage settings | Read and search one site's published pages | Read and search all Mintlify sites |
+| **Endpoint** | `https://mcp.mintlify.com` | `/mcp` on your site domain | `https://index.mintlify.com` |
+| **Output** | Content edits, navigation changes, pull requests, workflow runs | Search results and page content from your site | Search results and page content from all Mintlify sites |
+
+See the [Mintlify Index MCP reference](/search-index/mcp) for its tool inputs and rate limits.
## Prerequisites
diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx
index e1d31f8621..41b4f22b86 100644
--- a/ai/model-context-protocol.mdx
+++ b/ai/model-context-protocol.mdx
@@ -14,7 +14,7 @@ The Model Context Protocol (MCP) is an open protocol that creates standardized c
Your search MCP server exposes tools for AI applications to search and retrieve your content. Your users must connect your search MCP server to their tools.
- Looking to let agents edit your content instead of read it? Use the [admin MCP server](/ai/mintlify-mcp) for an authenticated MCP server that exposes branching, page editing, navigation, and `docs.json` tools to trusted agents.
+ To let trusted agents edit your content, use the [admin MCP server](/ai/mintlify-mcp). To give coding agents one retrieval source across all Mintlify sites, use [Mintlify Index](/search-index).
### How MCP servers work
diff --git a/api/introduction.mdx b/api/introduction.mdx
index 39a08764eb..5781adc490 100644
--- a/api/introduction.mdx
+++ b/api/introduction.mdx
@@ -6,7 +6,9 @@ boost: 3
---
- The REST API requires a [Pro or Enterprise plan](https://mintlify.com/pricing?ref=api).
+ The platform REST API requires a [Pro or Enterprise plan](https://mintlify.com/pricing?ref=api).
+
+ The [Mintlify Index REST API](/api/search-index/introduction) uses a separate API key and base URL.
The Mintlify REST (Representational State Transfer) API enables you to programmatically interact with your documentation, trigger updates, embed AI-powered chat experiences, and export analytics data.
@@ -45,18 +47,19 @@ The Mintlify REST (Representational State Transfer) API enables you to programma
## Authentication
-Generate API keys on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. Each API key belongs to an organization—you can use keys across multiple deployments within the same organization.
+Generate API keys on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. Admin and Index API keys belong to an organization-you can use the same keys across multiple deployments withing the same organization. Assistant API keys belong to the deployment where you create them.
You can create up to 10 API keys per hour per organization.
When you create a key, you can set it to expire in 7, 30, 60, or 90 days, or select **No expiration**. New keys default to 90 days. The API keys page shows an **Expires in …** badge for keys that expire within 7 days and an **Expired** badge for keys that have already expired. Expired keys stop working, so rotate or replace them before the expiration date.
-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 messages, documentation search, and 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 messages, documentation search, and page content. Proxy in production. |
+| Index API key | `mint_us_` | Index search, context assembly, and content retrieval. Server-side only. |
### Admin API key
@@ -102,9 +105,15 @@ Assistant API keys begin with the `mint_dsc_` prefix.
Search documentation and page content requests do not consume credits. Assistant message requests use credits and can incur overages.
+### Index API key
+
+Use an Index API key to authenticate requests to the [Mintlify Index](/search-index) REST API. Index API keys begin with the `mint_us_` prefix.
+
+The Index API key is a server-side secret. Do not expose it in client-side code.
+
### Restrict keys by IP address
-Optionally restrict an API key to a list of allowed IP addresses or CIDR ranges. When a key has an allowlist, requests from any other IP address return a `403` response. Both admin and assistant API keys support allowlists.
+Optionally restrict an API key to a list of allowed IP addresses or CIDR ranges. When a key has an allowlist, requests from any other IP address return a `403` response. Admin, assistant, and Index API keys support allowlists.
Set the allowlist when you create a key on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. You set the allowlist for the lifetime of the key when you create it. To change the allowlist, you must create a new key. If you don't set an allowlist, the key accepts requests from any IP address.
@@ -136,7 +145,7 @@ The scope only accepts `read` and `write`. Any other value returns a `400` respo
### Set an expiration date
-Optionally set an expiration date on any API key at creation. After the expiration timestamp passes, requests using the key return a `403` response. Both admin and assistant API keys support expiration.
+Optionally set an expiration date on any API key at creation. After the expiration timestamp passes, requests using the key return a `401` response. All API keys support expiration.
Set the expiration on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. You set the expiration for the lifetime of the key. To change it, you must create a new key. If you don't set an expiration, the key never expires.
diff --git a/api/search-index/contents.mdx b/api/search-index/contents.mdx
new file mode 100644
index 0000000000..fd28cb9743
--- /dev/null
+++ b/api/search-index/contents.mdx
@@ -0,0 +1,7 @@
+---
+title: "Get result contents"
+sidebarTitle: "Contents"
+description: "Retrieve content from Mintlify Index by result ID or result URL after searching."
+keywords: ["Mintlify Index", "contents API", "result IDs", "URLs"]
+openapi: "/index-openapi.json POST /v1/contents"
+---
diff --git a/api/search-index/context.mdx b/api/search-index/context.mdx
new file mode 100644
index 0000000000..d9921083bf
--- /dev/null
+++ b/api/search-index/context.mdx
@@ -0,0 +1,7 @@
+---
+title: "Build implementation context"
+sidebarTitle: "Context"
+description: "Assemble source-cited technical context within a token budget for an application or agent."
+keywords: ["Mintlify Index", "context", "citations", "token budget"]
+openapi: "/index-openapi.json POST /v1/context"
+---
diff --git a/api/search-index/introduction.mdx b/api/search-index/introduction.mdx
new file mode 100644
index 0000000000..623547045a
--- /dev/null
+++ b/api/search-index/introduction.mdx
@@ -0,0 +1,93 @@
+---
+title: "Mintlify Index REST API"
+sidebarTitle: "Overview"
+description: "Use the Mintlify Index REST API to search documentation and the web, assemble source-cited context, and retrieve page contents for applications and agents."
+keywords: ["Mintlify Index API", "REST API", "authentication", "API key"]
+---
+
+Use the Mintlify Index REST API to retrieve technical knowledge for applications and agents. The API supports three retrieval patterns:
+
+- [`context`](/api/search-index/context) assembles source-cited content within a token budget.
+- [`search`](/api/search-index/search) returns ranked documentation and web results.
+- [`contents`](/api/search-index/contents) retrieves content for selected Mintlify result IDs or result URLs.
+
+
+ The REST API requires an API key for your organization. The public [Index MCP server](/search-index/mcp) does not require an API key.
+
+
+## Base URL
+
+Send REST API requests to:
+
+```text
+https://leaves.mintlify.com/api/universal-search/v1
+```
+
+Append an endpoint path to this base URL, for example `/context`, `/search`, or `/contents`.
+
+## Authentication
+
+Authenticate each request with an Index API key in the `Authorization` header:
+
+```http
+Authorization: Bearer mint_us_...
+```
+
+Index API keys begin with `mint_us_`.
+
+
+
+ Open the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard and create an Index API key.
+
+ If this key type is unavailable, your organization does not have access to the Index REST API.
+
+
+ Save the key in a server-side environment variable. Mintlify only displays the complete key when you first create it. Store it securely.
+
+ ```bash
+ export MINTLIFY_INDEX_API_KEY="mint_us_..."
+ ```
+
+
+ Do not expose an Index API key in client-side code or commit it to version control.
+
+
+
+ Send your first request to the `context` endpoint:
+
+ ```bash
+ curl -X POST "https://leaves.mintlify.com/api/universal-search/v1/context" \
+ -H "Authorization: Bearer $MINTLIFY_INDEX_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "query": "How should I configure caching in Next.js 16?",
+ "product": "Next.js",
+ "format": "txt",
+ "tokenBudget": 3000
+ }'
+ ```
+
+ A successful response includes assembled context with source URLs, the number of results used, and the output token count.
+
+
+
+## Rate limits
+
+REST API limits apply per Mintlify organization. All API keys in an organization share the same limit:
+
+| Window | Limit |
+| --- | ---: |
+| Per second | 10 requests |
+| Per day | 1,000 requests |
+
+Requests exceeding either limit return `429 Too Many Requests`. Use exponential backoff before retrying.
+
+## Errors
+
+| Status | Meaning |
+| --- | --- |
+| `400` | The request body is invalid. |
+| `401` | The API key is missing or invalid, or the organization does not have Index REST API access. |
+| `403` | The request IP is not allowed by the API key. |
+| `429` | The organization exceeded a rate limit. |
+| `500` | Index could not complete the request. |
diff --git a/api/search-index/search.mdx b/api/search-index/search.mdx
new file mode 100644
index 0000000000..5690c8a5b3
--- /dev/null
+++ b/api/search-index/search.mdx
@@ -0,0 +1,7 @@
+---
+title: "Search technical knowledge"
+sidebarTitle: "Search"
+description: "Search Mintlify Index for ranked technical documentation and web results."
+keywords: ["Mintlify Index", "search API", "technical documentation", "ranked results"]
+openapi: "/index-openapi.json POST /v1/search"
+---
diff --git a/changelog.mdx b/changelog.mdx
index d5abe274ee..1bc80bf337 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -5,6 +5,17 @@ rss: true
noindex: true
---
+
+
+ ## Mintlify Index
+
+ [Mintlify Index](/search-index) gives coding agents one retrieval layer for publisher-maintained technical documentation and the web.
+
+ - **Public MCP server:** [Connect](/search-index/connect) coding agents without an API key. The `context` tool returns source-cited material for implementation tasks.
+ - **Access-controlled REST API:** Search ranked sources, assemble context within a token budget, and retrieve selected contents through separate API endpoints. Requires an Index API key.
+
+
+
## Mintlify widget
diff --git a/docs.json b/docs.json
index 8b49d310ca..0e5373c2c1 100644
--- a/docs.json
+++ b/docs.json
@@ -248,6 +248,14 @@
"ai/skillmd",
"ai/model-context-protocol",
"optimize/search",
+ {
+ "group": "Mintlify Index",
+ "pages": [
+ "search-index/index",
+ "search-index/connect",
+ "search-index/mcp"
+ ]
+ },
"optimize/seo",
"ai/markdown-export",
"optimize/pdf-exports",
@@ -350,6 +358,16 @@
"api/assistant/get-page-content"
]
},
+ {
+ "group": "Mintlify Index",
+ "icon": "library",
+ "pages": [
+ "api/search-index/introduction",
+ "api/search-index/context",
+ "api/search-index/search",
+ "api/search-index/contents"
+ ]
+ },
{
"group": "Analytics",
"icon": "chart-line",
diff --git a/index-openapi.json b/index-openapi.json
new file mode 100644
index 0000000000..24d0d8e5ee
--- /dev/null
+++ b/index-openapi.json
@@ -0,0 +1,715 @@
+{
+ "openapi": "3.0.1",
+ "info": {
+ "title": "Mintlify Index API",
+ "description": "Search and retrieve technical documentation and web context for applications and agents.",
+ "version": "1.0.0"
+ },
+ "servers": [
+ {
+ "url": "https://leaves.mintlify.com/api/universal-search"
+ }
+ ],
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ],
+ "paths": {
+ "/v1/context": {
+ "post": {
+ "operationId": "buildIndexContext",
+ "summary": "Build implementation context",
+ "description": "Searches Mintlify Index and returns source-cited content assembled within a token budget. Use this endpoint when an application or agent needs ready-to-use context in one request.",
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ContextRequest"
+ },
+ "example": {
+ "query": "How should I configure caching in Next.js 16?",
+ "product": "Next.js",
+ "format": "txt",
+ "tokenBudget": 3000
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Context assembled successfully.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ContextResponse"
+ },
+ "example": {
+ "requestId": "7f2ab8d1-3bea-4a29-bc51-c05a8d3a3e3c",
+ "query": "How should I configure caching in Next.js 16?",
+ "response": "### Caching and revalidating\n\nSource: https://nextjs.org/docs/app/getting-started/caching-and-revalidating\n\nUse the current caching APIs described in this guide.\n\n--------------------------------",
+ "resultsCount": 3,
+ "outputTokens": 1842
+ }
+ }
+ }
+ },
+ "400": {
+ "$ref": "#/components/responses/BadRequest"
+ },
+ "401": {
+ "$ref": "#/components/responses/Unauthorized"
+ },
+ "403": {
+ "$ref": "#/components/responses/Forbidden"
+ },
+ "429": {
+ "$ref": "#/components/responses/RateLimited"
+ },
+ "500": {
+ "$ref": "#/components/responses/InternalError"
+ }
+ }
+ }
+ },
+ "/v1/search": {
+ "post": {
+ "operationId": "searchIndex",
+ "summary": "Search technical knowledge",
+ "description": "Returns ranked results from publisher-maintained documentation or the web. Use Mintlify result IDs or any result URL with the contents endpoint when you need more content.",
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchRequest"
+ },
+ "example": {
+ "query": "Next.js 16 caching and revalidation",
+ "numResults": 5,
+ "text": {
+ "maxCharacters": 4000
+ },
+ "includeDomains": [
+ "nextjs.org"
+ ]
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Search completed successfully.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchResponse"
+ },
+ "example": {
+ "requestId": "3d8ed0aa-c21c-4a18-b995-207aa6315ea8",
+ "results": [
+ {
+ "id": "nextjs:/docs/app/getting-started/caching-and-revalidating",
+ "url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating",
+ "title": "Caching and revalidating",
+ "text": "Caching is a technique for storing the result of data fetching and other computations.",
+ "truncated": false,
+ "totalCharacters": 92,
+ "score": 0.91,
+ "source": "mintlify",
+ "siteName": "nextjs",
+ "breadcrumbs": [
+ "App Router",
+ "Getting started"
+ ],
+ "publishedDate": null
+ }
+ ]
+ }
+ }
+ }
+ },
+ "400": {
+ "$ref": "#/components/responses/BadRequest"
+ },
+ "401": {
+ "$ref": "#/components/responses/Unauthorized"
+ },
+ "403": {
+ "$ref": "#/components/responses/Forbidden"
+ },
+ "429": {
+ "$ref": "#/components/responses/RateLimited"
+ },
+ "500": {
+ "$ref": "#/components/responses/InternalError"
+ }
+ }
+ }
+ },
+ "/v1/contents": {
+ "post": {
+ "operationId": "getIndexContents",
+ "summary": "Get result contents",
+ "description": "Retrieves content for Mintlify result IDs or result URLs returned by the search endpoint. A request can include up to 20 items across both fields.",
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ContentsRequest"
+ },
+ "example": {
+ "ids": [
+ "nextjs:/docs/app/getting-started/caching-and-revalidating"
+ ],
+ "query": "revalidate cached data",
+ "maxCharacters": 12000
+ }
+ }
+ }
+ },
+ "responses": {
+ "400": {
+ "description": "The request body is invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "example": {
+ "error": "A request may reference at most 20 items across urls and ids"
+ }
+ }
+ }
+ },
+ "200": {
+ "description": "Content retrieval completed. Check each status to determine whether its item succeeded.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ContentsResponse"
+ },
+ "example": {
+ "requestId": "6bf694e4-76cb-4d31-a222-c94b2d9b198a",
+ "results": [
+ {
+ "id": "nextjs:/docs/app/getting-started/caching-and-revalidating",
+ "url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating",
+ "title": "Caching and revalidating",
+ "text": "# Caching and revalidating\n\nUse revalidation APIs to refresh cached data.",
+ "truncated": false,
+ "totalCharacters": 78,
+ "score": 0,
+ "source": "mintlify",
+ "siteName": "nextjs",
+ "breadcrumbs": [
+ "App Router",
+ "Getting started"
+ ],
+ "publishedDate": null
+ }
+ ],
+ "statuses": [
+ {
+ "id": "nextjs:/docs/app/getting-started/caching-and-revalidating",
+ "status": "success"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/Unauthorized"
+ },
+ "403": {
+ "$ref": "#/components/responses/Forbidden"
+ },
+ "429": {
+ "$ref": "#/components/responses/RateLimited"
+ },
+ "500": {
+ "$ref": "#/components/responses/InternalError"
+ }
+ }
+ }
+ }
+ },
+ "components": {
+ "securitySchemes": {
+ "bearerAuth": {
+ "type": "http",
+ "scheme": "bearer",
+ "bearerFormat": "Mintlify Index API key",
+ "description": "Mintlify Index API key with the `mint_us_` prefix."
+ }
+ },
+ "responses": {
+ "BadRequest": {
+ "description": "The request body is invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "example": {
+ "error": "Invalid request body"
+ }
+ }
+ }
+ },
+ "Unauthorized": {
+ "description": "The API key is missing or invalid, or the organization does not have Index REST API access.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "example": {
+ "error": "Unauthorized"
+ }
+ }
+ }
+ },
+ "Forbidden": {
+ "description": "The request IP is not allowed by the API key.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "example": {
+ "error": "IP address is not allowed for this API key"
+ }
+ }
+ }
+ },
+ "RateLimited": {
+ "description": "The organization exceeded a rate limit.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "example": {
+ "error": "Rate limit exceeded. Please try again later"
+ }
+ }
+ }
+ },
+ "InternalError": {
+ "description": "Index could not complete the request.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ }
+ },
+ "schemas": {
+ "ContextRequest": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "query",
+ "format"
+ ],
+ "properties": {
+ "query": {
+ "type": "string",
+ "minLength": 1,
+ "description": "Implementation question to research."
+ },
+ "product": {
+ "type": "string",
+ "minLength": 1,
+ "description": "Product or company name to use as an additional retrieval hint."
+ },
+ "format": {
+ "type": "string",
+ "enum": [
+ "txt",
+ "json"
+ ],
+ "description": "Format of the `response` string. `txt` returns Markdown sections. `json` returns a serialized JSON object containing result items."
+ },
+ "includeDomains": {
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "string",
+ "minLength": 1
+ },
+ "description": "Domains to include in retrieval."
+ },
+ "excludeDomains": {
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "string",
+ "minLength": 1
+ },
+ "description": "Domains to exclude from retrieval."
+ },
+ "tokenBudget": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 6000,
+ "default": 3000,
+ "description": "Maximum number of output tokens."
+ }
+ }
+ },
+ "ContextResponse": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "requestId",
+ "query",
+ "response",
+ "resultsCount",
+ "outputTokens"
+ ],
+ "properties": {
+ "requestId": {
+ "type": "string",
+ "description": "Unique identifier for the request."
+ },
+ "query": {
+ "type": "string",
+ "description": "Original query from the request."
+ },
+ "response": {
+ "type": "string",
+ "description": "Assembled source content. The value is Markdown for `txt` requests and serialized JSON for `json` requests. The string can be empty when no content fits within the token budget."
+ },
+ "resultsCount": {
+ "type": "integer",
+ "minimum": 0,
+ "description": "Number of source snippets included in the response."
+ },
+ "outputTokens": {
+ "type": "integer",
+ "minimum": 0,
+ "description": "Number of tokens in the assembled response."
+ }
+ }
+ },
+ "SearchRequest": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "query",
+ "numResults"
+ ],
+ "properties": {
+ "query": {
+ "type": "string",
+ "minLength": 1,
+ "description": "Search query."
+ },
+ "numResults": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 20,
+ "description": "Maximum number of results to return."
+ },
+ "text": {
+ "default": false,
+ "description": "Controls result content. Set to `true` to include matched content, `false` to omit it, or provide `maxCharacters` to include truncated content. When omitted, defaults to `false`.",
+ "oneOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "maxCharacters"
+ ],
+ "properties": {
+ "maxCharacters": {
+ "type": "integer",
+ "minimum": 1,
+ "description": "Maximum number of content characters to include per result."
+ }
+ }
+ }
+ ]
+ },
+ "includeDomains": {
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "string",
+ "minLength": 1
+ },
+ "description": "Domains to include in search results."
+ },
+ "excludeDomains": {
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "string",
+ "minLength": 1
+ },
+ "description": "Domains to exclude from search results."
+ }
+ }
+ },
+ "SearchResponse": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "requestId",
+ "results"
+ ],
+ "properties": {
+ "requestId": {
+ "type": "string",
+ "description": "Unique identifier for the request."
+ },
+ "results": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SearchResult"
+ },
+ "description": "Ranked search results."
+ }
+ }
+ },
+ "SearchResult": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "id",
+ "url",
+ "title",
+ "text",
+ "score",
+ "source",
+ "siteName",
+ "breadcrumbs",
+ "publishedDate"
+ ],
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Result identifier. Pass IDs from Mintlify results in the contents request's `ids` field. For web results, pass the result URL in `urls`."
+ },
+ "url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Canonical source URL."
+ },
+ "title": {
+ "type": "string",
+ "description": "Source title."
+ },
+ "text": {
+ "type": "string",
+ "description": "Matched content when requested. Otherwise, an empty string."
+ },
+ "truncated": {
+ "type": "boolean",
+ "description": "Whether the returned content is shorter than the available content."
+ },
+ "totalCharacters": {
+ "type": "integer",
+ "minimum": 0,
+ "description": "Number of available characters before truncation. Present when available."
+ },
+ "score": {
+ "type": "number",
+ "description": "Relative relevance score. Contents responses use `0` because they retrieve selected items rather than rank results."
+ },
+ "source": {
+ "type": "string",
+ "enum": [
+ "mintlify",
+ "web"
+ ],
+ "description": "Retrieval source."
+ },
+ "siteName": {
+ "type": "string",
+ "description": "Documentation site or web hostname."
+ },
+ "breadcrumbs": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Documentation hierarchy for the result."
+ },
+ "publishedDate": {
+ "type": "string",
+ "nullable": true,
+ "description": "Published date when the source provides one, otherwise `null`. `search` results normalize this to a full ISO 8601 timestamp. `contents` results retrieved by `urls` pass the source's original date string through unnormalized, which can be a full timestamp or a date-only string."
+ }
+ }
+ },
+ "ContentsRequest": {
+ "type": "object",
+ "additionalProperties": false,
+ "description": "Provide at least one Mintlify result ID or result URL. You can combine both fields, with up to 20 items total.",
+ "anyOf": [
+ {
+ "required": [
+ "urls"
+ ]
+ },
+ {
+ "required": [
+ "ids"
+ ]
+ }
+ ],
+ "properties": {
+ "urls": {
+ "type": "array",
+ "minItems": 1,
+ "maxItems": 20,
+ "items": {
+ "type": "string",
+ "format": "uri"
+ },
+ "description": "Result URLs to retrieve. Use this field for web results."
+ },
+ "ids": {
+ "type": "array",
+ "minItems": 1,
+ "maxItems": 20,
+ "items": {
+ "type": "string",
+ "minLength": 1
+ },
+ "description": "Mintlify result IDs to retrieve."
+ },
+ "maxCharacters": {
+ "type": "integer",
+ "minimum": 1,
+ "description": "Maximum number of content characters to return per result."
+ },
+ "query": {
+ "type": "string",
+ "minLength": 1,
+ "description": "Query used to select the most relevant sections when content exceeds `maxCharacters`."
+ }
+ }
+ },
+ "ContentsResponse": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "requestId",
+ "results",
+ "statuses"
+ ],
+ "properties": {
+ "requestId": {
+ "type": "string",
+ "description": "Unique identifier for the request."
+ },
+ "results": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SearchResult"
+ },
+ "description": "Successfully retrieved results."
+ },
+ "statuses": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/ContentStatus"
+ },
+ "description": "Retrieval status for each requested item."
+ }
+ }
+ },
+ "ContentStatus": {
+ "oneOf": [
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "id",
+ "status"
+ ],
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Requested ID or URL."
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "success"
+ ],
+ "description": "Retrieval status."
+ }
+ }
+ },
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "id",
+ "status",
+ "error"
+ ],
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Requested ID or URL."
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "error"
+ ],
+ "description": "Retrieval status."
+ },
+ "error": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "tag",
+ "httpStatusCode"
+ ],
+ "properties": {
+ "tag": {
+ "type": "string",
+ "description": "Machine-readable error category."
+ },
+ "httpStatusCode": {
+ "type": "integer",
+ "nullable": true,
+ "description": "Upstream HTTP status code when available."
+ }
+ }
+ }
+ }
+ }
+ ]
+ },
+ "Error": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "error"
+ ],
+ "properties": {
+ "error": {
+ "type": "string",
+ "description": "Error message."
+ }
+ }
+ }
+ }
+ }
+}
diff --git a/search-index/connect.mdx b/search-index/connect.mdx
new file mode 100644
index 0000000000..bcd232bc45
--- /dev/null
+++ b/search-index/connect.mdx
@@ -0,0 +1,133 @@
+---
+title: "Connect Mintlify Index to your coding agent"
+sidebarTitle: "Connect"
+description: "Set up the Mintlify Index MCP server in Claude Code, Cursor, VS Code, Codex, OpenCode, Windsurf, or Zed with the CLI or manual configuration."
+keywords: ["Mintlify Index", "CLI", "Claude Code", "Cursor", "MCP", "technical documentation"]
+---
+
+import { PreviewButton } from "/snippets/previewbutton.jsx"
+
+Connect your coding agent to Mintlify Index so it can retrieve current technical documentation and web context while it plans and writes code. Index supports Claude Code, Cursor, VS Code, Codex, OpenCode, Windsurf, and Zed.
+
+
+ You do not need a Mintlify account or API key to connect to the public Index MCP server.
+
+
+## Set up with the CLI
+
+Run the Index setup command to configure one or more coding agents in a single step:
+
+```bash
+npx mint index
+```
+
+The command detects which supported coding agents you have installed and prompts you to choose which ones to configure. For each agent you select, it adds the Index MCP server to that agent's configuration and installs a rule telling the agent when to use the `context` tool.
+
+To skip the picker, pass one or more agent flags instead:
+
+```bash
+npx mint index --claude --cursor
+```
+
+| Flag | Coding agent |
+| --- | --- |
+| `--claude` | Claude Code |
+| `--cursor` | Cursor |
+| `--vscode` | VS Code |
+| `--codex` | Codex |
+| `--opencode` | OpenCode |
+| `--windsurf` | Windsurf |
+| `--zed` | Zed |
+
+
+ Add `--yes` to configure every detected agent without prompting, or `--project` to write the configuration to the current project instead of your global agent settings. Not every agent supports project-level configuration. Those agents always receive the global configuration.
+
+
+Run the command again to update an existing setup or add another agent.
+
+## Set up manually
+
+To configure Claude Code or Cursor manually, or to verify what the CLI changed, follow the steps for your agent.
+
+
+
+
+
+ Run the following command:
+
+ ```bash
+ claude mcp add --transport http mintlify-index https://index.mintlify.com
+ ```
+
+
+ List your configured MCP servers:
+
+ ```bash
+ claude mcp list
+ ```
+
+ The output should include `mintlify-index` with a connected status.
+
+
+
+
+ Select **Install in Cursor**, review the MCP configuration, and approve the installation.
+
+ Install in Cursor
+
+ To configure Cursor manually instead:
+
+
+
+ 1. Open the command palette with Command + Shift + P (Ctrl + Shift + P on Windows).
+ 2. Search for **Open MCP settings**.
+ 3. Select **Add custom MCP** to open `mcp.json`.
+
+
+ Add the following server:
+
+ ```json
+ {
+ "mcpServers": {
+ "mintlify-index": {
+ "url": "https://index.mintlify.com"
+ }
+ }
+ }
+ ```
+
+
+ Reload Cursor, then open **Settings → Tools & MCP**. The `mintlify-index` server should show as connected with the `context` tool available.
+
+
+
+
+
+## Use Index in a session
+
+Ask an implementation question and tell your agent to use Index when you want to ensure it retrieves current sources. For example:
+
+```text
+Use Mintlify Index to find the current recommended way to configure caching in Next.js 16. Cite the sources you use.
+```
+
+The agent calls the Index `context` tool when it needs technical context and includes the returned source links in its work.
+
+## Remove the connection
+
+
+
+ Run the following command:
+
+ ```bash
+ claude mcp remove mintlify-index
+ ```
+
+
+ Open **Settings → Tools & MCP**, then delete the `mintlify-index` entry from `mcp.json`.
+
+
+
+For VS Code, Codex, OpenCode, Windsurf, or Zed, remove the `mintlify-index` entry from that agent's MCP server configuration.
+
+See the [Index MCP reference](/search-index/mcp) for tool inputs and rate limits.
diff --git a/search-index/index.mdx b/search-index/index.mdx
new file mode 100644
index 0000000000..beb228721e
--- /dev/null
+++ b/search-index/index.mdx
@@ -0,0 +1,47 @@
+---
+title: "Mintlify Index"
+sidebarTitle: "Overview"
+description: "Give coding agents current technical context from publisher-maintained documentation and the web through one MCP server or REST API."
+keywords: ["Mintlify Index", "technical search", "coding agents", "MCP", "REST API"]
+---
+
+Mintlify Index gives coding agents one search layer for technical knowledge. It routes questions about indexed products to publisher-maintained documentation hosted on Mintlify and uses web search for questions outside that corpus.
+
+Use Index through the public MCP server or the access-controlled REST API.
+
+- **MCP server**: Connect an AI tool and let it retrieve source-cited context while you work. Publicly available. Does not require an API key.
+- **REST API**: Search for ranked sources, assemble context within a token budget, or retrieve the contents of selected results. Access-controlled. Requires an Index API key.
+
+## Get started
+
+
+
+ Add Index to Claude Code, Codex, Cursor, and other coding agents.
+
+
+ Review the `context` tool, input fields, output, and rate limits.
+
+
+ Use `search`, `context`, and `contents` in an application or agent.
+
+
+
+## How Index retrieves context
+
+
+
+ Index identifies whether the question concerns a product in its documentation corpus or requires broader web results.
+
+
+ Product-specific questions search current documentation from the publisher. Other questions search the web.
+
+
+ Index ranks the results and returns source URLs with the relevant content. The MCP `context` tool and REST `context` endpoint assemble that content within a token budget.
+
+
+
+## Choose a retrieval operation
+
+- **[`context`](/api/search-index/context)**: Use this for most agent tasks. It returns a compact set of cited source material in one request.
+- **[`search`](/api/search-index/search)**: Use this when your application needs ranked results and controls which sources to read. Available through the REST API.
+- **[`contents`](/api/search-index/contents)**: Use this after `search` to retrieve content for selected Mintlify result IDs or result URLs. Available through the REST API.
diff --git a/search-index/mcp.mdx b/search-index/mcp.mdx
new file mode 100644
index 0000000000..09e0328048
--- /dev/null
+++ b/search-index/mcp.mdx
@@ -0,0 +1,77 @@
+---
+title: "Mintlify Index MCP server"
+sidebarTitle: "MCP reference"
+description: "Reference for the public Mintlify Index MCP server, including its context tool, parameters, output, and rate limits."
+keywords: ["Mintlify Index", "MCP server", "context tool", "rate limits"]
+---
+
+The Mintlify Index MCP server gives AI tools read-only access to technical documentation and web context. Connect to it at:
+
+```text
+https://index.mintlify.com
+```
+
+You do not need to authenticate to the public server. See [Connect](/search-index/connect) for Claude Code and Cursor setup instructions.
+
+
+ The Index MCP searches across covered product documentation and the technical web. To search only the content on a specific Mintlify-hosted site, use that site's [search MCP server](/ai/model-context-protocol).
+
+
+## `context` tool
+
+Use `context` to research an implementation task and return compact, source-cited context in one call. The tool is read-only and can access the open web.
+
+
+ Implementation question to research.
+
+
+
+ Product or company name to use as an additional retrieval hint.
+
+
+
+ Domains to include in retrieval. When set, retrieval limits results to these domains.
+
+
+
+ Domains to exclude from retrieval.
+
+
+
+ Maximum number of tokens to return. The maximum value is `6000`. Use the default for focused questions and a larger budget for complex, multi-part tasks.
+
+
+### Output
+
+The tool returns Markdown-formatted context assembled from ranked sources. Each section includes a title, source URL, and the relevant source content.
+
+```text
+### Configure caching
+
+Source: https://nextjs.org/docs/app/getting-started/caching-and-revalidating
+
+Relevant source content appears here.
+
+--------------------------------
+```
+
+The MCP server returns source material for the connected agent to use. The agent decides how to apply that context to your task.
+
+## Rate limits
+
+Index applies the following per-IP limits to the public MCP server:
+
+| Window | Limit |
+| --- | ---: |
+| Per second | 10 requests |
+| Per day | 1,000 requests |
+
+Requests exceeding either limit return `429 Too Many Requests`. Wait before retrying, and use exponential backoff for automated clients.
+
+## Protocol behavior
+
+The Index MCP uses stateless Streamable HTTP:
+
+- Send each JSON-RPC request as an HTTP `POST`.
+- Send one JSON-RPC request per HTTP request. Batching is not supported.
+- Do not persist or send an MCP session ID between requests.