skills/mintlify__docs
1
0
Fork 0
mirror of https://github.com/mintlify/docs.git synced 2026-09-14 13:35:46 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
mintlify__docs/zh/discovery-openapi.json
T
mintlify[bot] 3b821703e8 docs: document caller-passed groups on discovery search and page endpoints (#6712) 
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
2026-07-23 14:29:25 -07:00

943 lines
40 KiB
JSON
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"openapi": "3.0.1",
"info": {
"title": "Mintlify Assistant API",
"description": "用于将 Mintlify 的探索功能集成到你的产品中的 API。",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.mintlify.com/discovery"
}
],
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/v1/assistant/{domain}/message": {
"post": {
"summary": "AI 助手消息 v1",
"description": "为指定的 domain 生成 AI 助手的回复消息。兼容 AI SDK v4。\n\n使用 assistant API 密钥进行身份验证。",
"parameters": [
{
"name": "domain",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "在你的 `domain.mintlify.site` URL 中使用的 domain 标识符。你可以在控制台 URL 的末尾找到它。例如，在 `dashboard.mintlify.com/organization/domain` 中，domain 标识符为 `domain`。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"fp",
"messages"
],
"properties": {
"fp": {
"type": "string",
"description": "用于会话跟踪的指纹标识符。对匿名用户使用 `anonymous`，或提供唯一的用户标识符。"
},
"threadId": {
"default": null,
"type": "string",
"description": "一个可选的标识符，用于在多条消息之间保持会话的连续性。提供该标识符后，系统可以将后续消息关联到同一个会话线程。当 event.type === 'finish' 时，响应中会通过 event.threadId 字段返回该 threadId。"
},
"messages": {
"type": "array",
"default": [
{
"id": "foobar",
"role": "user",
"content": "how do i get started",
"parts": [
{
"type": "text",
"text": "How do I get started"
}
]
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "消息的唯一标识符。"
},
"role": {
"type": "string",
"enum": [
"system",
"assistant",
"data",
"user"
],
"description": "消息发送方的角色。"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "消息创建时的时间戳。"
},
"content": {
"type": "string",
"description": "消息的内容。"
},
"annotations": {
"type": "array",
"items": {},
"description": "消息的可选注解数组。"
},
"parts": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"text"
]
},
"text": {
"type": "string"
}
},
"required": [
"type",
"text"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"reasoning"
]
},
"reasoning": {
"type": "string"
},
"details": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"text"
]
},
"text": {
"type": "string"
},
"signature": {
"type": "string"
}
},
"required": [
"type",
"text"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"redacted"
]
},
"data": {
"type": "string"
}
},
"required": [
"type",
"data"
]
}
]
}
}
},
"required": [
"type",
"reasoning",
"details"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"step-start"
]
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"source"
]
},
"source": {
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"enum": [
"url"
]
},
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"sourceType",
"id",
"url"
]
}
},
"required": [
"type",
"source"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"tool-invocation"
]
},
"toolInvocation": {
"oneOf": [
{
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"partial-call"
]
},
"step": {
"type": "number"
},
"toolCallId": {
"type": "string"
},
"toolName": {
"type": "string"
},
"args": {}
},
"required": [
"state",
"toolCallId",
"toolName",
"args"
]
},
{
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"call"
]
},
"step": {
"type": "number"
},
"toolCallId": {
"type": "string"
},
"toolName": {
"type": "string"
},
"args": {}
},
"required": [
"state",
"toolCallId",
"toolName",
"args"
]
},
{
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"result"
]
},
"step": {
"type": "number"
},
"toolCallId": {
"type": "string"
},
"toolName": {
"type": "string"
},
"args": {},
"result": {}
},
"required": [
"state",
"toolCallId",
"toolName",
"args",
"result"
]
}
]
}
},
"required": [
"type",
"toolInvocation"
]
}
]
},
"description": "由多种类型组成的消息片段数组，包括文本、推理、来源以及工具调用。"
},
"experimental_attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"contentType": {
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"url"
]
},
"description": "消息可选的实验性附件数组。"
}
},
"required": [
"id",
"role",
"content",
"parts"
]
},
"description": "会话中的消息数组。在前端，你通常会希望使用 @ai-sdk 包中 useChat 钩子提供的 handleSubmit 函数来追加用户消息并处理流式响应，而不是在这个数组里手动定义对象，因为这些对象包含的参数非常多。"
},
"retrievalPageSize": {
"type": "number",
"default": 5,
"description": "用于生成回复的文档搜索结果数量。数值越高可提供的上下文越多，但可能增加响应时间。推荐值：5。"
},
"filter": {
"type": "object",
"default": null,
"properties": {
"version": {
"type": "string",
"description": "可选的版本筛选器。"
},
"language": {
"type": "string",
"description": "可选的语言筛选器。"
}
},
"description": "用于搜索的可选筛选条件。"
},
"context": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"code",
"textSelection"
],
"description": "所提供上下文的类型。"
},
"value": {
"type": "string",
"description": "代码片段或选中的文本内容。"
},
"path": {
"type": "string",
"description": "指向源文件或页面的可选路径。"
},
"elementId": {
"type": "string",
"description": "承载该上下文的 UI 元素的可选标识符。"
}
},
"required": [
"type",
"value"
]
},
"description": "用于传递给 AI 助手的可选上下文信息数组。"
},
"currentPath": {
"type": "string",
"description": "用户当前正在查看的页面路径。若提供，AI 助手会利用该上下文给出更相关的回答。最大长度：200 个字符。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "消息生成成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "响应对象，其中的数据流部分会根据指定的状态码、响应头和内容进行格式化。更多信息请参阅 AI SDK 文档：[ai-sdk.dev/docs/ai-sdk-ui/streaming-data](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data)。使用 AI SDK 提供的 [useChat Hook](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) 来处理响应流。"
}
}
}
}
}
}
},
"/v2/assistant/{domain}/message": {
"post": {
"summary": "AI 助手的消息",
"description": "针对指定的 domain，从 AI 助手生成一条回复消息。适用于 AI SDK v5 及更高版本。\n\n使用 assistant API 密钥进行身份验证。",
"parameters": [
{
"name": "domain",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "来自你的 `domain.mintlify.site` URL 中的 domain 标识符。你可以在控制台 URL 的末尾找到它。例如，在 `dashboard.mintlify.com/organization/domain` 中，domain 标识符是 `domain`。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"fp",
"messages"
],
"properties": {
"fp": {
"type": "string",
"description": "用于跟踪会话的指纹标识符。对匿名用户使用 `anonymous`，或提供一个唯一的用户标识符。"
},
"threadId": {
"default": null,
"type": "string",
"description": "一个可选的标识符，用于在多条消息之间保持会话的连续性。提供该值后，系统会将后续消息关联到同一个会话线程。当 `event.type === 'finish'` 时，响应中会在 `event.threadId` 字段返回该 `threadId`。"
},
"messages": {
"type": "array",
"default": [
{
"id": "foobar",
"role": "user",
"parts": [
{
"type": "text",
"text": "How do I get started"
}
]
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "消息的唯一标识符。"
},
"role": {
"type": "string",
"enum": [
"system",
"assistant",
"user"
],
"description": "消息发送者的角色。"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "消息创建时的时间戳。"
},
"parts": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"description": "文本内容片段。",
"properties": {
"type": {
"type": "string",
"enum": [
"text"
]
},
"text": {
"type": "string"
}
},
"required": [
"type",
"text"
]
},
{
"type": "object",
"description": "包含可选提供方 metadata 的推理内容片段。",
"properties": {
"type": {
"type": "string",
"enum": [
"reasoning"
]
},
"text": {
"type": "string"
},
"providerMetadata": {
"type": "object",
"description": "可选的、特定于提供方的 metadata。"
}
},
"required": [
"type",
"text"
]
},
{
"type": "object",
"description": "引用来源 URL 的片段。",
"properties": {
"type": {
"type": "string",
"enum": [
"source-url"
]
},
"sourceId": {
"type": "string"
},
"url": {
"type": "string"
},
"title": {
"type": "string"
},
"providerMetadata": {
"type": "object",
"description": "可选的、特定于提供方的 metadata。"
}
},
"required": [
"type",
"sourceId",
"url"
]
},
{
"type": "object",
"description": "文件附件内容片段。",
"properties": {
"type": {
"type": "string",
"enum": [
"file"
]
},
"mediaType": {
"type": "string"
},
"url": {
"type": "string"
},
"filename": {
"type": "string"
}
},
"required": [
"type",
"mediaType",
"url"
]
},
{
"type": "object",
"description": "标记一个新步骤开始的片段。",
"properties": {
"type": {
"type": "string",
"enum": [
"step-start"
]
}
},
"required": [
"type"
]
}
]
},
"description": "消息片段数组。每个片段都有一个类型以及该类型特有的字段。"
},
"metadata": {
"type": "object",
"description": "与消息关联的可选 metadata。"
}
},
"required": [
"id",
"role",
"parts"
]
},
"description": "会话中的消息数组。使用 @ai-sdk/react 包中的 useChat 钩子提供的 handleSubmit 函数来管理消息和流式响应。"
},
"retrievalPageSize": {
"type": "number",
"default": 5,
"description": "用于生成回答时检索的文档搜索结果数量。数值越高，可用的上下文越多，但可能增加响应时间。推荐值：5。"
},
"filter": {
"type": "object",
"default": null,
"properties": {
"version": {
"type": "string",
"description": "可选的版本过滤条件。"
},
"language": {
"type": "string",
"description": "可选的语言过滤条件。"
},
"groups": {
"type": "array",
"items": {
"type": "string"
},
"description": "可选的分组标识符数组，用于筛选结果。"
}
},
"description": "用于搜索的可选筛选条件。"
},
"context": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"code",
"textSelection"
],
"description": "所提供上下文的类型。"
},
"value": {
"type": "string",
"description": "代码片段或选中文本的内容。"
},
"path": {
"type": "string",
"description": "源文件或页面的可选路径。"
},
"elementId": {
"type": "string",
"description": "包含该上下文的 UI 元素的可选标识符。"
}
},
"required": [
"type",
"value"
]
},
"description": "提供给 AI 助手的可选上下文信息数组。"
},
"currentPath": {
"type": "string",
"description": "用户当前正在查看的页面路径。若提供，AI 助手会利用该上下文给出更相关的回答。最大长度：200 个字符。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "消息已成功生成",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "与 AI SDK v5 兼容的流式响应。使用 [@ai-sdk/react 中的 useChat 钩子](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) 来处理响应流。"
}
}
}
}
}
}
},
"/v1/page/{domain}": {
"post": {
"summary": "获取页面内容",
"description": "通过路径检索特定文档页面的完整文本内容。在搜索之后使用此接口来获取匹配页面的完整内容。\n\n使用 assistant API 密钥进行身份验证。页面内容请求不消耗额度。",
"parameters": [
{
"name": "domain",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "来自你的 `domain.mintlify.site` URL 的域名标识符。可以在你的控制台 URL 末尾找到。例如，`dashboard.mintlify.com/organization/domain` 的域名标识符为 `domain`。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"description": "要检索内容的页面路径或 slug。对应于 [Search documentation](/zh/api/assistant/search) 端点返回的 `path` 字段。"
},
"groups": {
"type": "array",
"items": {
"type": "string"
},
"description": "调用方获授权访问的可选文档分组。当部署启用 `auth` 或 `userAuth` 时，仅当指定分组可查看该页面时才返回其内容。在受保护的部署上如果省略或为空，则仅返回公开页面。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "页面内容检索成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "所请求的页面路径。"
},
"content": {
"type": "string",
"description": "页面的完整文本内容。"
}
}
}
}
}
},
"404": {
"description": "页面未找到或搜索索引不可用",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "描述为何无法找到该页面的错误消息。"
}
}
}
}
}
}
}
}
},
"/v1/search/{domain}": {
"post": {
"x-mint": {
"mcp": {
"enabled": true
}
},
"summary": "搜索文档",
"description": "在你的文档中执行语义搜索和关键词搜索，并支持可配置的过滤和分页。\n\n使用 assistant API 密钥进行身份验证。搜索请求不消耗额度。",
"parameters": [
{
"name": "domain",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "来自你的 `domain.mintlify.site` URL 的域名标识符。可以在控制台 URL 的末尾找到。例如，`dashboard.mintlify.com/organization/domain` 的域名标识符就是 `domain`。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "在文档内容中要执行的搜索查询。"
},
"pageSize": {
"type": "integer",
"default": 10,
"minimum": 1,
"maximum": 50,
"description": "要返回的搜索结果数量。必须在 1 到 50 之间。若未指定，默认为 10。"
},
"scoreThreshold": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "结果的最低相关性分数。仅返回分数等于或高于此阈值的结果。必须介于 0 和 1 之间。"
},
"filter": {
"type": "object",
"description": "用于缩小搜索结果范围的可选过滤参数。",
"properties": {
"version": {
"type": "string",
"description": "按文档版本筛选结果。"
},
"language": {
"type": "string",
"description": "按内容语言筛选结果。"
},
"tag": {
"type": "string",
"description": "按标签筛选结果。"
},
"groups": {
"type": "array",
"items": {
"type": "string"
},
"description": "调用方获授权访问的可选文档分组。当部署启用 `auth` 或 `userAuth` 时，结果仅限于指定分组可查看的页面。在受保护的部署上如果省略或为空，则结果仅包含公开页面。"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "搜索结果",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "来自文档中匹配的内容。"
},
"path": {
"type": "string",
"description": "源文档所在的路径或 URL。"
},
"metadata": {
"type": "object",
"description": "与搜索结果相关的附加 metadata。"
}
}
}
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Authorization 请求头需要携带 Bearer 令牌。请使用 assistant API 密钥。你可以在控制台的 [API 密钥页面](https://dashboard.mintlify.com/settings/organization/api-keys) 中生成一个。在生产环境中，请通过你的后端代理请求，而不是将密钥嵌入到客户端代码中。"
}
}
}
}
Reference in New Issue View Git Blame Copy Permalink