mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
1876c01f16
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
517 lines
22 KiB
JSON
517 lines
22 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/v1"
|
||
}
|
||
],
|
||
"security": [
|
||
{
|
||
"bearerAuth": []
|
||
}
|
||
],
|
||
"paths": {
|
||
"/assistant/{domain}/message": {
|
||
"post": {
|
||
"summary": "AI 助手的消息",
|
||
"description": "为指定的 domain 生成一条来自 AI 助手的回复消息。",
|
||
"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' 时，threadId 会在响应中以 event.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 hook 提供的 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)。"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/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 中的 domain 标识符。可以在控制台 URL 的末尾找到。例如，`dashboard.mintlify.com/organization/domain` 的 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 令牌。有关如何获取 API key 的详细信息，请参阅 [API 认证](/api/introduction#authentication) 文档。"
|
||
}
|
||
}
|
||
}
|
||
} |