mintlify__docs/zh/admin-openapi.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "Mintlify Admin API",
    "description": "用于管理操作的 API，包括文档更新和代理管理。",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.mintlify.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/deslop/{projectId}": {
      "post": {
        "summary": "检测页面中 AI 风格的文本",
        "description": "分析页面中是否存在 AI 生成的文本，并返回被标记的段落以及建议的改写。每检查一个页面消耗 1 个 AI 积分。少于 50 个词的页面会被跳过。针对每个客户端 IP 地址每分钟最多 30 个请求。",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "你的项目 ID。可从你的控制台中的 [API keys](https://app.mintlify.com/settings/organization/api-keys) 页面复制。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["path", "content"],
                "properties": {
                  "path": {
                    "type": "string",
                    "minLength": 1,
                    "description": "页面的仓库相对路径，仅用于报告。"
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 1000000,
                    "description": "要检查的页面的原始 MDX 或 Markdown 内容。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "页面已被检查，或因过短而被跳过。",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/DeslopResult" } }
            }
          },
          "400": {
            "description": "请求体无效。",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "402": {
            "description": "AI 积分不足。",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": {
            "description": "超出速率限制。",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "请求过多，请稍后再试。"
                }
              }
            }
          },
          "503": {
            "description": "检测暂时不可用。不扣除积分。",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "500": {
            "description": "处理页面时发生了意外错误。"
          }
        }
      }
    },
    "/v1/agent/{projectId}/job": {
      "post": {
        "summary": "创建代理任务（v1）",
        "deprecated": true,
        "description": "已废弃：请改用 [v2 create agent job](/api/agent/v2/create-agent-job)。此操作会创建一个新的代理任务，该任务可根据提供的消息和 Git branch 信息生成并编辑文档。\n\n使用管理员 API 密钥进行身份验证。",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "你的项目 ID。可从你的控制台中的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面复制。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "branch": {
                    "type": "string",
                    "description": "代理应处理的 Git branch 名称。如省略，代理会根据消息内容生成一个 branch 名称。"
                  },
                  "messages": {
                    "type": "array",
                    "description": "提供给代理的消息列表。系统始终会自动在前面添加一条默认的系统提示，因此通常只需包含用户消息。",
                    "items": {
                      "type": "object",
                      "required": [
                        "role",
                        "content"
                      ],
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "system",
                            "user",
                            "assistant"
                          ],
                          "description": "消息发送者的角色。对于任务说明，请使用 `user`。使用 `system` 添加补充说明，这些说明会附加在默认系统提示之后（不会替换默认系统提示）。使用 `assistant` 提供用于少样本提示的 AI 助手示例回复。"
                        },
                        "content": {
                          "type": "string",
                          "description": "消息的 content。"
                        }
                      }
                    }
                  },
                  "asDraft": {
                    "type": "boolean",
                    "default": false,
                    "description": "控制拉取请求（PR；亦称“合并请求”/Merge Request）是以草稿模式还是非草稿模式创建。为 true 时，会创建草稿拉取请求（PR；亦称“合并请求”/Merge Request）。为 false 时（默认），会创建可供评审的常规拉取请求（PR；亦称“合并请求”/Merge Request）。"
                  },
                  "model": {
                    "type": "string",
                    "enum": [
                      "sonnet",
                      "opus"
                    ],
                    "default": "sonnet",
                    "description": "用于代理任务的 AI 模型。使用 `sonnet` 可获得更快、更具成本效益的处理。使用 `opus` 可获得能力更强但速度较慢的处理。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "代理任务创建成功。返回 Server-Sent Events 流式响应。",
            "headers": {
              "X-Session-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "已创建的代理任务的唯一会话标识符。"
              },
              "X-Branch-Name": {
                "schema": {
                  "type": "string"
                },
                "description": "代理正在进行更改的 Git 分支名称。"
              }
            },
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "包含代理任务执行详情和结果的 Server-Sent Events 流。"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agent/{projectId}/job/{id}": {
      "get": {
        "summary": "按 ID 获取代理任务（v1）",
        "deprecated": true,
        "description": "已废弃：请改用 [v2 get agent job](/api/agent/v2/get-agent-job)。按 ID 检索特定代理任务的详细信息和状态。\n\n使用管理员 API 密钥进行身份验证。",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "你的项目 ID。可从你的控制台中的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面复制。"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "要检索的代理任务的唯一标识符。"
          }
        ],
        "responses": {
          "200": {
            "description": "已成功检索代理任务详细信息",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sessionId": {
                      "type": "string",
                      "description": "此会话所属的子域。"
                    },
                    "subdomain": {
                      "type": "string",
                      "description": "此会话所属的子域。"
                    },
                    "branch": {
                      "type": "string",
                      "description": "进行更改的 Git branch 名称。",
                      "nullable": true
                    },
                    "haulted": {
                      "type": "boolean",
                      "description": "会话执行是否已中止。"
                    },
                    "haultReason": {
                      "type": "string",
                      "enum": [
                        "completed",
                        "github_missconfigured",
                        "error",
                        "processing",
                        "interrupted"
                      ],
                      "description": "会话中止的原因。`processing` 表示任务仍在运行。`interrupted` 表示任务被手动中断。"
                    },
                    "pullRequestLink": {
                      "type": "string",
                      "description": "已创建的拉取请求（PR；亦称“合并请求”/Merge Request）链接。"
                    },
                    "messageToUser": {
                      "type": "string",
                      "description": "向用户说明会话结果的消息。"
                    },
                    "todos": {
                      "type": "array",
                      "description": "会话中的待办事项列表。",
                      "items": {
                        "type": "object",
                        "properties": {
                          "content": {
                            "type": "string",
                            "description": "任务的简要说明。"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "in_progress",
                              "completed",
                              "cancelled"
                            ],
                            "description": "任务的当前状态。"
                          },
                          "priority": {
                            "type": "string",
                            "enum": [
                              "high",
                              "medium",
                              "low"
                            ],
                            "description": "任务的优先级。"
                          },
                          "id": {
                            "type": "string",
                            "description": "待办事项的唯一标识符。"
                          }
                        }
                      }
                    },
                    "userId": {
                      "type": "string",
                      "description": "创建此会话的用户 ID（如有）"
                    },
                    "title": {
                      "type": "string",
                      "description": "用于概括代理任务的生成标题"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "会话创建时的时间戳。"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/agent/{projectId}/jobs": {
      "get": {
        "summary": "获取所有代理任务（v1）",
        "deprecated": true,
        "description": "已废弃：请改用 [v2 get agent job](/api/agent/v2/get-agent-job)。检索指定 domain 的所有代理任务，包括其状态和详细信息。\n\n使用管理员 API 密钥进行身份验证。",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "你的项目 ID。可从你的控制台中的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面复制。"
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "用于分页的跳过结果数。"
          },
          {
            "name": "take",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 12
            },
            "description": "返回的结果数量。最大 100。"
          }
        ],
        "responses": {
          "200": {
            "description": "已成功检索所有代理任务",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "allSessions": {
                      "type": "array",
                      "description": "该 domain 的所有代理会话数组。",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sessionId": {
                            "type": "string",
                            "description": "此会话所属的子域。"
                          },
                          "subdomain": {
                            "type": "string",
                            "description": "此会话所属的子域。"
                          },
                          "branch": {
                            "type": "string",
                            "description": "进行更改的 Git branch 名称。",
                            "nullable": true
                          },
                          "haulted": {
                            "type": "boolean",
                            "description": "会话执行是否已中止"
                          },
                          "haultReason": {
                            "type": "string",
                            "enum": [
                              "completed",
                              "github_missconfigured",
                              "error",
                              "processing",
                              "interrupted"
                            ],
                            "description": "会话中止的原因。`processing` 表示任务仍在运行。`interrupted` 表示任务被手动中断。"
                          },
                          "pullRequestLink": {
                            "type": "string",
                            "description": "已创建的拉取请求（PR；亦称“合并请求”/Merge Request）链接"
                          },
                          "messageToUser": {
                            "type": "string",
                            "description": "向用户说明会话结果的消息。"
                          },
                          "todos": {
                            "type": "array",
                            "description": "会话中的待办事项列表。",
                            "items": {
                              "type": "object",
                              "properties": {
                                "content": {
                                  "type": "string",
                                  "description": "任务的简要说明。"
                                },
                                "status": {
                                  "type": "string",
                                  "enum": [
                                    "pending",
                                    "in_progress",
                                    "completed",
                                    "cancelled"
                                  ],
                                  "description": "任务的当前状态。"
                                },
                                "priority": {
                                  "type": "string",
                                  "enum": [
                                    "high",
                                    "medium",
                                    "low"
                                  ],
                                  "description": "任务的优先级。"
                                },
                                "id": {
                                  "type": "string",
                                  "description": "待办事项的唯一标识符。"
                                }
                              }
                            }
                          },
                          "userId": {
                            "type": "string",
                            "description": "创建此会话的用户 ID（如有）。"
                          },
                          "title": {
                            "type": "string",
                            "description": "用于概括代理任务的生成标题"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time",
                            "description": "会话创建时的时间戳。"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/agent/{projectId}/job": {
      "post": {
        "summary": "创建代理任务",
        "description": "创建一个在后台运行的新代理作业。该作业会异步处理提示词——轮询 get job 端点以跟踪进度。如果代理成功编辑文件，则会自动创建拉取请求（PR；亦称“合并请求”/Merge Request）。\n\n使用管理员 API 密钥进行身份验证。",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "你的项目 ID。可从你的控制台中的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面复制。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt"
                ],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "minLength": 1,
                    "description": "供代理执行的指令。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "代理作业创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentJob"
                }
              }
            }
          },
          "400": {
            "description": "无效请求",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出速率限制",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v2/agent/{projectId}/job/{id}": {
      "get": {
        "summary": "获取代理任务",
        "description": "检索代理作业的当前状态和详细信息。轮询此端点以跟踪作业进度。\n\n使用管理员 API 密钥进行身份验证。",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "你的项目 ID。可从你的控制台中的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面复制。"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "代理任务的唯一标识符。"
          }
        ],
        "responses": {
          "200": {
            "description": "代理任务详情",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentJob"
                }
              }
            }
          },
          "404": {
            "description": "未找到作业",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v2/agent/{projectId}/job/{id}/message": {
      "post": {
        "summary": "发送后续消息",
        "description": "向现有代理任务发送后续消息。该消息将异步处理——请轮询 get job 端点以跟踪进度。\n\n使用管理员 API 密钥进行身份验证。",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "你的项目 ID。可从你的控制台中的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面复制。"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "要向其发送消息的代理任务的唯一标识符。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt"
                ],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "minLength": 1,
                    "description": "发送给代理的后续指令。"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "消息发送成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentJob"
                }
              }
            }
          },
          "400": {
            "description": "无效请求",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "未找到作业",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出速率限制",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DeslopResult": {
        "type": "object",
        "required": ["path", "skipped", "creditsCharged"],
        "properties": {
          "path": { "type": "string", "description": "请求中传入的 path。" },
          "skipped": {
            "type": "string",
            "nullable": true,
            "enum": ["too_short", null],
            "description": "页面被跳过的原因；如果页面已被检查则为 null。`too_short` 表示页面正文少于 50 个词，且未被计费。"
          },
          "predictionShort": {
            "type": "string",
            "enum": ["AI", "AI-Assisted", "Human", "Mixed"],
            "description": "页面的整体判定结果。仅在页面已被检查时出现。"
          },
          "fractionAi": { "type": "number", "description": "被识别为 AI 生成的页面比例（0-1）。" },
          "fractionAiAssisted": { "type": "number", "description": "被识别为 AI 辅助的比例（0-1）。" },
          "fractionHuman": { "type": "number", "description": "被识别为人类撰写的比例（0-1）。" },
          "windows": {
            "type": "array",
            "description": "被标记的（非人类）段落。仅在页面已被检查时出现。",
            "items": { "$ref": "#/components/schemas/DeslopWindow" }
          },
          "creditsCharged": { "type": "integer", "description": "本次请求扣除的 AI 积分数（被跳过时为 0）。" }
        }
      },
      "DeslopWindow": {
        "type": "object",
        "required": ["text", "label", "aiAssistanceScore", "startLine", "endLine"],
        "properties": {
          "text": { "type": "string", "description": "被标记的段落文本。" },
          "label": { "type": "string", "description": "段落的检测标签，例如 `AI-Generated`。" },
          "aiAssistanceScore": { "type": "number", "description": "段落的 AI 辅助评分（0-1）。" },
          "confidence": {
            "description": "检测置信度，返回值可能为 `High` 之类的标签或数值。",
            "oneOf": [
              { "type": "string" },
              { "type": "number" }
            ]
          },
          "startLine": { "type": "integer", "description": "段落在原始内容中的起始行号（从 1 开始）。" },
          "endLine": { "type": "integer", "description": "段落在原始内容中的结束行号（从 1 开始）。" },
          "rewrites": {
            "type": "array",
            "description": "建议的人类风格改写。",
            "items": {
              "type": "object",
              "required": ["text", "rationale"],
              "properties": {
                "text": { "type": "string", "description": "改写后的段落。" },
                "rationale": { "type": "string", "description": "该改写更贴近人类风格的原因。" }
              }
            }
          }
        }
      },
      "AgentJob": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "代理任务的唯一标识符。"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "completed",
              "archived",
              "failed"
            ],
            "description": "作业的当前状态。`active`——代理当前正在处理提示词。`completed`——代理已成功完成，并且可能已创建 PR（请检查 `prLink`）。`archived`——作业已归档。`failed`——代理遇到了不可恢复的错误。请持续轮询，直到状态变为 `completed`、`archived` 或 `failed`。"
          },
          "source": {
            "type": "object",
            "description": "源存储库信息。",
            "properties": {
              "repository": {
                "type": "string",
                "description": "GitHub 存储库的完整 URL。"
              },
              "ref": {
                "type": "string",
                "description": "代理正在处理的 Git branch。",
                "nullable": true
              }
            }
          },
          "model": {
            "type": "string",
            "description": "此作业使用的 AI 模型。"
          },
          "prLink": {
            "type": "string",
            "format": "uri",
            "example": "https://github.com/org/repo/pull/123",
            "description": "由代理创建的 GitHub 拉取请求（PR；亦称“合并请求”/Merge Request）URL。作业仍处于 `active` 状态或没有文件变更时，该值为 `null`。代理成功创建 PR 后，此字段会被填充。",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "作业创建时的时间戳。"
          },
          "archivedAt": {
            "type": "string",
            "format": "date-time",
            "description": "作业归档时的时间戳。",
            "nullable": true
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "错误消息。"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization 请求头需要使用 Bearer 令牌。请使用管理员 API 密钥。这是仅供服务端使用的机密密钥。你可以在控制台的 [API 密钥页面](https://dashboard.mintlify.com/settings/organization/api-keys) 中生成一个。"
      }
    }
  }
}