From 9e932990cffacbf91b020cc7a718d01cd46f3d85 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 22 Jul 2026 15:21:59 -0700
Subject: [PATCH 1/4] add search endpoint section
---
docs.json | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/docs.json b/docs.json
index 0da21a45b2..0d7a8584ae 100644
--- a/docs.json
+++ b/docs.json
@@ -407,10 +407,16 @@
"icon": "bot-message-square",
"pages": [
"api/assistant/create-assistant-message-v2",
- "api/assistant/search",
"api/assistant/get-page-content"
]
},
+ {
+ "group": "Search",
+ "icon": "search",
+ "pages": [
+ "api/assistant/search"
+ ]
+ },
{
"group": "Analytics",
"icon": "chart-line",
From e8488b10113fc66b6077645bcf0005ea575eed15 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 22 Jul 2026 15:24:29 -0700
Subject: [PATCH 2/4] fix icon label
---
docs.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs.json b/docs.json
index 0d7a8584ae..3500de4a24 100644
--- a/docs.json
+++ b/docs.json
@@ -377,7 +377,7 @@
"groups": [
{
"group": "API reference",
- "icon": "file-json",
+ "icon": "file-braces",
"pages": [
"api/introduction"
]
From 264318167ce79873f374cc85bdfe240fe5980467 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 22 Jul 2026 15:31:38 -0700
Subject: [PATCH 3/4] update index
---
api/introduction.mdx | 19 ++++++++++---------
docs.json | 6 +++---
2 files changed, 13 insertions(+), 12 deletions(-)
diff --git a/api/introduction.mdx b/api/introduction.mdx
index e8e791f52b..2bf9d922b5 100644
--- a/api/introduction.mdx
+++ b/api/introduction.mdx
@@ -38,7 +38,8 @@ The Mintlify REST (Representational State Transfer) API enables you to programma
- **CI/CD integration**: Update documentation as part of your deployment pipeline when code changes with [Trigger update](/api/update/trigger).
- **Preview deployments**: Create or update preview deployments programmatically in your CI/CD pipeline with [Trigger preview deployment](/api/preview/trigger).
- **On-demand automations**: Run scheduled automations from your CI/CD pipeline or release tooling with [Trigger automation](/api/automations/trigger).
-- **Custom integrations**: Embed the AI assistant into your product, support portal, or internal tools with [Create assistant message](/api/assistant/create-assistant-message-v2), [Search documentation](/api/assistant/search), and [Get page content](/api/assistant/get-page-content).
+- **Assistant integrations**: Embed the AI assistant into your product, support portal, or internal tools with [Create assistant message](/api/assistant/create-assistant-message-v2).
+- **Documentation retrieval**: Find and retrieve documentation for custom search experiences with [Search documentation](/api/assistant/search) and [Get page content](/api/assistant/get-page-content).
- **Automated editing**: Use agent jobs to programmatically update documentation at scale with [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), and [Send follow-up message](/api/agent/v2/send-message).
- **Analytics export**: Export feedback, assistant conversations, search analytics, page views, and visitor data for external analysis with [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), [Get assistant caller stats](/api/analytics/assistant-caller-stats), [Get search queries](/api/analytics/searches), [Get page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors).
@@ -50,10 +51,10 @@ 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:
-| 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 messages, documentation search, and page content. Proxy in production. |
### Admin API key
@@ -82,12 +83,12 @@ The admin API key is a server-side secret. Do not expose it in client-side code.
### Assistant API key
- Do not directly embed the assistant API key in client-side code. Any visitor who extracts the key can send requests on your behalf, consuming credits and potentially triggering overage charges.
+ Do not directly embed the assistant API key in client-side code. Any visitor who extracts the key can call the assistant message endpoint on your behalf, consuming credits and potentially triggering overage charges.
- For production deployments, proxy assistant API requests through your own backend and store the key as a server-side environment variable. Routing requests through a proxy also lets you add rate limiting, authentication, and bot protection to prevent abuse.
+ For production deployments, proxy requests that use an assistant API key through your own backend and store the key as a server-side environment variable. Routing requests through a proxy also lets you add rate limiting, authentication, and bot protection to prevent abuse.
-Use the assistant API key for the assistant endpoints.
+Use the assistant API key to authenticate requests to the assistant, search, and page content endpoints.
- [Create assistant message](/api/assistant/create-assistant-message-v2)
- [Search documentation](/api/assistant/search)
@@ -96,5 +97,5 @@ Use the assistant API key for the assistant endpoints.
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.
+ Search documentation and page content requests do not consume credits. Assistant message requests use credits and can incur overages.
diff --git a/docs.json b/docs.json
index 3500de4a24..cc65e2c226 100644
--- a/docs.json
+++ b/docs.json
@@ -406,15 +406,15 @@
"group": "Assistant",
"icon": "bot-message-square",
"pages": [
- "api/assistant/create-assistant-message-v2",
- "api/assistant/get-page-content"
+ "api/assistant/create-assistant-message-v2"
]
},
{
"group": "Search",
"icon": "search",
"pages": [
- "api/assistant/search"
+ "api/assistant/search",
+ "api/assistant/get-page-content"
]
},
{
From 160640e424cff9d8b2fd50c52ca2755cc61996fc Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 22 Jul 2026 15:32:04 -0700
Subject: [PATCH 4/4] very clear search endpoints don't use credits
---
discovery-openapi.json | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/discovery-openapi.json b/discovery-openapi.json
index 10c41dd09c..e2b54c88f0 100644
--- a/discovery-openapi.json
+++ b/discovery-openapi.json
@@ -743,7 +743,7 @@
"/v1/page/{domain}": {
"post": {
"summary": "Get page content",
- "description": "Retrieve the full text content of a specific documentation page by its path. Use this after a search to fetch the complete content of a matching page.\n\nAuthenticate with an assistant API key.",
+ "description": "Retrieve the full text content of a specific documentation page by its path. Use this after a search to fetch the complete content of a matching page.\n\nAuthenticate with an assistant API key. Page content requests do not consume credits.",
"parameters": [
{
"name": "domain",
@@ -767,7 +767,7 @@
"properties": {
"path": {
"type": "string",
- "description": "The page slug or path to retrieve content for. This corresponds to the `page` field returned by the [Search documentation](/api/assistant/search) endpoint."
+ "description": "The page slug or path to retrieve content for. This corresponds to the `path` field returned by the [Search documentation](/api/assistant/search) endpoint."
}
}
}
@@ -822,7 +822,7 @@
}
},
"summary": "Search documentation",
- "description": "Perform semantic and keyword searches across your documentation with configurable filtering and pagination.\n\nAuthenticate with an assistant API key.",
+ "description": "Perform semantic and keyword searches across your documentation with configurable filtering and pagination.\n\nAuthenticate with an assistant API key. Search requests do not consume credits.",
"parameters": [
{
"name": "domain",