mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
51f9be82f8
* docs: document assistant link deflection and thread transcript endpoint * fix: correct link deflection anchor in assistant thread page --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
830 lines
26 KiB
JSON
830 lines
26 KiB
JSON
{
|
||
"openapi": "3.1.0",
|
||
"info": {
|
||
"title": "Mintlify Analytics Export API",
|
||
"version": "1.0.0",
|
||
"description": "用于导出文档 Analytics 数据的 API"
|
||
},
|
||
"servers": [
|
||
{
|
||
"url": "https://api.mintlify.com",
|
||
"description": "生产环境"
|
||
}
|
||
],
|
||
"components": {
|
||
"securitySchemes": {
|
||
"bearerAuth": {
|
||
"type": "http",
|
||
"scheme": "bearer",
|
||
"description": "Authorization 请求头需要使用 Bearer 令牌。请使用管理员 API 密钥。这是仅供服务端使用的机密密钥。你可以在控制台的 [API 密钥页面](https://dashboard.mintlify.com/settings/organization/api-keys) 中生成一个。"
|
||
}
|
||
},
|
||
"schemas": {
|
||
"projectId": {
|
||
"type": "string",
|
||
"description": "你的项目 ID，可在控制台的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面中复制。"
|
||
},
|
||
"FeedbackResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"feedback": {
|
||
"type": "array",
|
||
"description": "反馈条目的列表。",
|
||
"items": {
|
||
"anyOf": [
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "反馈的唯一标识符。"
|
||
},
|
||
"path": {
|
||
"type": "string",
|
||
"description": "源文档的路径或 URL。"
|
||
},
|
||
"comment": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "用户提交的反馈内容。"
|
||
},
|
||
"createdAt": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "提交该反馈时的时间戳。"
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"enum": [
|
||
"code_snippet",
|
||
"contextual",
|
||
"agent",
|
||
"thumbs_only"
|
||
],
|
||
"description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈，`agent` 表示由第三方 AI Agent 提交的反馈，`thumbs_only` 表示点赞/点踩投票。"
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": [
|
||
"pending",
|
||
"in_progress",
|
||
"resolved",
|
||
"dismissed"
|
||
],
|
||
"description": "该反馈当前的审核状态。"
|
||
},
|
||
"helpful": {
|
||
"type": "boolean",
|
||
"description": "用户是否认为该内容有帮助。"
|
||
},
|
||
"contact": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "用户提供的用于后续联系的电子邮件地址。"
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"path",
|
||
"comment",
|
||
"createdAt",
|
||
"source",
|
||
"status",
|
||
"helpful",
|
||
"contact"
|
||
],
|
||
"description": "当来源为 `contextual` 时返回。包含用户是否认为页面有帮助以及可选的联系邮箱。"
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "该反馈的唯一标识符。"
|
||
},
|
||
"path": {
|
||
"type": "string",
|
||
"description": "源文档的路径或 URL。"
|
||
},
|
||
"comment": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "用户提交的反馈内容。"
|
||
},
|
||
"createdAt": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "提交该反馈时的时间戳。"
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"enum": [
|
||
"code_snippet",
|
||
"contextual",
|
||
"agent",
|
||
"thumbs_only"
|
||
],
|
||
"description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈，`agent` 表示由第三方 AI Agent 提交的反馈，`thumbs_only` 表示点赞/点踩投票。"
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": [
|
||
"pending",
|
||
"in_progress",
|
||
"resolved",
|
||
"dismissed"
|
||
],
|
||
"description": "反馈当前的审核状态。"
|
||
},
|
||
"code": {
|
||
"type": "string",
|
||
"description": "与该反馈相关的代码片段。"
|
||
},
|
||
"filename": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "与代码片段关联的文件名。"
|
||
},
|
||
"lang": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "代码片段所使用的编程语言。"
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"path",
|
||
"comment",
|
||
"createdAt",
|
||
"source",
|
||
"status",
|
||
"code",
|
||
"filename",
|
||
"lang"
|
||
],
|
||
"description": "当来源为 `code_snippet` 时返回。包含反馈所涉及代码片段的代码、文件名和编程语言。"
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "反馈的唯一标识符。"
|
||
},
|
||
"path": {
|
||
"type": "string",
|
||
"description": "源文档的路径或 URL。"
|
||
},
|
||
"comment": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "用户反馈评论的正文内容。"
|
||
},
|
||
"createdAt": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "提交该反馈时的时间戳。"
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"enum": [
|
||
"code_snippet",
|
||
"contextual",
|
||
"agent",
|
||
"thumbs_only"
|
||
],
|
||
"description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈，`agent` 表示由第三方 AI Agent 提交的反馈，`thumbs_only` 表示点赞/点踩投票。"
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": [
|
||
"pending",
|
||
"in_progress",
|
||
"resolved",
|
||
"dismissed"
|
||
],
|
||
"description": "反馈当前的审核状态。"
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"path",
|
||
"comment",
|
||
"createdAt",
|
||
"source",
|
||
"status"
|
||
],
|
||
"description": "当来源为 `agent` 或 `thumbs_only` 时返回。仅包含基本反馈字段。"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"nextCursor": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "用于获取下一页结果的游标。如果没有更多结果，则为 null。"
|
||
},
|
||
"hasMore": {
|
||
"type": "boolean",
|
||
"description": "当前页之后是否还有更多结果。"
|
||
}
|
||
},
|
||
"required": [
|
||
"feedback",
|
||
"nextCursor",
|
||
"hasMore"
|
||
]
|
||
},
|
||
"AnalyticsErrorResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"error": {
|
||
"type": "string",
|
||
"description": "描述错误原因的错误信息。"
|
||
},
|
||
"details": {
|
||
"type": "array",
|
||
"description": "关于该错误的其他详细信息。",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"message": {
|
||
"type": "string",
|
||
"description": "对某个特定校验或处理错误的说明。"
|
||
}
|
||
},
|
||
"required": [
|
||
"message"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"error"
|
||
]
|
||
},
|
||
"AssistantThreadResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"threadId": {
|
||
"type": "string",
|
||
"description": "AI 助手会话线程标识符（ULID）。"
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"description": "线程创建时间戳。"
|
||
},
|
||
"messages": {
|
||
"type": "array",
|
||
"description": "该线程中按顺序排列的消息列表。",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "消息的唯一标识符。"
|
||
},
|
||
"role": {
|
||
"type": "string",
|
||
"enum": [
|
||
"user",
|
||
"assistant"
|
||
],
|
||
"description": "该消息由用户还是 AI 助手发送。"
|
||
},
|
||
"content": {
|
||
"type": "string",
|
||
"description": "消息的文本内容。"
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"description": "消息发送时间戳。"
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"role",
|
||
"content",
|
||
"createdAt"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"threadId",
|
||
"createdAt",
|
||
"messages"
|
||
]
|
||
},
|
||
"AssistantCallerStatsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"web": {
|
||
"type": "number",
|
||
"description": "来自网页端（文档站点）的助手查询次数。"
|
||
},
|
||
"api": {
|
||
"type": "number",
|
||
"description": "来自 API 调用的助手查询次数。"
|
||
},
|
||
"other": {
|
||
"type": "number",
|
||
"description": "来自其他来源（例如集成、SDK）的助手查询次数。"
|
||
},
|
||
"total": {
|
||
"type": "number",
|
||
"description": "所有调用方类型的助手查询总数。"
|
||
}
|
||
},
|
||
"required": [
|
||
"web",
|
||
"api",
|
||
"other",
|
||
"total"
|
||
]
|
||
},
|
||
"AssistantConversationsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"conversations": {
|
||
"type": "array",
|
||
"description": "AI 助手会话列表。",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "会话的唯一标识符。"
|
||
},
|
||
"timestamp": {
|
||
"type": "string",
|
||
"description": "开启该轮次的用户消息的时间戳。"
|
||
},
|
||
"query": {
|
||
"type": "string",
|
||
"description": "用户向 AI 助手提出的问题。"
|
||
},
|
||
"response": {
|
||
"type": "string",
|
||
"description": "AI 助手的回答。对于澄清问题轮次，这是 AI 助手向用户提出的追问。"
|
||
},
|
||
"responseType": {
|
||
"type": "string",
|
||
"enum": [
|
||
"answer",
|
||
"clarifying_question"
|
||
],
|
||
"description": "返回给用户的响应类型。`answer` 表示最终回答。`clarifying_question` 表示 AI 助手向用户提出了追问，而没有直接作答。当该字段不存在时，默认值为 `answer`。"
|
||
},
|
||
"sources": {
|
||
"type": "array",
|
||
"description": "在回答中被引用的文档页面。",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"title": {
|
||
"type": "string",
|
||
"description": "被引用文档页面的标题。"
|
||
},
|
||
"url": {
|
||
"type": "string",
|
||
"description": "被引用文档页面的 URL。"
|
||
}
|
||
},
|
||
"required": [
|
||
"title",
|
||
"url"
|
||
]
|
||
}
|
||
},
|
||
"queryCategory": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "会话自动分配的分类分组（如适用）。"
|
||
},
|
||
"pageUrl": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "会话开始时所在文档页面的完整 URL。如果没有捕获页面路径，则为 null。"
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"timestamp",
|
||
"query",
|
||
"response",
|
||
"sources",
|
||
"queryCategory",
|
||
"pageUrl"
|
||
]
|
||
}
|
||
},
|
||
"nextCursor": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "用于获取下一页结果的游标；如果没有更多结果则为 null。"
|
||
},
|
||
"hasMore": {
|
||
"type": "boolean",
|
||
"description": "指示在当前页之外是否还有更多可用结果。"
|
||
}
|
||
},
|
||
"required": [
|
||
"conversations",
|
||
"nextCursor",
|
||
"hasMore"
|
||
]
|
||
}
|
||
},
|
||
"parameters": {
|
||
"projectId": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/projectId"
|
||
},
|
||
"required": true,
|
||
"name": "projectId",
|
||
"in": "path"
|
||
}
|
||
}
|
||
},
|
||
"paths": {
|
||
"/v1/analytics/{projectId}/feedback": {
|
||
"get": {
|
||
"summary": "获取用户反馈列表",
|
||
"description": "返回按页划分的用户反馈，并支持可选筛选条件\n\n使用管理员 API 密钥进行身份验证。",
|
||
"tags": [
|
||
"Analytics"
|
||
],
|
||
"security": [
|
||
{
|
||
"bearerAuth": []
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"$ref": "#/components/parameters/projectId"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "ISO 8601 或 YYYY-MM-DD 格式的日期",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateFrom",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "ISO 8601 或 YYYY-MM-DD 格式的日期。`dateTo` 为不包含在内的上界。结果包括指定日期之前的所有日期，但不包括指定日期当天。",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateTo",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"enum": [
|
||
"code_snippet",
|
||
"contextual",
|
||
"agent",
|
||
"thumbs_only"
|
||
],
|
||
"description": "按反馈来源进行筛选"
|
||
},
|
||
"required": false,
|
||
"name": "source",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "用于筛选的以逗号分隔的状态列表"
|
||
},
|
||
"required": false,
|
||
"name": "status",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "number",
|
||
"minimum": 1,
|
||
"maximum": 100,
|
||
"default": 50,
|
||
"description": "每页返回的最大结果数"
|
||
},
|
||
"required": false,
|
||
"name": "limit",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "分页游标"
|
||
},
|
||
"required": false,
|
||
"name": "cursor",
|
||
"in": "query"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "包含分页信息的反馈数据",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/FeedbackResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "无效的查询参数",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/v1/analytics/{projectId}/assistant/threads/{threadId}": {
|
||
"get": {
|
||
"summary": "获取 AI 助手会话线程",
|
||
"description": "返回单个 AI 助手会话线程的完整消息转录。线程 ID 可从 AI 助手会话端点获取，或作为 AI 助手链接转接支持 URL 上追加的 `threadId` 查询参数获取。\n\n使用管理员 API 密钥进行身份验证。",
|
||
"tags": [
|
||
"Analytics"
|
||
],
|
||
"security": [
|
||
{
|
||
"bearerAuth": []
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"$ref": "#/components/parameters/projectId"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "AI 助手会话线程 ID（ULID）。"
|
||
},
|
||
"required": true,
|
||
"name": "threadId",
|
||
"in": "path"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "会话转录",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AssistantThreadResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "线程 ID 无效",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "未找到线程",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/v1/analytics/{projectId}/assistant/caller-stats": {
|
||
"get": {
|
||
"summary": "获取 AI 助手调用方统计",
|
||
"description": "返回指定日期范围内按调用方类型（网页端、API 和其他）划分的助手查询次数明细。\n\n使用管理员 API 密钥进行身份验证。",
|
||
"tags": [
|
||
"Analytics"
|
||
],
|
||
"security": [
|
||
{
|
||
"bearerAuth": []
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"$ref": "#/components/parameters/projectId"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "ISO 8601 或 YYYY-MM-DD 格式的日期",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateFrom",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "ISO 8601 或 YYYY-MM-DD 格式的日期。`dateTo` 为不包含在内的上限。结果将包含早于该日期的记录，但不包含该日期当天的记录。",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateTo",
|
||
"in": "query"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "按调用方类型划分的助手查询次数",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AssistantCallerStatsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "无效的查询参数",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/v1/analytics/{projectId}/assistant": {
|
||
"get": {
|
||
"summary": "获取 AI 助手会话记录",
|
||
"description": "返回分页后的 AI 助手会话历史\n\n使用管理员 API 密钥进行身份验证。",
|
||
"tags": [
|
||
"Analytics"
|
||
],
|
||
"security": [
|
||
{
|
||
"bearerAuth": []
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"$ref": "#/components/parameters/projectId"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "ISO 8601 或 YYYY-MM-DD 格式的日期",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateFrom",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "ISO 8601 或 YYYY-MM-DD 格式的日期。`dateTo` 为不包含在内的上限。结果将包含早于该日期的记录，但不包含该日期当天的记录。",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateTo",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "number",
|
||
"minimum": 1,
|
||
"maximum": 1000,
|
||
"default": 100,
|
||
"description": "每页返回的最大结果数"
|
||
},
|
||
"required": false,
|
||
"name": "limit",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "ulid",
|
||
"description": "分页游标（ULID 格式）"
|
||
},
|
||
"required": false,
|
||
"name": "cursor",
|
||
"in": "query"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "包含分页信息的会话数据",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AssistantConversationsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "无效的查询参数",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"webhooks": {}
|
||
}
|