mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
d043cf3254
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
801 lines
34 KiB
JSON
801 lines
34 KiB
JSON
{
|
||
"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。",
|
||
"parameters": [
|
||
{
|
||
"name": "domain",
|
||
"in": "path",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "在你的 `domain.mintlify.app` 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": "用于搜索的可选筛选条件。"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"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 助手消息 v2",
|
||
"description": "针对指定的 domain，从 AI 助手生成一条回复消息。适用于 AI SDK v5 及更高版本。",
|
||
"parameters": [
|
||
{
|
||
"name": "domain",
|
||
"in": "path",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "来自你的 `domain.mintlify.app` 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 助手的可选上下文信息数组。"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"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/search/{domain}": {
|
||
"post": {
|
||
"x-mint": {
|
||
"mcp": {
|
||
"enabled": true
|
||
}
|
||
},
|
||
"summary": "搜索文档",
|
||
"description": "在你的文档中执行语义搜索和关键词搜索，并支持可配置的过滤和分页。",
|
||
"parameters": [
|
||
{
|
||
"name": "domain",
|
||
"in": "path",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "来自你的 `domain.mintlify.app` 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": "number",
|
||
"default": 10,
|
||
"description": "要返回的搜索结果数量。若未指定，默认为 10。"
|
||
},
|
||
"filter": {
|
||
"type": "object",
|
||
"description": "用于缩小搜索结果范围的可选过滤参数。",
|
||
"properties": {
|
||
"version": {
|
||
"type": "string",
|
||
"description": "按文档版本筛选结果。"
|
||
},
|
||
"language": {
|
||
"type": "string",
|
||
"description": "按内容语言筛选结果。"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"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 令牌。请使用以 `mint_dsc_` 为前缀的 AI 助手 API 密钥。它是一个可以安全用于客户端代码的公用密钥。你可以在控制台的 [API 密钥页面](https://dashboard.mintlify.com/settings/organization/api-keys) 中生成它。"
|
||
}
|
||
}
|
||
}
|
||
} |