mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
76b0d76917
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
699 lines
22 KiB
JSON
699 lines
22 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",
|
||
"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"
|
||
]
|
||
},
|
||
"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 助手的回答。"
|
||
},
|
||
"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": "返回按页划分的用户反馈，并支持可选筛选条件",
|
||
"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/caller-stats": {
|
||
"get": {
|
||
"summary": "获取 AI 助手调用方统计",
|
||
"description": "返回指定日期范围内按调用方类型（网页端、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 助手会话历史",
|
||
"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": {}
|
||
}
|