mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
41af0c5388
* docs: remove retired mint deslop CLI command * docs: remove retired deslop API endpoint and references --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
681 lines
25 KiB
JSON
681 lines
25 KiB
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/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": {
|
||
"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) 中生成一个。"
|
||
}
|
||
}
|
||
}
|
||
}
|