mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
19d89bf8eb
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
581 lines
18 KiB
JSON
581 lines
18 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 Token。请使用管理员 API key（以 `mint_` 开头）。这是仅供服务端使用的密钥。你可以在控制台的 [API keys 页面](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"
|
||
],
|
||
"description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈。"
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": [
|
||
"pending",
|
||
"in_progress",
|
||
"resolved",
|
||
"dismissed"
|
||
],
|
||
"description": "该反馈当前的审核状态。"
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"path",
|
||
"comment",
|
||
"createdAt",
|
||
"source",
|
||
"status"
|
||
]
|
||
},
|
||
{
|
||
"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"
|
||
],
|
||
"description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈。"
|
||
},
|
||
"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"
|
||
]
|
||
},
|
||
{
|
||
"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"
|
||
],
|
||
"description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示针对整页的反馈。"
|
||
},
|
||
"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"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"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"
|
||
]
|
||
},
|
||
"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 助手的回答。"
|
||
},
|
||
"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": "会话自动分配的分类分组（如适用）。"
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"timestamp",
|
||
"query",
|
||
"response",
|
||
"sources",
|
||
"queryCategory"
|
||
]
|
||
}
|
||
},
|
||
"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": {
|
||
"/api/external/v1/analytics/{projectId}/feedback": {
|
||
"get": {
|
||
"summary": "获取用户反馈",
|
||
"description": "返回用户反馈的分页结果，并可按条件筛选。",
|
||
"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 格式的日期",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateTo",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"enum": [
|
||
"code_snippet",
|
||
"contextual"
|
||
],
|
||
"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"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/external/v1/analytics/{projectId}/assistant": {
|
||
"get": {
|
||
"summary": "获取 AI 助手会话记录",
|
||
"description": "返回分页后的 AI 助手对话历史",
|
||
"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 格式的日期",
|
||
"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": "无效的 query 参数",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"webhooks": {}
|
||
} |